DOCSEARCHbyAlgolia
Submit Docs

n8n Hosting

repository·main·Indexed 23 days ago

https://github.com/n8n-io/n8n-hosting

Official production-ready deployment configurations for the n8n workflow automation platform. Provides setup guides and templates for Kubernetes (Helm and Raw Manifests), Docker Compose, and AWS ECS Fargate, including detailed configurations for queue mode, multi-main setups, worker scaling, and webhook processors.

Tokens
10.1K
Snippets
22
Records
52
Agent score
80%

What's inside n8n-hosting

  1. How Webhook Processors work and how to route traffic

    main

    Webhook processors are dedicated pods that handle production webhook and form traffic, separating this high-volume workload from the main UI and API processes.

    When webhookProcessor.disableProductionWebhooksOnMainProcess is set to true, you must configure your Ingress or Load Balancer to route specific paths to the webhook processor service and all other paths to the main service.

    Routing Table:

    PathTarget Service
    /webhook/*webhook processor (production webhooks)
    /webhook-waiting/*webhook processor (waiting webhook responses)
    /form/*webhook processor (production form triggers)
    /form-waiting/*webhook processor (waiting form pages)
    /webhook-test/*main service (test webhooks)
    /form-test/*main service (test form triggers)
    /* (everything else)main service (UI, API, etc.)

    Testing Routing:

    • curl -i http://your-domain/webhook/test-id should reach the webhook processor.
    • curl -i http://your-domain/webhook-test/test-id should reach the main service.
    • If you see "Cannot POST" errors, your routing is likely incorrect.

  2. Implement queue-depth scaling for workers

    main

    In queue mode, CPU/Memory scaling alone may not react to lightweight jobs that saturate concurrency without moving CPU.

    Automated Scaling (Webhooks and HA templates)

    The -webhooks and -ha templates include a 1-minute in-VPC Lambda that reads the Bull backlog key from Redis and publishes a WorkerBacklogPerTask custom metric. This is wired to an Application Auto Scaling target-tracking policy.

    To tune this, use:

    • WorkerMinTasks
    • WorkerMaxTasks
    • WorkerBacklogPerTask
    • WorkerConcurrency

    Manual Scaling (Base template)

    The base template only supports CPU/Memory scaling. To add queue-depth scaling manually, you must:

    1. Ensure N8N_METRICS=true and N8N_METRICS_INCLUDE_QUEUE_METRICS=true are set (enabled by default in the template).
    2. Scrape the /metrics endpoint for n8n_scaling_mode_queue_jobs_waiting or read the Redis queue length via a Lambda.
    3. Publish this to CloudWatch and attach a custom-metric scaling policy.

  3. How n8n deployment modes and components work

    main

    The chart supports two primary architectural patterns:

    1. Standalone Mode

    A single pod running n8n with SQLite. Best for development or small-scale use.

    2. Queue Mode (Default)

    A distributed architecture requiring external PostgreSQL and Redis. It consists of three pod types:

    ComponentPurposeScaling
    mainUI, API, non-production webhooks1 replica (or N with multi-main + Enterprise license)
    workerExecutes workflows from Redis queue2+ replicas, stateless
    webhook-processorHandles production webhooks (optional)2+ replicas, stateless

    All components use the same n8n container image but are differentiated by command-line arguments.

  4. Quick Start: Deploy n8n via Helm

    main

    To deploy n8n using the Helm chart, follow these steps:

    1. Set up external services: If using Queue mode, you must provide external PostgreSQL and Redis services. If using Standalone mode (queueMode.enabled: false), n8n uses SQLite and requires no external dependencies.
    2. Choose an example configuration: Select a .yaml file from the examples/ directory that matches your deployment scenario (e.g., standalone.yaml for simple setups or production-s3.yaml for enterprise production).
    3. Prepare your values file: Copy the chosen example to a new file and customize it with your environment settings.
    4. Create required secrets: Run the provided script to generate necessary secrets (database passwords, encryption keys, etc.).
    5. Deploy: Use Helm to install the chart using your customized values file.

    Note on Licensing:

    • Multi-main setup (multiMain.enabled: true) requires an n8n Enterprise license.
    • Community Edition users should stick to single main pod configurations.

  5. Deploy n8n on a subfolder with SSL using Docker Compose

    main

    This configuration allows you to run n8n behind a reverse proxy on a specific subfolder path with SSL enabled.

    Prerequisites: Before starting the containers, you must update the default credentials in the .env file to ensure your instance is secure.

    Deployment Steps:

    1. Navigate to the docker-compose/subfolderWithSSL/ directory.
    2. Edit the .env file to set your own custom users and passwords.
    3. Start the deployment using Docker Compose.

    Commands:

    • Start the services in detached mode: docker compose up -d
    • Stop the services: docker compose stop

  6. Configure KEDA Autoscaling for queue-based workloads

    main

    By default, the Helm chart uses Horizontal Pod Autoscalers (HPA) to scale workers based on CPU utilization. For more responsive scaling in queue-based workloads, you can use KEDA to scale workers based on the length of the Redis queue.

    To use this feature:

    1. Ensure KEDA is installed in your Kubernetes cluster.
    2. Set keda.enabled: true in your values.yaml.
    3. Configure the worker triggers. For n8n, the trigger type is redis.

    Important: The listName must match the Bull waiting-list key, which follows the pattern <prefix>:jobs:wait. If you have customized the Redis prefix using redis.prefix, you must update listName accordingly (e.g., myprefix:jobs:wait). If they do not match, the scaler will poll an incorrect key and autoscaling will not trigger.

    keda:
  enabled: true
  worker:
    minReplicaCount: 2
    maxReplicaCount: 20
    triggers:
      - type: redis
        metadata:
          listName: "bull:jobs:wait"
          listLength: "5"

  8. Quick Start Guide for n8n Helm Chart

    main

    To deploy n8n using this chart, follow these steps:

    1. Set up external services: Provision PostgreSQL and Redis (required for queue mode).
    2. Create required secrets: Run the provided helper script to generate necessary credentials:
      ./examples/create-secrets.sh
    3. Configure values: Choose a template from the examples/ directory and customize it.
    4. Deploy: Run the helm install command using your customized values file.
    ./examples/create-secrets.sh

helm install n8n oci://ghcr.io/n8n-io/n8n-helm-chart/n8n --version 1.0.0 -f my-values.yaml

  9. Choose the right n8n AWS ECS Fargate template

    main

    n8n provides three CloudFormation templates for running in queue mode with multi-main on ECS Fargate. Choose based on your load and availability requirements:

    • n8n-w-multimain-queuemode.yaml: Best for Dev, small, or cost-sensitive environments. Uses a single RDS instance.
    • n8n-w-multimain-queuemode-webhooks.yaml: Best for Production with real webhook load. Adds a dedicated webhook tier, queue-depth worker autoscaling, request-rate webhook autoscaling, and database/Redis hardening.
    • n8n-w-multimain-queuemode-webhooks-ha.yaml: Best for failover-sensitive production. Uses Aurora PostgreSQL (writer + reader), Redis Multi-AZ, and larger task sizes.

    Note: These templates require an Enterprise license for multi-main and S3 external storage features. You must provide a valid N8nLicenseKey for the stack to start.

  10. Use Task Runners for isolated code execution

    main

    Task runners execute JavaScript and Python code in isolated sidecar containers. When enabled, each main and worker pod receives a runner sidecar. The n8n container runs a task broker on port 5679, which the sidecar connects to via localhost.

    Setup Steps:

    1. Enable task runners in your values file.
    2. Create a secret containing a secure auth-token.
    taskRunners:
  enabled: true
  authToken:
    existingSecret: "n8n-runner-token"
    existingSecretKey: "auth-token"

    Create the secret via CLI:

    kubectl create secret generic n8n-runner-token \
  --from-literal=auth-token=$(openssl rand -base64 32)

  11. Configure deployment inputs for n8n ECS Fargate

    main

    Before deploying the CloudFormation templates, you must provide the following inputs:

    • A Route 53 hosted zone ID.
    • The n8n hostname to be created in that hosted zone.
    • An ACM certificate ARN (must be in the same AWS Region as the stack).
    • Production-grade values for the database, Redis, license key, and passwords.

    While the templates include placeholder defaults for inspection, these must be replaced with production values before deployment.

  12. Deploy n8n using the official Helm Chart

    main

    To deploy n8n on a production Kubernetes cluster, use the official Helm chart hosted on GHCR. You can provide a custom configuration file using the -f flag.

    Note: For full configuration details and common patterns, refer to the chart's specific documentation and the examples directory within the repository.

    helm install n8n oci://ghcr.io/n8n-io/n8n-helm-chart/n8n -f my-values.yaml