dokploy-compose-structure

Dokploy Compose Structure

When to Use This Skill

• When creating a new Dokploy template from scratch
• When converting an existing docker-compose to Dokploy format
• When adding new services to existing Dokploy templates
• When user asks to "create a dokploy template for [application]"
• When user asks about "dokploy compose patterns"

When NOT to Use This Skill

• For Kubernetes manifests (use kubernetes patterns instead)
• For standalone Docker deployments without Dokploy
• For modifying existing working templates without understanding context (use dokploy-template-validation first)

Prerequisites

• Application name and version to deploy
• Required services (database, cache, etc.)
• Port mappings needed for external access
• Storage requirements (persistent volumes)

---

Core Patterns

Pattern 1: Network Structure (MANDATORY)

Every Dokploy template MUST have exactly two networks:

networks:
  ${app-name}-net:
    driver: bridge
  dokploy-network:
    external: true

Rules:

• ${app-name}-net: Internal app communication (bridge driver)
• dokploy-network: External network for Traefik routing (ALWAYS external: true)
• Web-facing services connect to BOTH networks
• Internal-only services (databases) connect ONLY to app-net

Pattern 2: Service Definition Template

services:
  ${service-name}:
    image: ${image}:${version}  # ALWAYS pin version, NEVER use :latest
    restart: always             # ALWAYS set restart policy
    depends_on:
      ${dependency}:
        condition: service_healthy  # Use health-based dependencies
    volumes:
      - ${volume-name}:/path/in/container
    environment:
      REQUIRED_VAR: ${REQUIRED_VAR:?Set description here}
      OPTIONAL_VAR: ${OPTIONAL_VAR:-default_value}
    networks:
      - ${app-name}-net
      - dokploy-network  # ONLY for web-facing services
    labels:
      - "traefik.enable=true"
      # ... additional traefik labels
    healthcheck:
      test: ["CMD", "command"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 30s