Docker Redis Setup for n8n: Step-by-Step Guide

Step by Step Guide for Docker Redis Setup for n8n

 

 

Who this is for: DevOps engineers and n8n power‑users who need a reliable, production‑grade Redis instance behind Docker Compose. For a complete overview of Redis usage, errors, performance tuning, and scaling in n8n, check out our detailed guide on Redis for n8n Workflows.

---

Quick Diagnosis

Add the two service definitions below to your docker‑compose.yml, set a password in a .env file, and run docker compose up -d.

Redis service (5 lines) – creates a secure, persistent Redis container.

redis:
  image: redis:7-alpine
  command: ["redis-server","--requirepass","${REDIS_PASSWORD}","--appendonly","yes"]
  volumes: [redis-data:/data]
  networks: [n8n-net]

n8n service (5 lines) – connects n8n to the Redis container.

n8n:
  image: n8nio/n8n:latest
  depends_on:
    redis:
      condition: service_healthy
  environment:
    - N8N_REDIS_HOST=redis
    - N8N_REDIS_PORT=6379
    - N8N_REDIS_PASSWORD=${REDIS_PASSWORD}
  networks: [n8n-net]

Add the network and volume definitions (unchanged from the snippet above) and you’re ready to start.

---

1. Why Run Redis in a Dedicated Container?

Benefit	Reason
Stateful workflow execution	n8n stores execution data, queue jobs, and cache in Redis.
Low latency	In‑memory access is far faster than SQLite or file‑based queues.
Horizontal scalability	Separate Redis lets you add n8n workers without losing state.

EEFA – Never expose port 6379 to the public internet. Keep Redis on an internal Docker network (n8n-net) and protect it with a strong password.

---

2. Prerequisites

Requirement	Minimum version
Docker Engine	20.10+
Docker Compose (v2 plugin)	2.5+
n8n	1.0+ (Redis support)

*Verify each tool with docker version, docker compose version, and docker exec <n8n> n8n --version.*
Before continuing, make sure your Redis instance is secure. I’ve explained the process in detail Securing Redis for n8n. Once done, return here to proceed

---

3. Compose File Deep‑Dive

3.1 Redis Service Details

Setting	Value	Why it matters
Image	redis:7-alpine	Small footprint, up‑to‑date security patches.
–requirepass	${REDIS_PASSWORD}	Enforces authentication; mandatory in production.
–appendonly yes	AOF persistence	Guarantees durability with minimal data loss.

3.2 Persistent Volume

# Create a backup of the Redis AOF file (5 lines)
docker run --rm \
  -v redis-data:/data \
  -v "$(pwd)":/backup \
  alpine \
  tar czf /backup/redis-backup-$(date +%F).tar.gz /data

*Using a named volume (redis-data) ensures data survives container recreation.*

3.3 Network Isolation

All services join n8n-net, a user‑defined bridge network. This isolates Redis from the host and any external network while allowing DNS‑based discovery (redis → container IP).

3.4 Healthcheck

healthcheck:
  test: ["CMD","redis-cli","-a","${REDIS_PASSWORD}","ping"]
  interval: 10s
  timeout: 5s
  retries: 3

n8n’s depends_on waits for a healthy Redis, eliminating race conditions at startup.

3.5 n8n Environment Variables

Variable	Value	Purpose
N8N_REDIS_HOST	redis	Service name on n8n-net.
N8N_REDIS_PORT	6379	Default Redis port.
N8N_REDIS_PASSWORD	${REDIS_PASSWORD}	Must match Redis password.

EEFA – To avoid plain‑text passwords, replace ${REDIS_PASSWORD} with a Docker secret reference ({{ secret "redis_password" }}) and mount the secret into both containers.

---

4. Step‑by‑Step Setup

1. Create a project directory

   mkdir n8n-redis && cd n8n-redis

2. Add a .env file (never commit to VCS)

   REDIS_PASSWORD=SuperSecret123!

3. Create docker-compose.yml – paste the TL;DR snippets and the network/volume sections.
4. Start the stack

   docker compose up -d

5. Confirm Redis is healthy

   docker compose ps redis
   # STATUS column should show “healthy”

6. Check n8n’s Redis connection

   docker exec -it $(docker compose ps -q n8n) \
     curl -s http://localhost:5678/api/v1/healthz | jq .redis

   Expected output: "connected".

7. Schedule regular backups – add the backup command from §3.2 to a host cron job.
8. To get the best performance out of Redis, follow this optimization guide Optimizing Redis for n8n performance. After completing it, continue with the workflow below.

---

5. Production‑Ready Checklist

Item	Reason
Strong, unique password	Stops unauthorized access.
AOF persistence (appendonly yes)	Minimises data loss on crash.
Dedicated Docker network	Isolates Redis from the public.
Healthcheck + depends_on	Guarantees ordered startup.
Resource limits (optional)	Prevents Redis from exhausting host memory.
Regular backups	Enables disaster recovery.
Monitoring (e.g., redis_exporter)	Detects latency spikes and memory pressure.
Pin Redis image tag (e.g., redis:7.2.4-alpine)	Avoids accidental breaking changes.

---

6. Common Pitfalls & Fixes

Symptom	Likely cause	Remedy
ERR invalid password in n8n logs	Password mismatch	Verify ${REDIS_PASSWORD} is identical in .env and the Redis command; restart the stack.
docker compose up hangs on Redis	Volume permission issue	Ensure the host directory used by redis-data is owned by UID 999 (Redis default).
Latency > 100 ms	AOF file growth	Add auto-aof-rewrite-percentage 100 and auto-aof-rewrite-min-size 64mb to the Redis command args.
Container restarts repeatedly	Healthcheck failing (wrong password)	Test manually: docker exec redis redis-cli -a $REDIS_PASSWORD ping. Adjust the healthcheck if needed.

 

---

Next Steps

1. Enable TLS on Redis (requires a custom image or sidecar).
2. Add redis_exporter to the compose file for Prometheus metrics.
3. Configure Redis ACLs if multiple applications share the same Redis instance.

---

Conclusion

Deploying Redis as a dedicated, password‑protected container gives n8n a fast, persistent queue and cache layer that survives container restarts and scales horizontally. By pinning the Redis image, using AOF persistence, isolating the service on an internal network, and adding healthchecks, you eliminate the most common connectivity and reliability problems in production. Follow the checklist, back up the volume regularly, and monitor key metrics to keep the stack robust and secure.