# n8n

n8n is a workflow automation platform with a visual editor and hundreds of integrations

[n8n](https://github.com/n8n-io/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.