pulse-memory/skills/xcloud-docker-deploy/references/scenario-proxy-conflict.md

Scenario: Proxy/SSL Conflict & Multi-Port Apps

Detection

This scenario applies when docker-compose.yml contains any of:

• A Caddy, Traefik, nginx-proxy, or similar reverse-proxy service
• Multiple exposed ports (e.g., 3001 for API, 3002 for frontend)
• External config files referenced via volume mounts (e.g., ./nginx.conf:/etc/nginx/nginx.conf)
• SSL/TLS config (certresolver, Let's Encrypt, ACME)

Real example — Rybbit Analytics:

services:
  caddy:           # ← conflicts with xCloud's nginx
    image: caddy
    ports: ["80:80", "443:443"]
  clickhouse: ...
  backend:
    ports: ["3001:3001"]   # ← multiple ports
  frontend:
    ports: ["3002:3002"]   # ← multiple ports

Solution Overview

1. Remove the proxy/SSL service (Caddy/Traefik/nginx-proxy)
2. Remove SSL-related labels and config
3. Add a lightweight nginx-router service that routes internal traffic
4. Embed the nginx config inline using the configs: block (no external files)
5. Expose a single port (e.g., 3080) for xCloud to proxy to

Architecture After Fix

xCloud Nginx (443) → nginx-router:3080 → backend:3001 (API)
                                        → frontend:3002 (UI)

Step 1 — Remove Proxy Service

Delete the entire Caddy/Traefik/nginx-proxy service block. Remove any labels: containing traefik.* or Caddy directives from other services. Remove port mappings "80:80" and "443:443".

Step 2 — Remove External Port Mappings from App Services

Backend and frontend services should NOT expose ports directly to the host. Remove their ports: sections — they communicate internally via Docker network.

# BEFORE
backend:
  ports:
    - "3001:3001"

# AFTER
backend:
  expose:
    - "3001"    # internal only — accessible within Docker network

Step 3 — Add nginx-router Service with Embedded Config

Use the configs: top-level block to embed nginx config inline:

services:
  nginx-router:
    image: nginx:alpine
    ports:
      - "3080:80"     # ← single port xCloud proxies to
    configs:
      - source: nginx_config
        target: /etc/nginx/conf.d/default.conf
    depends_on:
      - backend
      - frontend
    networks:
      - app-network

configs:
  nginx_config:
    content: |
      server {
        listen 80;

        location /api/ {
          proxy_pass http://backend:3001/;
          proxy_set_header Host $host;
          proxy_set_header X-Real-IP $remote_addr;
          proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
          proxy_set_header X-Forwarded-Proto $scheme;
        }

        location / {
          proxy_pass http://frontend:3002/;
          proxy_set_header Host $host;
          proxy_set_header X-Real-IP $remote_addr;
          proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
          proxy_set_header X-Forwarded-Proto $scheme;
        }
      }

Note: The configs: inline content: feature requires Docker Compose v2.23+ / Docker Engine 25+. For older versions, use a heredoc in a startup command instead (see below).

Alternative: Inline Config via Command

If configs.content is not supported:

nginx-router:
  image: nginx:alpine
  ports:
    - "3080:80"
  command: >
    sh -c "echo 'server {
      listen 80;
      location /api/ { proxy_pass http://backend:3001/; }
      location / { proxy_pass http://frontend:3002/; }
    }' > /etc/nginx/conf.d/default.conf && nginx -g 'daemon off;'"

Step 4 — Ensure Shared Network

All services must be on the same Docker network for internal routing:

services:
  nginx-router:
    networks: [app-network]
  backend:
    networks: [app-network]
  frontend:
    networks: [app-network]

networks:
  app-network:
    driver: bridge

Step 5 — xCloud Configuration

• Exposed port: 3080 (or whatever single port you chose)
• No SSL config needed — xCloud handles it
• All env vars added via xCloud UI

Common Routing Patterns

App type	Route pattern
API + SPA	/api/* → backend, /* → frontend
API + SSR	/api/* → api-service, /* → web-service
Multiple APIs	/api/v1/* → service-a, /api/v2/* → service-b
WebSocket	Add proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade";