n8n Documentation: A Practical Guide to Setup, Workflows, and Docker Deployment

Disclosure: This post contains one or more links to providers we have a real, registered affiliate/referral relationship with. We may earn a commission at no extra cost to you if you sign up through them.

If you’ve spent any time evaluating workflow automation tools, you’ve probably run into n8n — the open-source, node-based automation platform that positions itself as a self-hosted alternative to Zapier and Make. But n8n’s flexibility comes with a learning curve, and the official n8n documentation, while thorough, can feel scattered when you’re trying to go from zero to a running production instance. This guide walks through the parts of n8n documentation that actually matter for developers and sysadmins: installation, Docker deployment, workflow basics, and the production hardening steps most tutorials skip.

We’ll cover where to find the right documentation pages, how to stand up n8n with Docker Compose, how environment variables control security and persistence, and how to avoid the most common self-hosting mistakes.

What Is n8n?

n8n (pronounced “n-eight-n,” short for “nodemation”) is a fair-code licensed workflow automation tool. Instead of writing glue code to connect APIs, you build workflows visually by connecting “nodes” — each node represents a trigger, an action, or a piece of logic. It supports over 400 integrations out of the box, plus a JavaScript/Python code node for anything custom.

Unlike SaaS automation platforms, n8n can run entirely on your own infrastructure. That matters if you’re handling sensitive data, want to avoid per-execution pricing, or need to integrate with internal services that aren’t reachable from a public SaaS platform.

Why n8n Documentation Matters

The official n8n documentation lives at docs.n8n.io and is split across several distinct sections: hosting/installation, node reference, workflow concepts, and API reference. New users often waste time because they start reading the wrong section — for example, digging through node-level docs when what they actually need is the self-hosting and environment variable reference. Knowing the shape of the documentation before you start saves hours.

The source code itself is also useful documentation. The n8n GitHub repository contains example workflows, issue threads that double as troubleshooting guides, and the actual node source code — often more precise than the prose docs when you’re debugging a specific integration.

Getting Started: Installing n8n

There are three realistic ways to run n8n: npm (quick local testing), Docker (recommended for anything persistent), and n8n Cloud (managed, not self-hosted). For production or any serious self-hosting, Docker is the path documented and recommended by the n8n team itself.

Installing n8n with Docker

The fastest way to get a throwaway instance running is a single docker run command:

docker run -it --rm 
  --name n8n 
  -p 5678:5678 
  -v n8n_data:/home/node/.n8n 
  docker.n8n.io/n8nio/n8n

This exposes the editor UI on port 5678 and persists workflow data in a named volume. For anything beyond a quick test, use Docker Compose so you can add a database, reverse proxy, and environment configuration in one place:

version: "3.8"

services:
  n8n:
    image: docker.n8n.io/n8nio/n8n
    restart: unless-stopped
    ports:
      - "5678:5678"
    environment:
      - N8N_HOST=n8n.yourdomain.com
      - N8N_PROTOCOL=https
      - N8N_PORT=5678
      - WEBHOOK_URL=https://n8n.yourdomain.com/
      - GENERIC_TIMEZONE=UTC
      - DB_TYPE=postgresdb
      - DB_POSTGRESDB_HOST=postgres
      - DB_POSTGRESDB_DATABASE=n8n
      - DB_POSTGRESDB_USER=n8n
      - DB_POSTGRESDB_PASSWORD=${POSTGRES_PASSWORD}
    volumes:
      - n8n_data:/home/node/.n8n
    depends_on:
      - postgres

  postgres:
    image: postgres:16
    restart: unless-stopped
    environment:
      - POSTGRES_USER=n8n
      - POSTGRES_PASSWORD=${POSTGRES_PASSWORD}
      - POSTGRES_DB=n8n
    volumes:
      - postgres_data:/var/lib/postgresql/data

volumes:
  n8n_data:
  postgres_data:

Run it with:

docker compose up -d

If you’re new to Compose syntax generally, our Docker Compose guide for beginners covers the fundamentals used above, including volumes, environment variables, and service dependencies.

By default n8n uses SQLite, which is fine for testing but not for production — SQLite doesn’t handle concurrent writes well once you have multiple active workflows. The Postgres setup above is what the official docs recommend for anything beyond a single-user sandbox.

Installing n8n with npm

If you just want to try n8n locally without Docker:

npm install -g n8n
n8n start

This launches the editor at http://localhost:5678. It’s a reasonable way to explore the node reference, but it’s not something you should run as a long-lived service — no automatic restarts, no isolation, and updates require manually reinstalling the package.

Navigating the Official n8n Documentation

Once n8n is running, the documentation becomes a reference tool rather than an installation guide. Here’s how the official docs are organized, and what each section is actually good for:

Hosting docs — installation methods, environment variables, scaling with queue mode, and reverse proxy configuration.

Node reference — every built-in node (HTTP Request, Webhook, Postgres, Slack, etc.) with its parameters and example configurations.

Workflow docs — core concepts like expressions, the $json and $node variables, error workflows, and sub-workflows.

API reference — the REST API for managing workflows, credentials, and executions programmatically, useful if you want to manage n8n outside the UI.

Community forum and templates — thousands of shared workflow templates you can import directly instead of building from scratch.

If you’re debugging a specific node’s behavior, the node reference plus the node’s source in the GitHub repo will get you further than searching general web results — n8n’s ecosystem moves fast enough that Stack Overflow answers are frequently out of date.

Core Documentation Sections Worth Bookmarking

A few pages inside the official docs get referenced constantly once you’re running n8n day to day:

Environment variables reference (for hosting configuration)

Expressions reference (for writing dynamic values inside nodes)

Error handling and error workflows

Queue mode / scaling documentation (for high-volume production use)

Building Your First Workflow in n8n

Workflows in n8n start with a trigger node. The two most common starting points are the Webhook node (fires when an HTTP request hits a generated URL) and the Schedule Trigger node (fires on a cron-like interval).

A minimal webhook-triggered workflow looks like this:

1. Add a Webhook node, set the HTTP method to POST, and note the generated test URL.
2. Add an HTTP Request node after it to call an external API using data from the incoming webhook payload.
3. Add a Set node to reshape the response into whatever format you need downstream.
4. Activate the workflow.

You can test the webhook immediately with curl:

curl -X POST https://n8n.yourdomain.com/webhook-test/my-workflow 
  -H "Content-Type: application/json" 
  -d '{"event": "signup", "email": "[email protected]"}'

Inside any node, you can reference incoming data using n8n’s expression syntax, for example {{$json["email"]}}, which pulls the email field from the current item. This expression system is the single most important concept in n8n documentation to actually understand — almost every non-trivial workflow depends on correctly referencing data between nodes.

For anything that might fail — an API returning a 500, a malformed payload — attach an error workflow at the workflow level so failures trigger a notification instead of failing silently. This is one of the most under-used features in n8n, and it’s covered in the workflow documentation under error handling rather than in the node reference, which is exactly the kind of cross-section detail that’s easy to miss on a first pass through the docs.

Deploying n8n in Production

Running n8n on a laptop is fine for prototyping, but production deployments need a domain, HTTPS, and a process that survives reboots. This is also where most self-hosting mistakes happen — exposed ports, missing encryption keys, and no backup strategy for the workflow database.

Reverse Proxy Setup with Caddy

Putting n8n behind a reverse proxy handles TLS certificates automatically and lets you avoid exposing port 5678 directly. A minimal Caddyfile:

n8n.yourdomain.com {
    reverse_proxy localhost:5678
}

Caddy handles Let’s Encrypt certificate issuance automatically on first run. If you’d rather use Nginx or need a deeper walkthrough of proxying Docker containers generally, our reverse proxy setup guide for Docker containers covers both options with working config files.

Environment Variables and Security

A handful of environment variables control the security posture of a self-hosted n8n instance, and skipping them is the most common mistake in self-hosted deployments:

N8N_ENCRYPTION_KEY — encrypts stored credentials at rest; set this explicitly and back it up, since losing it makes saved credentials unrecoverable.

N8N_BASIC_AUTH_ACTIVE / N8N_BASIC_AUTH_USER / N8N_BASIC_AUTH_PASSWORD — adds authentication in front of the editor if you’re not using n8n’s built-in user management.

WEBHOOK_URL — must match your public domain, or generated webhook URLs will point to localhost.

N8N_SECURE_COOKIE — should stay true once you’re serving over HTTPS.

Never expose an n8n instance to the public internet without at least one authentication layer active. Workflows can contain live credentials for connected services (Slack tokens, database passwords, API keys), so an exposed editor UI is effectively an exposed credential store.

Choosing a Hosting Provider

Since n8n workflows run continuously and can spike in CPU usage during heavy executions, the underlying VPS matters more than it does for a static site. A 2-4GB RAM instance is generally the minimum for a Postgres-backed n8n instance with a handful of active workflows. DigitalOcean and Hetzner are both common choices among self-hosters for exactly this kind of workload — predictable pricing and straightforward Docker support.

Once n8n is live, uptime monitoring matters more than most people expect, since a silently crashed instance means every scheduled workflow and webhook integration stops firing without warning. A service like BetterStack can ping your n8n health endpoint and alert you before a broken automation costs you actual business data.

Backups matter just as much as hosting choice. At minimum, schedule automated dumps of the Postgres database and store the N8N_ENCRYPTION_KEY somewhere outside the VPS itself — a password manager or secrets vault works fine. Losing the encryption key without a backup means every stored credential becomes unusable, and you’ll need to reconnect every integration from scratch.

Common Issues and Troubleshooting

A few problems come up repeatedly across the n8n community forum and GitHub issues:

Webhooks return 404 — usually caused by WEBHOOK_URL not matching the actual public domain, or the workflow not being activated.

“Workflow could not be started” errors — often a symptom of SQLite lock contention; migrating to Postgres usually resolves it.

Lost credentials after redeploy — happens when N8N_ENCRYPTION_KEY isn’t persisted across container recreations; always set it explicitly rather than letting n8n generate one at random.

High memory usage — large binary data passed between nodes (files, images) stays in memory by default; configure binary data storage on disk for heavy workflows.

Timezone mismatches in scheduled triggers — set GENERIC_TIMEZONE explicitly instead of relying on the container’s default UTC.

Most of these are documented somewhere in the official docs or GitHub issues, but they’re easy to miss on a first read because they’re scattered across the hosting, node reference, and troubleshooting sections separately.

Recommended: Ready to put this into practice? DigitalOcean is a tool we use for exactly this, and we have a real, disclosed affiliate relationship with them.

FAQ

Is n8n documentation free to access?
Yes. The full n8n documentation at docs.n8n.io is free and doesn’t require an account, regardless of whether you’re using self-hosted n8n or n8n Cloud.

Do I need Docker to self-host n8n?
No, but it’s strongly recommended. npm installs work for local testing, but Docker gives you isolation, easier updates, and a repeatable setup that matches what most of the community and documentation examples assume.

Is n8n really free for self-hosting?
Yes, self-hosted n8n is available under a fair-code license (Sustainable Use License) that’s free for internal business use. Reselling n8n as a hosted service to third parties requires a separate agreement.

What database should I use with n8n?
SQLite works for testing, but Postgres is the recommended production database according to n8n’s own hosting documentation — it handles concurrent workflow executions far more reliably.

Where can I find pre-built workflow templates?
The official n8n website has a template library with thousands of community-submitted workflows you can import directly into your instance and modify instead of building from scratch.

How do I update a self-hosted n8n instance?
If you’re running Docker, pull the latest image and recreate the container: docker compose pull && docker compose up -d. Always back up your database and N8N_ENCRYPTION_KEY before updating a production instance.