Skip to main content

​
Overview

What you’ll learn Set up a complete n8n development environment using Railway for quick deployment, Docker for local development, and configure CLI tools and databases for building custom nodes.
Get your development environment ready for building custom nodes and production workflows.

​
Quick Start with Railway

Fastest deployment path Production-ready n8n instance in 2 minutes with PostgreSQL, Redis, workers, automatic SSL, and built-in monitoring included.

Deploy n8n on Railway

One-click deploy with automatic SSL, managed databases, and scaling
 Railway handles infrastructure complexity so you can focus on building:
  • Automatic HTTPS/SSL
  • PostgreSQL database
  • Redis for queue management
  • Worker processes for scaling
  • Built-in monitoring and logs

​
Local Development Setup

Development options Docker (recommended), Docker Compose, npm/yarn, or source code - each offering different levels of control and complexity.

​
n8n CLI Setup

Command line tools Essential commands for starting n8n, creating custom nodes, and managing workflows. Install globally with npm for development access.
# Install n8n CLI globally
npm install -g n8n

# Create a new custom node project
npx n8n-node-dev new

# Commands available
n8n start          # Start n8n
n8n start --tunnel # Start with tunnel for webhooks
n8n export:workflow --all # Export all workflows
n8n import:workflow --input=file.json # Import workflows

​
Database Configuration

Database options PostgreSQL recommended for production, MySQL also supported. Both set up easily with Docker and configured via environment variables.
# Using Docker
docker run -d \
  --name n8n-postgres \
  -e POSTGRES_USER=n8n \
  -e POSTGRES_PASSWORD=n8n \
  -e POSTGRES_DB=n8n \
  -p 5432:5432 \
  postgres:15

# Configure n8n to use PostgreSQL
export DB_TYPE=postgresdb
export DB_POSTGRESDB_DATABASE=n8n
export DB_POSTGRESDB_HOST=localhost
export DB_POSTGRESDB_PORT=5432
export DB_POSTGRESDB_USER=n8n
export DB_POSTGRESDB_PASSWORD=n8n

​
MySQL Setup

# Using Docker
docker run -d \
  --name n8n-mysql \
  -e MYSQL_ROOT_PASSWORD=rootpassword \
  -e MYSQL_DATABASE=n8n \
  -e MYSQL_USER=n8n \
  -e MYSQL_PASSWORD=n8n \
  -p 3306:3306 \
  mysql:8

# Configure n8n
export DB_TYPE=mysqldb
export DB_MYSQLDB_DATABASE=n8n
export DB_MYSQLDB_HOST=localhost
export DB_MYSQLDB_PORT=3306
export DB_MYSQLDB_USER=n8n
export DB_MYSQLDB_PASSWORD=n8n

​
Environment Variables

Configuration settings Control n8n’s behavior - database connections, security, execution modes, logging, and custom extensions. Use .env file for development configuration.
# Basic Configuration
N8N_HOST=localhost
N8N_PORT=5678
N8N_PROTOCOL=http
NODE_ENV=development

# Database
DB_TYPE=postgresdb
DB_POSTGRESDB_DATABASE=n8n
DB_POSTGRESDB_HOST=localhost
DB_POSTGRESDB_PORT=5432
DB_POSTGRESDB_USER=n8n
DB_POSTGRESDB_PASSWORD=n8n

# Security
N8N_BASIC_AUTH_ACTIVE=true
N8N_BASIC_AUTH_USER=dev
N8N_BASIC_AUTH_PASSWORD=dev

# Execution
EXECUTIONS_MODE=regular
EXECUTIONS_TIMEOUT=3600
EXECUTIONS_TIMEOUT_MAX=7200

# Logs
N8N_LOG_LEVEL=info
N8N_LOG_OUTPUT=console

# Custom Nodes
N8N_CUSTOM_EXTENSIONS="/home/node/.n8n/custom"
EXTERNAL_HOOK_FILES="/home/node/.n8n/hooks"

# Development
N8N_DIAGNOSTICS_ENABLED=false
N8N_TEMPLATES_ENABLED=true
N8N_PERSONALIZATION_ENABLED=false

​
Testing Your Setup

Verification steps Check the health endpoint, create test workflows, and enable development features like tunnels and verbose logging to confirm everything works.

​
1. Verify n8n is Running

# Check if n8n is accessible
curl http://localhost:5678/healthz

# Expected response
{"status":"ok"}

​
2. Create Test Workflow

// test-workflow.js
const axios = require('axios');

const workflow = {
  name: 'Test Workflow',
  nodes: [
    {
      parameters: {},
      name: 'Start',
      type: 'n8n-nodes-base.start',
      position: [250, 300]
    }
  ],
  connections: {}
};

// Import via API
axios.post('http://localhost:5678/api/v1/workflows', workflow, {
  headers: {
    'Authorization': 'Basic ' + Buffer.from('dev:dev').toString('base64')
  }
}).then(res => console.log('Workflow created:', res.data.id));

​
3. Enable Development Mode Features

# Start with tunnel for webhook development
n8n start --tunnel

# Enable verbose logging
N8N_LOG_LEVEL=debug n8n start

# Watch for file changes (custom nodes)
N8N_WATCH=true n8n start

​
Troubleshooting

Common issues Port conflicts, database connection failures, and custom node loading problems - each with specific solutions and troubleshooting steps.
# Find process using port
lsof -i :5678

# Kill the process
kill -9 <PID>

# Or use different port
N8N_PORT=5679 n8n start

# Check PostgreSQL is running
docker ps | grep postgres

# Test connection
psql -h localhost -U n8n -d n8n

# Check logs
docker logs n8n-postgres

# Verify custom node directory
ls ~/.n8n/custom/

# Check n8n logs for errors
N8N_LOG_LEVEL=debug n8n start

# Rebuild custom nodes
cd ~/.n8n/custom && npm run build

​
Next Steps

Ready to build With your environment configured, move on to building custom nodes or learning advanced workflow patterns.

Build Your First Node

Create a custom n8n node from scratch

Workflow Development

Learn workflow design patterns

​
Additional Resources

​
Frequently Asked Questions

​
Should I use Railway or local development for learning?

For learning, start with Railway to get familiar with n8n quickly, then move to local development when you’re ready to build custom nodes. Local development gives you more control and faster iteration cycles.

​
What’s the difference between SQLite and PostgreSQL for development?

SQLite is simpler for local development but doesn’t support all production features. PostgreSQL matches production environments and supports advanced features like queue management with Redis.

​
How do I switch between different n8n versions?

With Docker, change the image tag (e.g., n8nio/n8n:0.200.0). With npm, use npm install n8n@version. Always backup your data before switching versions.

​
Can I use n8n with other databases like MongoDB?

n8n officially supports PostgreSQL, MySQL, and SQLite. MongoDB isn’t supported as the primary database, but you can connect to MongoDB through workflow nodes.

​
How do I enable debug mode for troubleshooting?

Set N8N_LOG_LEVEL=debug and NODE_ENV=development. This provides verbose logging for troubleshooting issues with workflows, nodes, and connections.

​
What ports does n8n use besides 5678?

n8n uses port 5678 for the web interface. If using Redis, it typically uses 6379. PostgreSQL uses 5432, MySQL uses 3306. Ensure these ports are available or configure alternatives.

​
How do I backup my development environment?

Export workflows via CLI (n8n export:workflow --all), backup your database, and version control your custom nodes. For complete backups, include the .n8n directory contents.

​
Can I run multiple n8n instances for different projects?

Yes, use different ports and data directories. Set N8N_PORT, N8N_USER_FOLDER, and separate database configurations for each instance to avoid conflicts.

​
What happens if I don’t set up a database?

n8n defaults to SQLite stored in the user folder. This works for development but isn’t recommended for production due to performance and concurrency limitations.

​
How do I update n8n in my development environment?

For Docker, pull the latest image. For npm installations, run npm update n8n. For Railway, redeploy with the latest template. Always backup before updating.
⌘I