Quick Start & Setup
Relevant source files
The following files were used as context for generating this wiki page:
n8n is a workflow automation platform that enables technical teams to build integrations using a combination of a visual interface and custom code. The project uses a monorepo structure managed by pnpm workspaces, consisting of a Node.js backend, a Vue.js frontend, and an extensible node-based engine.
This guide covers the initial setup procedures for local development, Docker deployment, and specialized environments like node creation or E2E testing.
Sources: AGENTS.md:6-10, docker/images/n8n/README.md:3-7
Local Development Setup
To modify or extend n8n, you must install dependencies and link packages correctly. The project requires Node.js version 24 or newer and pnpm version 12.4.2.
System Requirements
| Tool | Requirement | Purpose |
|---|---|---|
| Node.js | v24+ | Runtime environment |
| pnpm | 12.4.2 | Package and workspace management |
| build-essential | Required (Debian/Ubuntu) | Compiling native dependencies |
| Python | Required | Build tool dependency |
Sources: CONTRIBUTING.md:46-75
Installation Steps
- Clone the repository and navigate to the root folder.
- Install all module dependencies and establish workspace links:
pnpm install - Build the source code across all packages:
pnpm build - Start the n8n instance:
pnpm start
Sources: CONTRIBUTING.md:120-136
Development Workflow
For active iteration, n8n provides specific commands to watch backend and frontend changes. The backend typically runs on port 5678, while the editor UI runs on port 8080.
The diagram shows the parallel execution of backend and frontend development servers after the initial build.
Sources: CONTRIBUTING.md:144-162
Docker Deployment
Docker is the recommended method for hosting n8n in production or testing containerized environments. n8n requires a persistent volume to store the encryption key and SQLite database; losing the /home/node/.n8n folder makes existing credentials unreadable.
Quick Start with Docker
Execute the following commands to start a basic instance:
- Create a persistent volume:
docker volume create n8n_data - Run the container:
docker run -it --rm --name n8n -p 5678:5678 -v n8n_data:/home/node/.n8n docker.n8n.io/n8nio/n8n
Sources: docker/images/n8n/README.md:46-56
Configuration via Environment Variables
n8n supports various environment variables to customize the installation.
| Variable | Description | Example Value |
|---|---|---|
DB_TYPE | Specifies the database type | postgresdb |
GENERIC_TIMEZONE | Sets the timezone for nodes | Europe/Berlin |
N8N_PORT | Overrides the default port | 5678 |
N8N_USER_FOLDER | Custom location for user data | /home/node/.n8n |
Sources: docker/images/n8n/README.md:73-86, CONTRIBUTING.md:162-166
Custom Node Scaffolding
The @n8n/create-node tool simplifies the creation of community nodes by providing pre-configured templates.
Scaffolding Procedure
- Run the scaffolding tool:
npm create @n8n/node@latest - Choose between a Declarative template (best for simple REST APIs) or a Programmatic template (for complex logic).
- Navigate to the generated directory and start the dev server:
npm run dev
The npm run dev command in a node project automatically links the node to ~/.n8n-node-cli/.n8n/custom and enables hot reloading via N8N_DEV_RELOAD=true.
Sources: packages/@n8n/create-node/README.md:5-15, packages/@n8n/create-node/README.md:52-65, packages/nodes-base/AGENTS.md:12-25
E2E Test Environment Setup
n8n uses Playwright for end-to-end testing. These tests require a clean database state to ensure reliability.
Playwright Configuration
Developers should configure a local testing environment in /.vscode/settings.json:
{
"playwright.env": {
"N8N_BASE_URL": "http://localhost:5679",
"RESET_E2E_DB": "true"
}
}
Execution Flow
The sequence diagram illustrates the automated environment preparation before executing UI tests.
Sources: packages/quality/testing/playwright/CONTRIBUTING.md:11-30, CONTRIBUTING.md:377-385
Summary
Setting up n8n involves preparing a Node.js/pnpm environment for local development or utilizing Docker for containerized deployment. Developers can leverage specific toolchains like create-node for extensions and Playwright for quality assurance. Proper management of the encryption key and user data folder is critical across all setup methods to maintain credential integrity.
Sources: docker/images/n8n/README.md:58-64, AGENTS.md:164-170