self hosting

n8n Docker Volume Persistence: Avoid Losing Workflows and Credentials

Persistent Docker storage is mandatory for self-hosted n8n because workflows, credentials, settings, and the default SQLite database live under the n8n user data directory.

Match your incident first

Start with the symptom you can prove

Jump to checks

Container restarts after upgrade or compose pull

First check: Run docker compose ps and inspect the last 100 n8n log lines.

Wrong fix to avoid: Do not delete volumes to make the container start.

Verify: Container stays healthy and existing workflows/credentials remain visible.

Workflows disappear after recreating container

First check: Check compose volumes and whether /home/node/.n8n is persisted.

Wrong fix to avoid: Do not create new workflows until you confirm whether old data exists in a volume or backup.

Verify: A restart preserves workflows, credentials, executions, and settings.

Production URL is wrong in Docker deployment

First check: Inspect only the public URL-related env vars and the proxy route.

Wrong fix to avoid: Do not expose the container directly on the public internet to bypass proxy config.

Verify: Webhook URLs in the editor use the intended HTTPS domain.

Use when: self-hosted, Docker
First check: Confirm workflows and credentials survive a restart before sending real traffic.
Time to check: 5-10 minutes
Next step: Match the symptom, then run the verification checks.

Independent third-party notes. n8n is a trademark of its owner and is referenced only for compatibility and troubleshooting context.

Quick Answer

Persistent Docker storage is mandatory for self-hosted n8n because workflows, credentials, settings, and the default SQLite database live under the n8n user data directory.

Does this match your symptom?

Self-hosted Docker setup looks risky

The instance runs, but persistence, .env files, public URLs, HTTPS, Postgres, or backups are unclear.

First check: Confirm workflows and credentials survive a restart before sending real traffic.

Primary path n8n Docker Compose Setup: Persistent Volume, .env, Postgres, and Webhooks Related check N8N Docker Compose .env File Related check N8N SSL Setup Still blocked? Generate a diagnostic brief

Problem Pattern

The user recreated or updated a container and workflows, credentials, SQLite data, or community node packages disappeared.

Version awareness

Last reviewed 2026-05-21

Applies to: self-hosted n8n, Docker Compose, Postgres, reverse proxy, backup/restore
Official docs checked: n8n Docker Installation, n8n Community Nodes Troubleshooting, n8n Supported Databases
Version-sensitive assumptions: n8n node parameters, credential names, and queue mode defaults can change between releases; confirm against your installed version before changing production.
What may change after upgrades: Node parameter names, credential scopes, webhook behavior, Docker image defaults, and queue worker expectations may shift after n8n upgrades.

Key Facts

Important path: /home/node/.n8n inside the official container.
Default SQLite file: ~/.n8n/database.sqlite for self-hosted SQLite setups.
Community nodes path: ~/.n8n/nodes for installed community packages.
Main risk: Recreating a container without the right volume can lose data.

Production Diagnostic Matrix

Turn checks into a brief

Exact symptom or log	Likely cause	First check	Wrong fix to avoid	Verification
Container restarts after upgrade or compose pull	Missing required env var, incompatible database migration, or invalid compose service config.	Run docker compose ps and inspect the last 100 n8n log lines.	Do not delete volumes to make the container start.	Container stays healthy and existing workflows/credentials remain visible.
Workflows disappear after recreating container	n8n data was stored inside the container instead of a persistent volume or external database.	Check compose volumes and whether /home/node/.n8n is persisted.	Do not create new workflows until you confirm whether old data exists in a volume or backup.	A restart preserves workflows, credentials, executions, and settings.
Production URL is wrong in Docker deployment	WEBHOOK_URL, N8N_HOST, N8N_PROTOCOL, or reverse proxy labels are missing or inconsistent.	Inspect only the public URL-related env vars and the proxy route.	Do not expose the container directly on the public internet to bypass proxy config.	Webhook URLs in the editor use the intended HTTPS domain.
Database or volume permission errors after moving hosts	File ownership, mounted path, or Postgres credentials changed during migration.	Check volume mount paths, container UID expectations, and database auth logs.	Do not chmod everything recursively without a backup.	n8n starts and can read previous workflows after one restart.
Backup exists but restore does not work	Backup missed the database, .n8n folder, encryption key, or binary data storage.	Verify restore in a disposable environment before touching production.	Do not assume a SQL dump alone is enough when binary data or SQLite is used.	A restored test instance can open workflows, decrypt credentials, and run a smoke test.
Upgrade breaks a previously working workflow	Node behavior, credential schema, API response shape, or custom node compatibility changed.	Compare failing execution before/after upgrade and check release notes for affected nodes.	Do not immediately downgrade without checking database migration and rollback safety.	Smoke tests for triggers, credentials, expressions, and outbound calls pass on the target version.

Recommended Steps

Create a named Docker volume or host bind mount for n8n data.
Mount it to /home/node/.n8n in the n8n container.
If using community nodes, ensure ~/.n8n/nodes is also persistent.
Restart the container and create a test workflow.
Recreate the container and verify the workflow remains.

Verification

The same workflows appear after container recreation.
Credentials remain available after restart.
Community nodes still load after rebuilding the container.

First Commands / Checks

Check container state Use first when n8n is down, restarting, or behaving differently after a deploy.

docker compose ps

Secrets note: This lists service names and status only; it should not print credential values.
Verification: n8n, database, Redis, and worker services are running or the failing service is obvious.

Read recent n8n logs Use when the editor, webhook, or startup path fails.

docker compose logs n8n --tail=100

Secrets note: Review before sharing; remove tokens, private hostnames, and customer payloads.
Verification: The log contains a timestamped error, migration message, or clean startup line.

Check public URL variables only Use when webhook URLs show localhost, http, or the wrong domain.

docker compose exec n8n printenv WEBHOOK_URL N8N_HOST N8N_PROTOCOL N8N_EDITOR_BASE_URL

Secrets note: Do not run a full env dump in public channels; print only these non-secret routing names.
Verification: Values point to the intended HTTPS public domain.

Safe Copyable Config

Minimal Docker Compose for a single n8n instance Use for a small self-hosted instance before adding queue mode or external Postgres.

services:
  n8n:
    image: n8nio/n8n:latest
    restart: unless-stopped
    ports:
      - "5678:5678"
    environment:
      - N8N_HOST=automation.example.com
      - N8N_PROTOCOL=https
      - WEBHOOK_URL=https://automation.example.com/
      - GENERIC_TIMEZONE=UTC
    volumes:
      - n8n_data:/home/node/.n8n

volumes:
  n8n_data:

What to change: Replace automation.example.com with your real public domain. Pin a tested n8n image tag before production upgrades.
Secrets to keep private: Do not paste production credentials into compose comments or public tickets. Keep the mounted .n8n data and encryption key backed up privately.
Verification: docker compose ps shows n8n running. Restarting the container keeps workflows and credentials visible.
Common mistakes: Using localhost in WEBHOOK_URL. Running without a persistent volume. Changing domains without updating OAuth/webhook providers.

Backup and restore checklist Use before upgrades, host moves, and restore drills.

# Backup Postgres in a private shell
docker compose exec postgres pg_dump -U n8n_app n8n > backup-n8n.sql

# Record non-secret runtime facts
docker compose ps > backup-services.txt
docker compose exec n8n printenv WEBHOOK_URL DB_TYPE N8N_BINARY_DATA_MODE > backup-runtime-public.txt

# Restore only into a disposable test environment first
psql "postgresql://n8n_app:REDACTED@postgres:5432/n8n_restore" < backup-n8n.sql

What to change: Use your real private database connection locally. Add binary data and volume backups based on your storage mode.
Secrets to keep private: Database password N8N_ENCRYPTION_KEY credential exports binary files containing customer data
Verification: A restored test instance can open workflows, decrypt credentials, and run a smoke test.
Common mistakes: Testing restore for the first time during an outage. Forgetting N8N_ENCRYPTION_KEY. Backing up the database but not binary data.

Warnings

Container filesystem storage is not a backup strategy.
Back up both the n8n data directory and any external database.

Best For

Docker users who want workflows and credentials to survive container replacement.
Teams using the default SQLite database in a containerized setup.
Instances that install community nodes and need package files to persist.

Not For

Disposable one-command demos where losing data is acceptable.
Managed n8n Cloud deployments.
Users who have already moved all durable data into managed external services and documented that setup.

Common Mistakes

Mounting the wrong host directory or container path.
Backing up the Compose file but not the actual Docker volume.
Persisting workflows but forgetting community node packages.
Deleting a named volume during cleanup and losing SQLite data.

Examples

Named volume mount The important part is the target path inside the container.

volumes:
  n8n_data:

services:
  n8n:
    image: docker.n8n.io/n8nio/n8n
    volumes:
      - n8n_data:/home/node/.n8n

Persistence test Run this before trusting a new deployment.

1. Create a test workflow.
2. Restart the container.
3. Confirm the workflow still exists.
4. Recreate the container without deleting the volume.
5. Confirm credentials and community nodes still load.

FAQ

What data is at risk without a volume?

On a default self-hosted Docker setup, workflows, credentials metadata, settings, SQLite data, and community node files may depend on persistent user data.

Is a Docker volume a backup?

No. A volume helps persistence, but a backup must be copied elsewhere and tested with a restore.

Do I still need this if I use Postgres?

Yes. Postgres moves database persistence out of the container, but user data, encryption key handling, and community node files still need planning.

Sources

n8n Docker Installation Accessed 2026-05-07 n8n Community Nodes Troubleshooting Accessed 2026-05-07 n8n Supported Databases Accessed 2026-05-07