Docker Compose Writer

Docker Compose Writer

Overview

Three modes:

Selection Mode — User asks for a category or vague need → present 3–4 real options → user picks → generate complete stack.

Direct Mode — User names a specific app or describes a full custom stack → generate immediately.

Optimize Mode — User pastes existing docker-compose.yml → audit and fix issues → write improved version.

Language: Respond in the user's language. YAML keys and comments always in English.

Step 1 — Detect Mode and Handle "Replace X" Requests

First, map "I want to replace X" requests to the right category:

Then decide mode:

Step 2 — Selection Mode: Present Options

When in Selection Mode, respond with:

Here are the best self-hosted options for [need]. Which fits your use case?

1. [App Name] — [one sentence what it is] Best for: [who/what it's best for] · RAM: [rough requirement] · Requires: [dependencies]

2. [App Name] — [one sentence] Best for: ... · RAM: ... · Requires: ...

3. [App Name] — [one sentence] Best for: ...

(Optional) 4. [App Name] — ...

Type a number to generate the full Docker Compose stack.

Never ask follow-up questions during selection — user picks a number, then generate immediately.

App Catalogue

📦 Databases & Data Stores

Extras to suggest alongside: pgAdmin (PostgreSQL UI) · RedisInsight (Redis UI) · Mongo Express (MongoDB UI)

📝 Notes, Wikis & Knowledge Base

🔒 Password Managers

☁️ File Storage & Cloud

📸 Photos

Note for Immich: Requires PostgreSQL + Redis + Machine Learning service in the same stack.

🎬 Media Servers

Media automation ( arr stack):* Suggest Sonarr + Radarr + Prowlarr + qBittorrent together when user asks for automated downloads.

📥 Media Automation (*arr Stack)

*Always generate the full arr stack together when user asks for any of these — they're meant to work as a unit.

🤖 AI / LLM

Note for Ollama: If user has NVIDIA GPU, add deploy: resources: reservations: devices for GPU passthrough.

📧 Email

Warning: Email delivery requires proper DNS (SPF, DKIM, DMARC, PTR) — mention this when generating.

🛡️ Identity, SSO & Access

🔀 Reverse Proxy

🌐 Network & Ad Blocking

🚇 Tunnels & Remote Access

Use when the server is behind CGNAT, ISP blocks ports 80/443, or you don't want to open firewall ports.

Cloudflare Tunnel pattern:

services:
  cloudflared:
    image: cloudflare/cloudflared:latest
    restart: unless-stopped
    command: tunnel --no-autoupdate run --token ${CLOUDFLARE_TUNNEL_TOKEN}
    networks:
      - app_network

Token from: Cloudflare Zero Trust → Networks → Tunnels → Create tunnel → Docker

📖 RSS & Read Later

📚 Books, Comics & Audiobooks

🔗 Bookmarks & Links

💰 Finance & Budget

📊 Analytics & Business Intelligence

🐙 Git & Code Hosting

🚀 CI/CD

📦 Container Registry

✅ Project Management & Productivity

🗓️ Calendar & Contacts

💬 Chat & Communication

🔔 Notifications

📊 Monitoring & Observability

For full observability stacks → use /linux-monitoring-setup instead.

🏠 Home Automation

🛠️ Developer Tools & Utilities

Watchtower note: By default updates all containers. Use --label-enable flag and add com.centurylinklabs.watchtower.enable: "true" only to containers you want auto-updated.

Step 3 — Generate the Compose Stack

After the user selects (or in Direct Mode), generate the complete, working stack immediately. No more questions.

Quality Standards — Every compose file MUST have:

Companion Service Health Check Templates

When generating Redis as a companion service, always include a health check so dependent services use condition: service_healthy:

  redis:
    image: redis:7-alpine
    restart: unless-stopped
    volumes:
      - redis_data:/data
    networks:
      - app_network
    healthcheck:
      test: ["CMD", "redis-cli", "--raw", "ping"]
      # redis:7-alpine includes redis-cli. For minimal custom images use:
      # test: ["CMD", "sh", "-c", "redis-cli ping | grep -q PONG"]
      interval: 10s
      timeout: 5s
      retries: 5

App-Specific Requirements

Some apps require specific companion services — always include them:

NVIDIA GPU Passthrough (for Ollama, Stable Diffusion)

Ask if user has NVIDIA GPU. If yes, add to the service:

runtime: nvidia       # Required — separate from deploy.resources
deploy:
  resources:
    reservations:
      devices:
        - driver: nvidia
          count: all
          capabilities: [gpu]

Requirements:

• NVIDIA Container Toolkit must be installed on host (both runtime: and deploy: require it)
• After install: sudo systemctl restart docker
• Test GPU access: docker run --rm --runtime=nvidia nvidia/cuda:12.0-base nvidia-smi

Install guide: https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/install-guide.html

Traefik Middleware Labels (add when Traefik is in the stack)

When generating services behind Traefik, offer these middleware patterns for exposed services:

Basic Auth (protect internal tools — pgAdmin, Grafana, etc.):

labels:
  traefik.http.middlewares.myapp-auth.basicauth.users: "${BASIC_AUTH_USERS}"
  # Generate hash: echo $(htpasswd -nB admin) | sed -e s/\\$/\\$\\$/g
  traefik.http.routers.myapp.middlewares: "myapp-auth@docker"

Rate Limiting (protect public-facing APIs):

labels:
  traefik.http.middlewares.myapp-ratelimit.ratelimit.average: "100"
  traefik.http.middlewares.myapp-ratelimit.ratelimit.burst: "50"
  traefik.http.middlewares.myapp-ratelimit.ratelimit.period: "1m"
  traefik.http.routers.myapp.middlewares: "myapp-ratelimit@docker"

Force HTTPS Redirect (HTTP → HTTPS on port 80):

labels:
  traefik.http.middlewares.redirect-https.redirectscheme.scheme: "https"
  traefik.http.middlewares.redirect-https.redirectscheme.permanent: "true"
  traefik.http.routers.myapp-http.rule: "Host(`${DOMAIN}`)"
  traefik.http.routers.myapp-http.entrypoints: "web"
  traefik.http.routers.myapp-http.middlewares: "redirect-https@docker"

IP Allowlist (restrict to specific IPs — e.g. internal only):

labels:
  traefik.http.middlewares.myapp-ipallowlist.ipallowlist.sourcerange: "192.168.1.0/24,10.0.0.0/8"
  traefik.http.routers.myapp.middlewares: "myapp-ipallowlist@docker"

Middlewares can be chained: middlewares: "redirect-https@docker,myapp-auth@docker"

Step 4 — Write Files Silently

Do NOT print the compose file or .env.example content in chat. Write them to disk silently.

File locations — kebab-case subdirectory in current working directory:

[app-name]/
  docker-compose.yml    ← complete, production-ready
  .env.example          ← all required vars with descriptions and safe placeholder values

Generate complete .env.example — every env var must have:

• A comment explaining what it is
• A safe placeholder value (not empty — CHANGE_ME_strong_password_here, your-domain.com, etc.)
• A note if it's auto-generated (e.g. # Generate with: openssl rand -hex 32)

Output — print ONLY this after writing:

✅ [App Name] stack created in ./[app-name]/

▶ Setup:
  cd [app-name]
  cp .env.example .env
  nano .env              # ← edit ALL passwords and domain settings first!

▶ Start:
  docker compose up -d

▶ Check health:
  docker compose ps
  docker compose logs -f [service-name]

📋 Useful commands:
  docker compose pull && docker compose up -d    # update to latest images
  docker compose down                            # stop (data preserved)
  docker compose down -v                         # ⚠️  stop + DELETE ALL DATA

💾 Backup volumes (before updating or migrating):
  docker run --rm -v [volume_name]:/data -v $(pwd):/backup alpine \
    tar czf /backup/[volume_name]-$(date +%Y%m%d).tar.gz -C /data .
  # Restore: tar xzf [volume_name]-YYYYMMDD.tar.gz -C /data

🌐 Access: http://localhost:[PORT]
[default login credentials if applicable]

⚠️  [Any important warnings — email DNS, firewall ports, first-run setup steps]

💡 Next steps:
  [1-2 relevant next steps, e.g. "Set up Traefik for HTTPS → /docker-compose-writer Traefik"]
  [e.g. "Back up volumes → /linux-backup-restore Docker volumes"]
  [e.g. "Monitor this stack → /linux-monitoring-setup for Prometheus + Grafana"]

List each UI separately if multiple services expose ports:

🌐 App:      http://localhost:8080
🌐 Admin UI: http://localhost:9000  (admin / [password from .env])

Optimize Mode (existing compose pasted)

When user pastes an existing compose file:

1. Audit silently for all issues:

   • latest image tags → pin to specific version
   • Hardcoded secrets → replace with ${ENV_VAR}
   • Missing health checks → add working test commands
   • Missing restart policy → add unless-stopped
   • Default bridge network → add named network
   • Missing log limits → add logging block
   • privileged: true without reason → warn and remove if possible
   • Bind mounts for DB data → move to named volumes

2. Write fixed docker-compose.yml to ./[app-name]/docker-compose.yml

3. If secrets were hardcoded, also write .env.example

4. Print only:

✅ Optimized compose written to ./[app-name]/docker-compose.yml
   Fixed [N] issues:
   - Pinned [X] image tags (removed :latest)
   - Moved secrets to .env.example
   - Added health checks to [services]
   - Added log rotation limits
   - [other changes]

🌐 Access: http://localhost:[PORT]

Security Rules (non-negotiable)

• No inline secrets — ${ENV_VAR} only, never password: mysecret
• Read-only config mounts — always :ro for config files that the app only reads
• cap_drop: [ALL] — drop all Linux capabilities; add back only what's explicitly needed
• Never privileged: true — if the user insists, warn with the security risk and require explicit confirmation
• Non-root user — user: "1000:1000" for app services where the image supports it
• Internal networks — services that communicate only internally must NOT have ports: exposed to host
• Log limits — always add logging block to prevent disk fill from container logs

Homelab / Multi-App Stacks

When user asks for a "full homelab setup", "all my self-hosted apps in one compose", or similar:

1. Ask which categories they want: file cloud, media, monitoring, git, CI/CD, etc.
2. Generate a single docker-compose.yml with all requested apps + shared infrastructure (Traefik as reverse proxy, shared PostgreSQL, shared Redis)
3. Use Traefik labels for routing instead of port mappings where possible
4. Group services with comments (# ── Media ──, # ── Storage ──, etc.)