Chapter 8: Nginx Reverse Proxy

Last Updated: 2026-03

8.2 Why a Proxy?

The Dify API runs on port 5001 inside the Docker network. The Nginx proxy:

1. Provides a stable external address — products always call localhost:3001, which remains constant even if the Dify API container moves or its internal port changes.
2. Handles CORS headers — preflight requests from browser-based clients are handled at the proxy layer, not in application code.
3. Provides SSL termination point — if HTTPS is added in the future, it is configured in Nginx without touching Dify.
4. Adds request routing — the proxy can route different URL paths to different upstream services.

---

8.3 Nginx Configuration

The configuration at ITI/infrastructure/n8n-dify/dify-nginx.conf defines:

upstream dify_api {
    server iti-dify-api:5001;
}

server {
    listen 80;

    # Handle CORS preflight requests
    location / {
        if ($request_method = OPTIONS) {
            add_header Access-Control-Allow-Origin *;
            add_header Access-Control-Allow-Methods "GET, POST, PUT, DELETE, OPTIONS";
            add_header Access-Control-Allow-Headers "Authorization, Content-Type";
            return 204;
        }

        proxy_pass http://dify_api;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }
}

Note: The actual configuration in the file may differ slightly from this summary. Always read the live config before making changes.

---

8.4 Testing the Proxy

Verify the proxy is responding

curl -s -o /dev/null -w "%{http_code}" http://localhost:3001/console/api/setup

Any HTTP status below 500 indicates the proxy is working (Dify will return 401 or 200 for this endpoint).

Test a CORS preflight request

curl -s -X OPTIONS http://localhost:3001/v1/datasets \
  -H "Origin: http://localhost" \
  -H "Access-Control-Request-Method: GET" \
  -v

Expected: a 204 No Content response with Access-Control-Allow-Origin header.

---

8.5 Reloading Nginx Configuration

After editing dify-nginx.conf, reload Nginx without restarting the container:

docker exec iti-dify-nginx nginx -t        # Test config syntax
docker exec iti-dify-nginx nginx -s reload  # Apply without downtime

If the syntax test fails, fix the error before proceeding. A broken Nginx config will cause the container to crash on restart.

---

8.6 Troubleshooting Nginx

502 Bad Gateway

The Nginx proxy is running but cannot reach the upstream Dify API.

# Check if dify-api is running
docker compose ps iti-dify-api

# Check dify-api logs
docker compose logs iti-dify-api --tail 50

# Restart both
docker compose restart iti-dify-api iti-dify-nginx

504 Gateway Timeout

The Dify API is taking too long to respond. This is usually caused by a slow LLM call or a large document indexing operation.

Add a larger proxy_read_timeout to the Nginx config if timeouts are frequent:

proxy_read_timeout 300s;
proxy_send_timeout 300s;

Nginx container not starting

docker compose logs iti-dify-nginx --tail 50

Look for configuration syntax errors. The most common cause is a missing upstream reference or a typo in the config file.

---

8.7 Adding a New Upstream

If a new service needs to be proxied through Nginx:

1. Add an upstream block to dify-nginx.conf pointing to the new container and port.
2. Add a location block routing the desired URL path to the upstream.
3. Test the config: docker exec iti-dify-nginx nginx -t
4. Reload: docker exec iti-dify-nginx nginx -s reload

Note: For services that are not Dify (e.g., a new FastAPI service), consider whether they need to share the Nginx proxy or whether they should expose their own port directly. The Dify Nginx proxy is purpose-built for Dify; new services may warrant their own proxy container.

---

Previous: Chapter 7 — Redis | Next: Chapter 9 — n8n Workflow Development