n8n

n8n is a workflow automation platform with a visual editor, webhook triggers, and built-in AI agent nodes. This guide deploys the official Docker image on Upsun using Docker image support, with a persistent SQLite database for workflows, credentials, and execution history. For prerequisites and Docker image limitations, see Self-hosted services from public Docker images. If you don’t need a persistent workflow UI and just want to run a job on demand or on a schedule, task containers or crons may be a simpler fit than n8n.

Before you begin

Install the Upsun CLI.
Run the following commands to log in and connect the current Git repository to the correct Upsun project. Replace <PROJECT_ID> with your project ID (run upsun projects to list them).
upsun login upsun auth:info upsun set-remote <PROJECT_ID> upsun project:info upsun environment:info

1. Configure n8n as an app

Add the following configuration to .upsun/config.yaml.

This configuration uses the startup command defined by the image. The official n8n image already starts n8n and listens on 0.0.0.0:5678, so this example does not set web.commands.start to override it.
The /home/node mount contains n8n’s SQLite database, configuration, credentials, and cache. Mounting the full home directory ensures both .n8n and .cache are writable and persistent.
HIGH_MEMORY is a container profile — a preset ratio of memory to CPU. Choose the profile that matches n8n’s actual resource needs.

applications:
  n8n:
    type: docker:1
    container_profile: HIGH_MEMORY

    # Pin the image tag for repeatable deploys. Avoid `latest` in production;
    # update this tag intentionally when you are ready to upgrade n8n.
    image:
      name: "ghcr.io/n8n-io/n8n:2.34.1"

    # Production baseline after deployment:
    #   upsun resources:set --size n8n:1 --disk n8n:2048
    # This keeps one n8n instance with 1 CPU and, under HIGH_MEMORY, roughly
    # 2 GB RAM. Increase disk for execution history and binary data.

    # /home/node exists in the official image. n8n stores its SQLite database
    # and instance configuration in .n8n and compiled editor assets in .cache.
    mounts:
      "/home/node":
        source: storage
        source_path: node-home

    variables:
      env:
        # Keep the encryption key out of Git and set it as a sensitive runtime
        # variable instead:
        #   upsun variable:create --level environment --prefix env: --name N8N_ENCRYPTION_KEY --value '<LONG_RANDOM_ENCRYPTION_KEY>' --sensitive true --visible-runtime true --visible-build false

        # Upsun starts the wrapped image from /app. Set the n8n user folder to
        # the persistent mount instead of allowing it to default to /app/.n8n.
        N8N_USER_FOLDER: "/home/node"
        N8N_ENFORCE_SETTINGS_FILE_PERMISSIONS: "true"

        # n8n serves HTTP directly on TCP port 5678. Trust one proxy hop so n8n
        # uses the forwarding headers supplied by the Upsun router.
        N8N_LISTEN_ADDRESS: "0.0.0.0"
        N8N_PROXY_HOPS: "1"

        # Change these values to the timezone used by scheduled workflows.
        GENERIC_TIMEZONE: "Etc/UTC"
        TZ: "Etc/UTC"

        # Register tini as a child subreaper because the image entrypoint runs
        # inside Upsun's application wrapper rather than as PID 1.
        TINI_SUBREAPER: "true"

    web:
      upstream:
        # n8n serves HTTP directly on a TCP port; passthrough lets the Upsun
        # router forward requests without expecting a local Unix socket.
        socket_family: tcp
      locations:
        "/":
          passthru: true
          request_buffering:
            enabled: false

# This project does not need Upsun-managed services because this example uses
# n8n's persistent SQLite database.
services: null

routes:
  # Use a dedicated subdomain so the editor and webhooks share one public URL.
  "https://n8n.{default}/":
    type: upstream
    upstream: "n8n:http"
    cache:
      enabled: false

2. Set or update the n8n encryption key

Set N8N_ENCRYPTION_KEY as a sensitive runtime environment variable instead of committing it to .upsun/config.yaml.

Generate a long random value for the encryption key:
openssl rand -hex 32

Use the generated value in place of <LONG_RANDOM_ENCRYPTION_KEY>:

upsun variable:create --level environment --prefix env: --name N8N_ENCRYPTION_KEY --value '<LONG_RANDOM_ENCRYPTION_KEY>' --sensitive true --visible-runtime true --visible-build false

If the N8N_ENCRYPTION_KEY variable already exists, update it:

upsun variable:update env:N8N_ENCRYPTION_KEY --level environment --value '<LONG_RANDOM_ENCRYPTION_KEY>' --sensitive true --visible-runtime true --visible-build false

Keep the key backed up securely. Changing it after n8n has stored credentials makes those credentials unreadable unless you migrate them using the previous key.

3. Deploy the app

Commit the changes to .upsun/config.yaml and push them to Upsun:

git add .upsun/config.yaml
git commit -m "Add n8n Docker image app"
upsun push

4. Allocate n8n resources

The first deployment defaults to a minimal resource allocation regardless of app type (0.5 CPU, 512 MB disk, and 1408 MB memory). That’s enough to boot n8n and run small workflows, but workflow concurrency, execution history, and binary data can require more resources. Set a baseline for the app:

upsun resources:set --size n8n:1 --disk n8n:2048

With container_profile: HIGH_MEMORY, the n8n app gets 1 CPU, about 2 GB RAM, 2 GB disk, and one instance. Increase CPU and memory for concurrent or memory-intensive workflows, and increase the disk size as execution history and binary data grow. If you changed resources after the app was already deployed, redeploy the environment:

upsun environment:redeploy

5. Set the public URLs

List the routes and copy the HTTPS hostname mapped to the n8n app:

upsun route:list

Replace <N8N_HOSTNAME> with that hostname, without a path:

upsun variable:create --level environment --prefix env: --name N8N_WEBHOOK_URL --value 'https://<N8N_HOSTNAME>/' --visible-runtime true --visible-build false

upsun variable:create --level environment --prefix env: --name N8N_EDITOR_BASE_URL --value 'https://<N8N_HOSTNAME>/' --visible-runtime true --visible-build false

If either variable already exists, update it:

upsun variable:update env:N8N_WEBHOOK_URL --level environment --value 'https://<N8N_HOSTNAME>/' --visible-runtime true --visible-build false

upsun variable:update env:N8N_EDITOR_BASE_URL --level environment --value 'https://<N8N_HOSTNAME>/' --visible-runtime true --visible-build false

These variables make webhook URLs and editor links use the public HTTPS route.

Preview environment URLs are ephemeral by default, so <N8N_HOSTNAME> changes with every new preview environment. If external services need a stable webhook URL, set up a custom domain for the environment.

6. Validate the deployment

List the routes and confirm that the HTTPS route mapped to the n8n app appears. You’ll use its hostname in place of <N8N_HOSTNAME> in the next step.

upsun route:list

Check the health endpoint. Replace <N8N_HOSTNAME> with the hostname for the n8n app:

curl https://<N8N_HOSTNAME>/healthz

Expected response:

{"status":"ok"}

Open https://<N8N_HOSTNAME>/ to create the n8n owner account. If the health check doesn’t return this, or you run into other issues deploying the app, debug the app over SSH to check /var/log/app.log and the container’s process state.

Updating the image version

To use a different n8n version, update the version in image.name:

applications:
  n8n:
    type: docker:1
    image:
      name: "ghcr.io/n8n-io/n8n:<VERSION>"

Then, commit and push the change:

git add .upsun/config.yaml
git commit -m "Update n8n image version"
upsun push

Limitations

This configuration uses SQLite and one n8n instance, so it can’t handle high workflow volume and provides no redundancy during restarts, deployments, or instance failures. Don’t fix this by increasing instance count alone: storage mounts are shared between instances of the same app, so multiple instances would write to the same SQLite file concurrently — something SQLite can’t handle safely. To scale horizontally and gain high availability, switch to queue mode: PostgreSQL for shared state, Valkey (Upsun’s Redis-compatible service) for the job queue, and separate worker instances. Until then, schedule redeploys during low-traffic windows and design workflows to tolerate an interrupted execution being retried.

Operational considerations

Backups: Production environments back up automatically with only 2 days of retention by default, and non-production environments aren’t backed up at all. Since this configuration has no external database, that backup is the only copy of your workflows, credentials, and execution history — consider a longer retention policy and n8n’s own execution-data pruning settings to limit how much there is to back up.
Monitoring/alerts: Upsun has no built-in alerting. Forward n8n’s logs to an external tool via log forwarding, or use Blackfire for performance profiling, then alert from whatever tool receives that data.
SMTP: n8n needs an SMTP provider for workflow notification emails. You can optionally use Upsun’s built-in SMTP proxy instead of a third-party provider — preview environments are limited to 12,000 email credits per calendar month.

n8n is commonly used to orchestrate AI agent workflows. If those workflows need to manage Upsun infrastructure itself (for example, triggering deploys or querying environment status from an agent), see the Upsun MCP Server.

Get Started

Core Concepts

Configure Apps & Services

Build, Deploy & Run

Manage Projects

Manage Environments

Manage Resources

Observability & Metrics

Integrations

Troubleshooting

Resources

Before you begin

1. Configure n8n as an app

2. Set or update the n8n encryption key

3. Deploy the app

4. Allocate n8n resources

5. Set the public URLs

6. Validate the deployment

Updating the image version

Limitations

Operational considerations

​Before you begin

​1. Configure n8n as an app

​2. Set or update the n8n encryption key

​3. Deploy the app

​4. Allocate n8n resources

​5. Set the public URLs

​6. Validate the deployment

​Updating the image version

​Limitations

​Operational considerations

​Related

Before you begin

1. Configure n8n as an app

2. Set or update the n8n encryption key

3. Deploy the app

4. Allocate n8n resources

5. Set the public URLs

6. Validate the deployment

Updating the image version

Limitations

Operational considerations

Related