app-docker-deploy-with-traefik

Docker + Traefik Deployment Setup

Generate production-ready Docker deployment configurations with Traefik reverse proxy integration, automatic HTTPS via Let's Encrypt.

Overview

This skill creates a deployment configuration following a proven pattern:

1. Dockerfile - Multi-stage build for the application
2. docker-compose.yml - Base service definitions
3. docker-compose.for-traefik.yml - Traefik routing overlay (composable)
4. .env.sample - Environment variable template

Instructions

Step 1: Analyze the Project

Before generating configurations, understand the project:

1. Detect the project type by examining:

   • package.json → Node.js/TypeScript
   • requirements.txt / pyproject.toml / Pipfile → Python
   • go.mod → Go
   • Cargo.toml → Rust
   • pom.xml / build.gradle → Java

2. Identify the application port from:

   • Start scripts in package.json
   • Application configuration files
   • Common defaults (3000 for Node, 8000 for Python, 8080 for Go/Java)

3. Check for existing Docker files - Don't overwrite without asking

Step 2: Generate Dockerfile

Create a multi-stage Dockerfile appropriate for the project type. See DOCKERFILES.md for templates.

Key principles:

• Use official base images with specific version tags (not :latest)
• Multi-stage builds to minimize final image size
• Non-root user for security
• Proper layer caching (dependencies before source code)
• Health checks when appropriate

Step 3: Generate docker-compose.yml

Base configuration with:

• Service definitions for app and dependencies (db, redis, etc.)
• Volume mounts for persistent data (./data/<service>:/path)
• Environment variable references (${VARIABLE})
• Restart policy: unless-stopped
• Health checks where appropriate
• Watchtower labels for auto-updates (optional)

services:
  app:
    build: .
    restart: unless-stopped
    volumes:
      - ./data/app:/app/data
    environment:
      - NODE_ENV=${NODE_ENV}
      - PORT=${PORT}
    depends_on:
      - db
    labels:
      - 'com.centurylinklabs.watchtower.enable=true'
      - 'com.centurylinklabs.watchtower.scope=${WATCHTOWER_SCOPE}'

  db:
    image: postgres:17-alpine
    restart: unless-stopped
    volumes:
      - ./data/postgres:/var/lib/postgresql/data
    environment:
      - POSTGRES_DB=${POSTGRES_DB}
      - POSTGRES_USER=${POSTGRES_USER}
      - POSTGRES_PASSWORD=${POSTGRES_PASSWORD}
    healthcheck:
      test: pg_isready -U "$$POSTGRES_USER" -d "$$POSTGRES_DB"
      interval: 10s
      timeout: 2s
      retries: 10

Step 4: Generate docker-compose.for-traefik.yml

Traefik overlay that can be composed with the base file:

services:
  app:
    networks:
      - default
      - traefik
    labels:
      - 'traefik.enable=true'
      - 'traefik.docker.network=traefik'
      # Service (internal port)
      - 'traefik.http.services.${SERVICE_NAME}.loadbalancer.server.port=${PORT}'
      # HTTPS Router
      - 'traefik.http.routers.${SERVICE_NAME}.rule=Host(`${DOMAIN}`)'
      - 'traefik.http.routers.${SERVICE_NAME}.entrypoints=websecure'
      - 'traefik.http.routers.${SERVICE_NAME}.tls=true'
      - 'traefik.http.routers.${SERVICE_NAME}.tls.certResolver=webcert'
      - 'traefik.http.routers.${SERVICE_NAME}.service=${SERVICE_NAME}'

  db:
    networks:
      - default

networks:
  traefik:
    external: true

Step 5: Generate .env.sample

Template for required environment variables:

# Domain and Deployment
DOMAIN=myapp.example.com
PORT=3000

# Database
POSTGRES_DB=myapp
POSTGRES_USER=myapp
POSTGRES_PASSWORD=change-me-in-production

# Application
NODE_ENV=production

# Auto-updates (optional)
WATCHTOWER_SCOPE=myapp

Step 6: Provide Usage Instructions

Include in the output:

1. How to copy and configure .env
2. How to run without Traefik (development)
3. How to run with Traefik (production)
4. Prerequisites (external traefik network)

Usage Commands

# Development (without Traefik)
docker compose up -d

# Production (with Traefik)
docker compose -f docker-compose.yml -f docker-compose.for-traefik.yml up -d

# Create external traefik network (first time only)
docker network create traefik

Traefik Label Reference

Label	Purpose
traefik.enable=true	Enable Traefik routing for this container
traefik.docker.network=traefik	Specify which network Traefik should use
traefik.http.services.NAME.loadbalancer.server.port=PORT	Container's internal port
traefik.http.routers.NAME.rule=Host(\domain`)`	Domain routing rule
traefik.http.routers.NAME.entrypoints=websecure	Use HTTPS entrypoint
traefik.http.routers.NAME.tls=true	Enable TLS
traefik.http.routers.NAME.tls.certResolver=webcert	Use Let's Encrypt
traefik.http.routers.NAME.service=NAME	Link router to service

Optional: Basic Auth Middleware

For admin panels or protected routes:

labels:
  # Define middleware
  - 'traefik.http.middlewares.myapp-auth.basicauth.users=${USERNAME}:${HASHED_PASSWORD}'
  # Apply to router
  - 'traefik.http.routers.myapp.middlewares=myapp-auth@docker'

Generate password hash: htpasswd -nb username password

Optional: Multiple Domains/Subdomains

# API subdomain
- 'traefik.http.routers.myapp-api.rule=Host(`api.${DOMAIN}`)'
- 'traefik.http.routers.myapp-api.entrypoints=websecure'
- 'traefik.http.routers.myapp-api.tls=true'
- 'traefik.http.routers.myapp-api.tls.certResolver=webcert'
- 'traefik.http.routers.myapp-api.service=myapp'

Best Practices

1. Use specific image tags - Never use :latest in production
2. External database volumes - Persist data outside containers
3. Secrets management - Use Docker secrets for production passwords
4. Health checks - Enable for proper orchestration
5. Resource limits - Add memory/CPU limits in production
6. Logging - Configure appropriate log drivers
7. Non-root users - Run containers as non-root when possible

Helper Scripts

Located in the scripts/ directory:

generate-htpasswd.sh

Generate password hashes for Traefik basic auth:

./scripts/generate-htpasswd.sh admin mypassword

validate-compose.py

Validate docker-compose files for common issues:

python scripts/validate-compose.py docker-compose.yml docker-compose.for-traefik.yml

Requires: pip install pyyaml

check-network.sh

Check if the traefik network exists (and optionally create it):

./scripts/check-network.sh          # Check only
./scripts/check-network.sh --create # Create if missing

Template Files

Located in the templates/ directory. Copy and customize:

Template	Description
Dockerfile.node	Node.js multi-stage build
Dockerfile.python	Python with uv package manager
docker-compose.yml	Base compose with app + PostgreSQL
docker-compose.for-traefik.yml	Traefik routing overlay
.dockerignore	Optimized Docker build context
.env.sample	Environment variables template

Replace placeholders: {{SERVICE_NAME}}, {{PORT}}, {{NODE_VERSION}}, etc.

Additional Resources

• DOCKERFILES.md - Complete Dockerfile templates for all languages
• EXAMPLES.md - Real-world deployment examples

Requirements

• Docker >= 20.10
• Docker Compose >= 2.0 (V2 syntax)
• Traefik >= 2.0 (running with webcert certificate resolver)
• External traefik network: docker network create traefik