n8n

n8n is a fair-code workflow automation tool, comparable to Zapier or Make, that you can self-host. It is a Node.js application published to npm as the n8n package. Rather than building the n8n monorepo from source, deploy a tiny repository that depends on the published package.

Requirements

Create a PostgreSQL database on the app's Databases tab. n8n does not read DATABASE_URL, so copy the host, database name, username and password from the connection string Hatchbox shows into the DB_POSTGRESDB_* variables below.

n8n 2.x requires Node.js 24.

Repository

Create a new Git repository with these files and point Hatchbox at it:

package.json

{
  "name": "n8n-hatchbox",
  "private": true,
  "dependencies": {
    "n8n": "2.41.6"
  },
  "scripts": {
    "start": "n8n start",
    "worker": "n8n worker"
  }
}

.node-version

24.21.0

Run npm install locally once and commit the generated package-lock.json together with the files above. Hatchbox needs the lockfile to detect a Node app and run npm install on deploy. Pin an exact n8n version and bump it to upgrade; the GitHub releases page lists the current stable version.

Environment Variables

N8N_HOST=n8n.example.com
N8N_PROTOCOL=https
N8N_EDITOR_BASE_URL=https://n8n.example.com/
N8N_WEBHOOK_URL=https://n8n.example.com/
N8N_PROXY_HOPS=1
N8N_ENCRYPTION_KEY=...                     # `openssl rand -hex 32`
N8N_USER_FOLDER=/home/deploy/n8n/shared    # $DIR/shared for your app name
GENERIC_TIMEZONE=America/Chicago
DB_TYPE=postgresdb
DB_POSTGRESDB_HOST=...
DB_POSTGRESDB_PORT=5432
DB_POSTGRESDB_DATABASE=...
DB_POSTGRESDB_USER=...
DB_POSTGRESDB_PASSWORD=...

Replace n8n.example.com with the domain you add on the Domains tab. N8N_PROXY_HOPS=1 tells n8n it sits behind one reverse proxy (Caddy). N8N_ENCRYPTION_KEY encrypts stored credentials; n8n generates one on first start if it is missing, but set it yourself so every server and worker shares the same key. N8N_USER_FOLDER moves n8n's .n8n data directory out of the release directory so it survives deploys.

Processes

n8n listens on N8N_PORT, so pass Hatchbox's PORT through in the command:

• web: N8N_PORT=$PORT npm start

n8n runs its database migrations automatically on startup.

First Login

Open your domain. n8n shows a setup screen that creates the instance owner account.

Queue Mode (optional)

By default the main process executes workflows itself. For heavier loads, n8n's queue mode hands executions to separate worker processes through Redis.

Add a Redis database on the Databases tab and then set:

EXECUTIONS_MODE=queue
QUEUE_BULL_REDIS_HOST=...
QUEUE_BULL_REDIS_PORT=6379
QUEUE_BULL_REDIS_PASSWORD=...     # omit if your Redis has no password
QUEUE_BULL_REDIS_DB=0             # the number at the end of the connection string, if any

n8n does not read REDIS_URL; take the host, port, password and database number from the connection string Hatchbox shows. Then add a second process on the worker servers:

• worker: N8N_RUNNERS_BROKER_PORT=5680 npm run worker

Every n8n process starts an internal task broker (it runs Code nodes) on 127.0.0.1:5679. A worker on the same server as the web process would fail with "n8n Task Broker's port 5679 is already in use", so give it its own broker port. If you run more than one worker or more than one n8n app on a server, give each process a different N8N_RUNNERS_BROKER_PORT.

Workers need the same N8N_ENCRYPTION_KEY and database variables as the main process. Queue mode does not support the filesystem binary data mode; keep the default or use S3 (N8N_DEFAULT_BINARY_DATA_MODE=s3).

Notes

n8n has announced that npm-based installs are deprecated from n8n 3.0, so check the release notes before upgrading past 2.x. Upgrade by changing the version in package.json, running npm install locally, committing the lockfile and deploying.