Quick Start & Installation
Relevant source files
The following files were used as context for generating this wiki page:
n8n is a technical workflow automation platform that allows teams to build complex automations using a visual interface or direct code. It supports over 400 integrations and provides native AI capabilities through LangChain.
This page covers the setup for different use cases, including production deployment via Docker and local development environments for contributors. For information on extending the platform, see Create custom nodes.
Sources: docker/images/n8n/README.md, CONTRIBUTING.md:1-10
Docker Installation
Docker provides the fastest method for running a production-ready n8n instance. By default, n8n uses SQLite to store workflows and credentials.
Standard Setup
Run the following commands to create a persistent volume and start the n8n container:
docker volume create n8n_data
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:65-76
Database Configuration
While SQLite is the default, you can use PostgreSQL for better scalability. You must still persist the /home/node/.n8n folder to protect the encryption key used for credentials.
| Environment Variable | Description |
|---|---|
DB_TYPE | Set to postgresdb |
DB_POSTGRESDB_HOST | The hostname of your PostgreSQL instance |
DB_POSTGRESDB_PORT | The port for PostgreSQL (usually 5432) |
DB_POSTGRESDB_USER | The database user |
DB_POSTGRESDB_PASSWORD | The database password |
DB_POSTGRESDB_DATABASE | The name of the database |
Sources: docker/images/n8n/README.md:85-110
Development Environment Setup
To contribute to the n8n core or develop custom nodes, you must set up a local development environment. n8n uses a monorepo structure managed by pnpm.
Prerequisites
- Node.js: Version 24 or newer.
- pnpm: Version 12.4.2 (pinned in the root
package.json). - Build Tools:
build-essentialandpython(Debian/Ubuntu) orwindows-build-tools(Windows).
Sources: CONTRIBUTING.md:46-75
Installation Steps
- Fork and clone the repository.
- Install all dependencies:
pnpm install. - Build the project:
pnpm build. - Start the development server:
pnpm start.
Sources: CONTRIBUTING.md:131-158
Development Flow
The following diagram illustrates the local development lifecycle:
The pnpm dev:be and pnpm dev:fe:editor commands enable hot-reloading for the backend and Vue-based editor UI respectively.
Sources: CONTRIBUTING.md:166-180, AGENTS.md:150-160
Custom Node Scaffolding
The @n8n/create-node tool allows you to quickly scaffold new community nodes with best practices built-in.
- Initialize: Run
npm create @n8n/node@latest. - Follow Prompts: Select the node type (Declarative or Programmatic) and authentication method.
- Develop: Navigate to the folder and run
npm run devto start a local n8n instance with hot-reloading for the new node.
Sources: packages/@n8n/create-node/README.md:5-20, packages/@n8n/create-node/README.md:46-60
Automated Testing Setup
n8n uses Playwright for end-to-end (E2E) testing. This is critical for verifying installations and changes.
Configuration
Create a .vscode/settings.json file to configure the test environment:
{
"playwright.env": {
"N8N_BASE_URL": "http://localhost:5679",
"RESET_E2E_DB": "true"
}
}
Execution
- Local E2E:
pnpm --filter=n8n-playwright test:local - Unit Tests:
pnpm test(run from the root or a specific package folder).
Sources: packages/quality/testing/playwright/CONTRIBUTING.md:12-25, CONTRIBUTING.md:440-450
Summary
n8n offers flexible installation paths ranging from single-command Docker deployments for production to a robust pnpm-based monorepo for developers. By using persistent volumes in Docker and following the standardized development cycle, users can ensure their workflow data remains secure and their contributions meet project standards.