The n8n quick-start Docker command, a single `docker run` line pulling the n8n image, gets an instance running in under a minute and is genuinely useful for evaluation. It is not a production deployment: no persistent database beyond an ephemeral SQLite file, no SSL, no backup strategy, and no update path that doesn't risk data loss. This guide covers the Docker Compose setup PURIST actually deploys for clients running n8n in production.
The Production Docker Compose Structure
A production-grade n8n Docker Compose file includes, at minimum, four components working together: the n8n application container, a PostgreSQL container for persistent, concurrent-safe data storage (covered in depth in our PostgreSQL setup guide), a reverse proxy (commonly Caddy or Nginx) handling SSL termination and routing, and named Docker volumes ensuring data persists across container restarts and image updates rather than living inside an ephemeral container filesystem.
| Component | Role | Why it's non-negotiable for production |
|---|---|---|
| n8n container | Runs the actual application | The core service, obviously required |
| PostgreSQL container | Persistent workflow and execution data | SQLite's concurrency limits make it unsuitable past light use |
| Reverse proxy (Caddy/Nginx) | SSL termination, routing, security headers | n8n should never be directly exposed to the internet without TLS in front of it |
| Named volumes | Data survives container restarts and updates | Without this, an image update or container recreation can silently wipe data |
Environment Variables That Matter in Production
Beyond the PostgreSQL connection variables covered in our database guide, a production deployment should explicitly set: `N8N_ENCRYPTION_KEY` (a stable, backed-up encryption key for credential storage, critical, losing this key makes all stored credentials permanently unrecoverable), `WEBHOOK_URL` (the public-facing URL webhooks should reference, which must match your actual domain for webhook-triggered workflows to function correctly behind a reverse proxy), `N8N_PROTOCOL` and `N8N_HOST` (matching your actual deployment configuration), and `GENERIC_TIMEZONE` (ensuring scheduled workflows fire at the intended local time rather than defaulting to UTC unexpectedly).
Backup Strategy for a Dockerized n8n Instance
A proper backup covers three things: the PostgreSQL database (via `pg_dump` on a scheduled basis, stored off the same server), the `N8N_ENCRYPTION_KEY` specifically (stored securely and separately, since losing it while having a database backup still leaves credentials unrecoverable), and any custom node installations or configuration files outside the standard image. A backup strategy covering only the database while missing the encryption key is a common and costly oversight, one that turns a routine server migration into a full credential-reconfiguration project.
Update Strategy Without Downtime Risk
Updating n8n's Docker image version should follow a tested pattern: pull the new image version, stop the current container, start the new version pointed at the same persistent volumes and database, and verify workflows execute correctly before considering the update complete. Skipping straight to `latest` without pinning a specific tested version risks an unexpected breaking change deploying automatically; PURIST's standard practice is pinning a specific version tag and testing updates in a staging instance before promoting to production, exactly the promotion pattern covered in our n8n API guide.
Sources & Further Reading
Deployment patterns reflect n8n's official Docker documentation and PURIST's own production deployment practice as of publication. See n8n's official Docker deployment documentation for the base reference. For the database layer specifically, see n8n self-hosted PostgreSQL: setup and schema guide, and for the broader cloud-versus-self-hosted decision, see n8n self-hosted vs cloud: the complete decision guide.
The Complete Docker Compose Reference Structure
A production n8n Docker Compose file conceptually organizes into these service blocks: the `n8n` service (application container, environment variables, volume mounts), the `postgres` service (database container, its own persistent volume, environment variables matching what n8n expects to connect to), and the `caddy` or `nginx` service (reverse proxy, exposed ports 80/443, configuration referencing your domain for automatic SSL certificate provisioning). Networking between these services uses Docker Compose's default internal network, meaning the n8n service connects to postgres by its service name as hostname, never by a public address, keeping the database entirely unexposed to the outside network.
SSL Certificate Management
Using Caddy specifically as the reverse proxy is a common choice for self-hosted n8n specifically because it handles automatic SSL certificate provisioning and renewal via Let's Encrypt with minimal configuration, a single line referencing your domain, compared to Nginx's more manual certbot-based certificate setup. For teams already standardized on Nginx for other infrastructure, that familiarity may outweigh Caddy's simplicity advantage, but for a dedicated n8n deployment starting fresh, Caddy's reduced configuration surface is a genuine time saver.
Handling Webhook URLs Behind a Reverse Proxy
A common production issue: webhook-triggered workflows fail because the `WEBHOOK_URL` environment variable doesn't match the actual public-facing domain the reverse proxy serves, causing n8n to register webhooks internally with an incorrect base URL. This environment variable must explicitly match your real public domain (e.g., `https://automation.yourbusiness.com/`), not `localhost` or an internal Docker service name, which is a frequent first-deployment mistake worth checking explicitly before assuming webhook triggers will work correctly.
Resource Limits and Container Stability
Setting explicit CPU and memory limits on the n8n container (via Docker Compose's `deploy.resources` configuration) prevents a single runaway workflow execution from consuming all available server resources and destabilizing other services running on the same host, particularly relevant for multi-tenant deployments running several clients' n8n instances on shared infrastructure, a pattern covered in this guide's FAQ section.
Zero-Downtime Update Pattern
For deployments where even brief downtime during updates is undesirable, running two n8n containers behind the reverse proxy with a rolling update (bringing up the new version, verifying health, then routing traffic to it before stopping the old version) avoids the brief interruption a simple stop-and-restart update causes. This adds real complexity and is generally only worth implementing once webhook-triggered, time-sensitive workflows make even a one-to-two-minute update window genuinely costly to the business.
What to Verify Before Going Live
- Do our named volumes actually persist data correctly across a full container recreation, tested deliberately, not assumed?
- Is our `WEBHOOK_URL` set to match our actual public domain, verified by testing a real webhook trigger end to end?
- Have we pinned specific image version tags rather than using `latest`, with a tested update process before promoting a new version to production?
- Are resource limits configured to prevent a single runaway workflow from destabilizing the whole instance?
Sources & Further Reading
Deployment patterns reflect n8n's official Docker documentation and PURIST's production deployment practice as of publication. See n8n's official Docker documentation for the authoritative base reference.
For related reading, see n8n self-hosted PostgreSQL: setup and schema guide for the database layer, and n8n API: the complete guide for the promotion pattern referenced in the update strategy section above.
Common Mistakes in Production Docker Deployments
Using the `latest` image tag in a production Compose file. This means every restart could silently pull a newer, untested version of n8n; pin a specific version tag and upgrade deliberately, testing the new version in staging first.
Forgetting named volumes and losing data on a routine container recreation. Without explicit named volumes, data can live inside a container's writable layer, which is destroyed when that container is removed and recreated during a routine update, a genuinely common and entirely avoidable data-loss cause.
Exposing the n8n instance directly to the internet without a reverse proxy and SSL. Running n8n's own port directly exposed, without TLS termination in front of it, sends credentials and data in plaintext and skips security headers a reverse proxy would otherwise provide.
A Realistic Scenario: An Update Gone Wrong, and the Recovery That Worked
A team running n8n via Docker pulled a new image version during a routine update without first testing it in staging, and the new version introduced a breaking change affecting one of their custom node configurations, causing several production workflows to fail silently overnight. Because their Compose setup used named volumes and a pinned previous version tag was still available locally, rolling back to the last known-good version took under five minutes once the failure was noticed the next morning. The lasting change from this incident wasn't abandoning self-hosting, it was adopting the staging-first update pattern covered earlier in this guide, so the same class of failure would be caught before reaching production the next time.
The 3-Year View: Infrastructure Maturity Over Time
| Year | Typical infrastructure state | What triggers the next stage |
|---|---|---|
| Year 1 | Single-server Docker Compose deployment | Sufficient for most starting automation volume |
| Year 2 | Added monitoring, tested backup/restore process, pinned version update discipline | Growing reliance on the instance for genuinely business-critical workflows |
| Year 3 | Possibly separated database and application servers, or a managed hosting relationship | Volume or reliability requirements outgrow a single-server setup |
Most PURIST client deployments stabilize at the year-two maturity level indefinitely; progressing to genuinely separated, multi-server infrastructure is only necessary for a minority of businesses running automation at a scale most SMB and mid-market operations never reach.
Comparing Cloud Providers for Self-Hosted n8n
| Provider | Typical strength for this use case | Consideration |
|---|---|---|
| DigitalOcean | Simple pricing, straightforward Droplet + Managed Database combination | Smaller global network than hyperscalers, generally sufficient for most SMB use cases |
| Hetzner | Very cost-competitive infrastructure pricing | Primarily European data centers, worth checking latency if your users are elsewhere |
| AWS/GCP/Azure | Deepest ecosystem, most advanced managed services, broadest global presence | More complex pricing and configuration surface than a simpler provider for a straightforward single-instance deployment |
For most PURIST client self-hosted deployments, a simpler provider (DigitalOcean or Hetzner) serving a single-region, single or dual-server Docker Compose deployment is entirely sufficient, and the added complexity of a hyperscaler's broader service catalog is rarely justified purely for hosting n8n itself, becoming relevant mainly when a business already has broader infrastructure on one of the major clouds and wants to keep everything consolidated with a single provider.
Complete Pre-Launch Checklist
Before considering a self-hosted n8n Docker deployment genuinely production-ready, verify each of the following explicitly rather than assuming: SSL certificate provisioning is working and auto-renewing correctly, named volumes are confirmed to persist data across a deliberate container recreation test, the `N8N_ENCRYPTION_KEY` is backed up separately from the database backup, a full backup-and-restore cycle has been tested end to end on a non-production instance, resource limits are configured to prevent a single workflow from destabilizing the host, and the specific n8n image version is pinned rather than tracking `latest`. Treating this as a formal go-live checklist, rather than an informal sense that "it's been running fine," catches the gaps that typically surface only during an actual incident, exactly when discovering them is most costly.
Frequently Asked Questions
What happens if I lose the N8N_ENCRYPTION_KEY?
Every stored credential becomes permanently unreadable, effectively requiring every single credential across every workflow to be manually re-entered. Back this key up with the same rigor as the database itself, ideally in a separate secure location, not just alongside the database backup.
Do I need a reverse proxy if I'm only accessing n8n internally, never from the public internet?
Less critical for SSL specifically if genuinely internal-only, but still valuable for consistent routing and security headers; if there's any chance of future public exposure (webhook triggers from external services almost always require it), build the reverse proxy in from the start rather than retrofitting it later.
How much server capacity do I need for a production n8n Docker deployment?
For most SMB automation volume, a modest VPS (2 vCPU, 4GB RAM as a reasonable starting point) handles n8n and PostgreSQL together comfortably; scale up specifically if you're running many concurrent, resource-intensive workflows (large data processing, heavy AI API calls) rather than by workflow count alone.
Can I run multiple n8n instances on the same server for different clients?
Yes, via separate Docker Compose stacks with distinct ports, databases, and encryption keys per instance, a common pattern for agencies managing multiple client deployments on shared infrastructure, provided each instance is properly isolated.
Is Docker Swarm or Kubernetes necessary for a production n8n deployment?
For most single-server production deployments, no, Docker Compose is sufficient and considerably simpler to manage. Kubernetes becomes relevant specifically at a scale requiring multi-server orchestration and auto-scaling, well beyond what most SMB and mid-market automation volume requires.
Can I deploy n8n via Docker on a Raspberry Pi or similarly limited hardware?
Technically possible for very light personal use, but not recommended for genuine business production use given the resource constraints; a modest cloud VPS is a more appropriate and still low-cost production target.
Do I need a dedicated domain for my n8n instance, or can I use a subpath of an existing site?
A dedicated subdomain (like automation.yourbusiness.com) is the more common and simpler setup, particularly for webhook URL configuration; running n8n on a subpath of an existing site's domain is possible but adds reverse-proxy configuration complexity most deployments don't need to take on.
How do I monitor container health in this Docker Compose setup?
Docker's built-in healthcheck configuration, combined with the execution-monitoring approach covered in our error handling guide, gives coverage at both the infrastructure level (is the container running) and the application level (are workflows executing successfully).
Should I use Docker Swarm mode even for a single-server deployment for future flexibility?
Generally not necessary; plain Docker Compose is simpler to operate and sufficient until you have a concrete multi-server scaling need, at which point migrating to Swarm or Kubernetes is a deliberate, planned project rather than something to prematurely adopt for single-server use.
How do I handle secrets (API keys, database passwords) in my Docker Compose file securely?
Use Docker Compose's environment file support (a separate `.env` file excluded from version control) rather than hard-coding secrets directly in the committed `docker-compose.yml`, and consider a dedicated secrets manager for anything beyond a single-server, low-sensitivity deployment.
What's the actual downtime during a standard (non-zero-downtime) update?
Typically well under a minute for a properly configured instance, the time to stop the old container, pull if needed, and start the new one; for most business automation use cases, a planned brief maintenance window absorbs this without meaningful impact.
Does the choice of Linux distribution for the host server matter for n8n Docker deployments?
Not significantly, since Docker abstracts most OS-level differences; any modern, well-supported Linux distribution (Ubuntu LTS is a common choice) works fine as a Docker host, the more important factor is your own familiarity with maintaining and securing whichever distribution you choose.
Should logs from the n8n container be sent to an external logging service?
For production deployments, yes, this is worth setting up; container logs alone (viewable via `docker logs`) work for basic troubleshooting but an external logging service provides better retention, searchability, and alerting integration for a genuinely production-grade setup.
How do I handle time zone configuration correctly across the whole stack?
Set `GENERIC_TIMEZONE` in the n8n service explicitly to your intended business time zone, and verify the PostgreSQL container's own time zone configuration is consistent, mismatched time zones between the application and database layers are a subtle, easy-to-miss source of scheduling and timestamp confusion.
Should I containerize a reverse proxy separately or use a managed load balancer service instead?
Both are valid; a containerized reverse proxy (Caddy/Nginx) keeps everything in one Compose stack and is simpler for a single-server deployment, while a managed load balancer service becomes more relevant once you're running multiple n8n instances behind it.
What's the minimum viable production setup if budget is extremely tight?
A single modest VPS (2 vCPU, 4GB RAM is a reasonable floor) running n8n and PostgreSQL via Docker Compose, with a basic Caddy reverse proxy for SSL, covers genuine production use for light-to-moderate automation volume at close to the lowest realistic cost.
Does containerizing n8n limit access to the underlying file system for custom node installations?
Custom nodes are typically installed via a volume-mounted directory or a custom Docker image build including them, both well-supported patterns; containerization doesn't meaningfully restrict custom node capability, it just requires the installation to happen through Docker-appropriate mechanisms rather than directly on a bare-metal file system.
Is it worth using Infrastructure as Code tooling (Terraform, etc.) for a single-server n8n deployment?
For a single, straightforward deployment, the added tooling overhead often exceeds the benefit; Infrastructure as Code becomes genuinely valuable once managing multiple similar environments (several client instances, for instance) where consistency and repeatability across many deployments matters more.
How do I handle scaling n8n horizontally across multiple containers for very high volume?
n8n supports a queue mode configuration (using Redis) for distributing execution across multiple worker containers, relevant specifically for genuinely high-volume deployments beyond what a single instance comfortably handles; most SMB and mid-market deployments never need this and a single well-resourced instance suffices.
Should backups be stored in the same cloud region as the production server?
Store at least one backup copy in a different region or provider entirely from your production infrastructure, protecting against a region-wide outage or provider-level incident affecting both your live instance and its backup simultaneously.
Does using Docker add meaningful performance overhead compared to running n8n directly on the host?
The overhead is minimal for n8n's typical workload profile; the operational benefits of containerization (consistent environments, easier updates, cleaner resource isolation) far outweigh the negligible performance cost for virtually all production use cases.
Is Podman a viable alternative to Docker for this deployment pattern?
Podman's broad Docker-compatibility means most of this guide's Compose-based patterns translate reasonably well, though verify specific compatibility for your exact setup, particularly around rootless container networking, before assuming a drop-in replacement.
To get a properly architected, backed-up, production-grade Docker deployment of n8n, book a free automation audit. We deploy and maintain exactly this infrastructure pattern for clients running self-hosted n8n in production.
Tags
Purist Team
The PURIST editorial team covers automation, AI agents, and operations strategy for businesses scaling with n8n, Make, and Claude AI.
