How to deploy worker n8n instances on n8n

advanced 12 min read Updated 2026-04-20

Quick Answer

Deploy worker n8n instances by configuring the main n8n instance as a queue mode setup with Redis, then launching separate worker containers that connect to the same database and Redis instance. Workers handle execution while the main instance manages the UI and workflow definitions.

Full n8n Review

Prerequisites

n8n installed and configured
Docker or Kubernetes environment
Redis instance for queue management
Basic understanding of microservices architecture

Step-by-Step Instructions

Configure Redis for Queue Management

Set up Redis to handle job queuing between your main n8n instance and workers. Install Redis and configure the connection in your environment variables:

N8N_EXECUTIONS_MODE=queue
QUEUE_BULL_REDIS_HOST=your-redis-host
QUEUE_BULL_REDIS_PORT=6379
QUEUE_BULL_REDIS_PASSWORD=your-redis-password

Use Redis Cluster for high availability in production environments

Configure Main n8n Instance for Queue Mode

Update your main n8n instance configuration to enable queue mode. Add these environment variables to your main instance:

N8N_EXECUTIONS_MODE=queue
EXECUTIONS_PROCESS=main
N8N_SKIP_WEBHOOK_DEREGISTRATION_SHUTDOWN=true

Restart your main n8n instance to apply the queue mode configuration.

The main instance will handle UI, webhooks, and scheduling but won't execute workflows

Prepare Worker Configuration

Create a worker-specific configuration with the same database and Redis settings as your main instance. Set these environment variables for workers:

N8N_EXECUTIONS_MODE=queue
EXECUTIONS_PROCESS=worker
DB_TYPE=your-database-type
DB_POSTGRESDB_HOST=your-db-host
DB_POSTGRESDB_DATABASE=your-n8n-database

Workers must connect to the same database as the main instance to access workflow definitions

Deploy Worker Containers

Deploy worker instances using Docker or your container orchestration platform. Use the same n8n Docker image but with worker-specific environment variables:

docker run -d \
  --name n8n-worker-1 \
  -e N8N_EXECUTIONS_MODE=queue \
  -e EXECUTIONS_PROCESS=worker \
  -e QUEUE_BULL_REDIS_HOST=redis-host \
  -e DB_POSTGRESDB_HOST=db-host \
  n8nio/n8n:latest

Configure Worker Scaling

Set up auto-scaling for your worker instances based on queue length or CPU usage. Configure the number of concurrent jobs per worker:

EXECUTIONS_PROCESS_MAX_CONCURRENT=10
QUEUE_BULL_REDIS_MAX_STALLEDCOUNT=1

Monitor Redis queue metrics to determine optimal worker count and scaling policies.

Start with 2-3 workers and scale based on your workflow execution patterns

Verify Worker Registration

Check that workers are properly connected by monitoring the Redis queues and n8n logs. In your main n8n instance, go to Settings > Execution to verify queue mode is active. Check worker logs for successful Redis connection messages:

docker logs n8n-worker-1

Workers should show 'Connected to Redis' and 'Worker started' messages in logs

Test Workflow Execution

Create a test workflow in your main n8n instance and execute it to verify workers are processing jobs. Monitor the Executions tab to see workflows being processed by worker instances. Check execution logs to confirm which worker handled each execution.

Use workflows with different execution times to test load distribution across workers

Monitor and Maintain Workers

Set up monitoring for worker health, queue length, and execution metrics. Use Redis monitoring tools to track queue depth and worker performance. Implement health checks for worker containers:

HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
CMD curl -f http://localhost:5678/healthz || exit 1

Set up alerts for high queue lengths or failed worker instances to maintain system reliability

Common Issues & Troubleshooting

Workers not processing executions from queue

Verify Redis connection settings match between main instance and workers. Check that QUEUE_BULL_REDIS_HOST and credentials are identical across all instances.

Database connection errors in worker instances

Ensure workers have the same database configuration as the main instance. Verify DB_POSTGRESDB_HOST, DB_POSTGRESDB_DATABASE, and credentials are correctly set in worker environment variables.

Workflows stuck in 'running' status

Check worker logs for execution errors and verify EXECUTIONS_PROCESS_MAX_CONCURRENT is not too high. Restart stuck workers and monitor Redis queue for stalled jobs using QUEUE_BULL_REDIS_MAX_STALLEDCOUNT.

High memory usage in worker instances

Reduce EXECUTIONS_PROCESS_MAX_CONCURRENT value and implement worker restarts after processing a certain number of jobs. Consider scaling horizontally with more workers instead of increasing concurrent executions per worker.

Prices mentioned in this guide are pulled from current plan data and may change. Always verify on the official n8n website before purchasing.

Visit n8n View n8n Pricing