Chapter 3: The Docker Stack

Last Updated: 2026-04

3.2 The Nine Services

┌─────────────────────────────────────────────────────────┐
│                    Host Machine                          │
│                                                          │
│  Port 5678 ──► iti-n8n                                   │
│  Port 3000 ──► iti-dify-web                              │
│  Port 3001 ──► iti-dify-nginx ──► iti-dify-api          │
│  Port 5432 ──► iti-postgres                              │
│                                                          │
│  Internal only:                                          │
│    iti-redis                                             │
│    iti-dify-worker                                       │
│    iti-dify-sandbox                                      │
│    iti-dify-plugin-daemon                                │
│                                                          │
│  Optional (profile: sd):                                 │
│  Port 7860 ──► iti-stable-diffusion                      │
└─────────────────────────────────────────────────────────┘

Service Reference Table

Container Name	Image	Host Port	Role
iti-postgres	pgvector/pgvector:pg16	5432	Primary database for n8n, Dify, and plugins
iti-redis	redis:7-alpine	internal	Cache and Celery task broker
iti-n8n	n8nio/n8n:latest	5678	Workflow automation engine
iti-dify-api	langgenius/dify-api:latest	internal	Dify API server
iti-dify-worker	langgenius/dify-api:latest	internal	Celery task worker for async Dify jobs
iti-dify-web	langgenius/dify-web:latest	3000	Dify web console
iti-dify-sandbox	langgenius/dify-sandbox:0.2.14	internal	Code execution sandbox
iti-dify-plugin-daemon	langgenius/dify-plugin-daemon:0.5.3-local	internal	Dify plugin runtime
iti-dify-nginx	nginx:alpine	3001	Reverse proxy for Dify API
iti-stable-diffusion	Built from infrastructure/stable-diffusion/	7860	Image generation API (profile: sd)

Note: dify-sandbox and dify-plugin-daemon are pinned to specific versions. Do not update these images without checking the Dify release notes. See Chapter 5. Note: iti-stable-diffusion uses a Docker Compose profile (sd) and does not start with the core stack. Start it with docker compose --profile sd up -d stable-diffusion. For best performance on Apple Silicon, run natively outside Docker to use Metal (MPS) acceleration — see ITI/infrastructure/stable-diffusion/README.md.

---

3.3 Service Roles in Detail

iti-postgres

PostgreSQL with the pgvector extension hosts three databases:

Database	Used By	Contents
n8n	n8n	Workflow definitions, execution history, credentials
dify	Dify API and worker	Datasets, documents, embeddings, app configs
dify_plugin	Dify plugin daemon	Plugin state

The init-db.sql script creates these databases and the pgvector extension on first startup.

iti-redis

Redis 7 serves two purposes:

1. Celery broker — the Dify worker (dify-worker) uses Redis as its task queue broker and result backend.
2. Cache — the Dify API caches frequently accessed data to reduce database load.

Redis data is ephemeral; it is not backed up. All persistent state lives in PostgreSQL.

iti-n8n

n8n is the workflow automation engine. Every product integration, scheduled job, and AI pipeline runs as an n8n workflow. n8n stores:

• Workflow definitions (in the n8n Postgres database)
• Execution logs (in the same database, pruned after 30 days)
• Credentials (encrypted in the database using N8N_ENCRYPTION_KEY)

The n8n web UI is accessible at http://localhost:5678.

Warning: The N8N_ENCRYPTION_KEY in .env encrypts all stored credentials. If this key is ever changed or lost, all credentials stored in n8n become permanently unrecoverable.

iti-dify-api and iti-dify-worker

Dify API is the backend for the Dify platform. It handles:

• Knowledge base management (documents, embeddings, retrieval)
• LLM app configuration and execution
• REST API for all Dify operations

Dify worker is a Celery worker process that handles async tasks: document indexing, embedding generation, and long-running LLM calls.

Note: dify-api and dify-worker must always run the same image version. They share the same codebase; only the entry point differs.

iti-dify-web

The Dify web console runs at http://localhost:3000. This is the primary interface for:

• Creating and managing knowledge bases
• Configuring LLM apps
• Testing retrieval and prompts

iti-dify-nginx

Nginx acts as a reverse proxy for the Dify API, exposing it at http://localhost:3001. All external integrations (products, n8n workflows) call Dify through this proxy rather than directly. The configuration lives at ITI/infrastructure/n8n-dify/dify-nginx.conf.

---

3.4 Environment Variables

All secrets and configuration are stored in ITI/infrastructure/n8n-dify/.env. This file is never committed to Git.

Critical variables:

Variable	Used By	Notes
N8N_ENCRYPTION_KEY	n8n	Encrypts credentials — never rotate this key
POSTGRES_PASSWORD	PostgreSQL	Master DB password
DIFY_SECRET_KEY	Dify API	Application secret key
CELERY_BROKER_URL	Dify worker	redis://iti-redis:6379/0
DATABASE_URL	Dify API	Points to iti-postgres

Warning: If .env is missing on startup, all services will fail. Keep a secure backup outside the repository.

---

3.5 Volumes

Docker named volumes persist data across container restarts:

Volume	Used By	Contains
postgres_data	iti-postgres	All database files
n8n_data	iti-n8n	Workflow data, encryption keys
dify_storage	iti-dify-api	Uploaded documents and files

Warning: docker compose down -v destroys all volumes and all data. Only use this after a confirmed backup.

---

3.6 Starting and Stopping the Stack

All commands run from ITI/infrastructure/n8n-dify/.

Start the full stack

cd ITI/infrastructure/n8n-dify
docker compose up -d

Stop the stack (preserve data)

docker compose down

Stop a single service

docker compose stop iti-dify-worker

Restart a single service

docker compose restart iti-n8n

View logs for all services

docker compose logs -f

View logs for one service

docker compose logs -f iti-n8n

Check container status

docker compose ps

All 9 containers should show running or healthy. If any show exited or unhealthy, see Chapter 4 — Daily Operations.

---

3.7 Service Start Order

Docker Compose starts services in dependency order:

1. iti-postgres (dependency: none)
2. iti-redis (dependency: none)
3. iti-n8n (dependency: postgres healthy)
4. iti-dify-api (dependency: postgres, redis healthy)
5. iti-dify-worker (dependency: postgres, redis healthy)
6. iti-dify-web (dependency: none — static assets)
7. iti-dify-sandbox (dependency: none)
8. iti-dify-plugin-daemon (dependency: none)
9. iti-dify-nginx (dependency: dify-api healthy)

On a cold start, allow 60–90 seconds for all services to reach healthy state before using them.

---

3.8 Resource Usage

Typical memory consumption at steady state:

Service	Typical Memory
iti-postgres	~1.5 GB
iti-dify-worker	~1.3 GB
iti-dify-api	~800 MB
iti-n8n	~400 MB
iti-dify-web	~200 MB
Other services	~100 MB each
Total	~4.5–6 GB

When running with the Stable Diffusion profile (--profile sd), add:

Service	Typical Memory
iti-stable-diffusion	~4 GB (idle with model loaded)

Thresholds (core 9 containers only):

• < 6 GB total — Normal
• 6–8 GB total — Acceptable; monitor
• > 8 GB total — Investigate; check for memory leaks

Thresholds (with Stable Diffusion):

• < 10 GB total — Normal
• 10–12 GB total — Acceptable; monitor
• > 12 GB total — Investigate; consider running SD natively instead of in Docker

docker stats --no-stream

---

Previous: Chapter 2 — Workspace Overview | Next: Chapter 4 — Daily Operations