Dokploy Traefik Routing

When to Use This Skill

• When adding web-accessible services to Dokploy templates
• When configuring SSL/TLS certificates via LetsEncrypt
• When setting up custom routing rules (path-based, subdomain)
• When enabling Cloudflare DNS challenge for wildcard certs
• When user asks about "traefik routing" or "SSL setup"

When NOT to Use This Skill

• For non-HTTP services (raw TCP/UDP ports) - use port mapping instead
• For internal-only services (databases, caches) - no Traefik needed
• For services behind Cloudflare Tunnel - different configuration

Prerequisites

• Service must connect to

  dokploy-network

• Domain name configured in environment variables
• LetsEncrypt resolver configured in Traefik (standard in Dokploy)

---

Core Patterns

Pattern 1: Standard HTTPS Routing (Most Common)

Every web-facing service needs these 6 labels:

labels:
  - "traefik.enable=true"
  - "traefik.http.routers.${service}.rule=Host(`${DOMAIN}`)"
  - "traefik.http.routers.${service}.entrypoints=websecure"
  - "traefik.http.routers.${service}.tls.certresolver=letsencrypt"
  - "traefik.http.services.${service}.loadbalancer.server.port=${port}"
  - "traefik.docker.network=dokploy-network"

Explanation:

1. traefik.enable=true

   - Enable Traefik routing for this service

2. rule=Host(...)

   - Match requests to this domain

3. entrypoints=websecure

   - Use HTTPS (port 443)

4. tls.certresolver=letsencrypt

   - Auto-provision SSL certificate

5. loadbalancer.server.port

   - Internal container port

6. docker.network

   - Which network Traefik uses to reach service

Pattern 2: Cloudflare DNS Challenge

For wildcard certificates or when HTTP challenge isn't possible:

labels:
  - "traefik.enable=true"
  - "traefik.http.routers.${service}.rule=Host(`${DOMAIN}`)"
  - "traefik.http.routers.${service}.entrypoints=websecure"
  - "traefik.http.routers.${service}.tls.certresolver=cloudflare"
  - "traefik.http.routers.${service}.tls.domains[0].main=${BASE_DOMAIN}"
  - "traefik.http.routers.${service}.tls.domains[0].sans=*.${BASE_DOMAIN}"
  - "traefik.http.services.${service}.loadbalancer.server.port=${port}"
  - "traefik.docker.network=dokploy-network"

Note: Requires Cloudflare API credentials in Traefik configuration.

Pattern 3: Path-Based Routing

Route different paths to different services:

# Main app
labels:
  - "traefik.http.routers.app.rule=Host(`${DOMAIN}`)"
  # ...

# API service
labels:
  - "traefik.http.routers.api.rule=Host(`${DOMAIN}`) && PathPrefix(`/api`)"
  - "traefik.http.routers.api.entrypoints=websecure"
  - "traefik.http.routers.api.tls.certresolver=letsencrypt"
  - "traefik.http.services.api.loadbalancer.server.port=8080"
  - "traefik.docker.network=dokploy-network"

Pattern 4: Subdomain Routing

Route subdomains to different services:

# Main app at example.com
labels:
  - "traefik.http.routers.app.rule=Host(`${DOMAIN}`)"
  # ...

# Admin at admin.example.com
labels:
  - "traefik.http.routers.admin.rule=Host(`admin.${DOMAIN}`)"
  - "traefik.http.routers.admin.entrypoints=websecure"
  - "traefik.http.routers.admin.tls.certresolver=letsencrypt"
  - "traefik.http.services.admin.loadbalancer.server.port=9000"
  - "traefik.docker.network=dokploy-network"

Pattern 5: Multiple Routers per Service

When a service needs different ports exposed:

labels:
  # Web UI
  - "traefik.http.routers.service-web.rule=Host(`${DOMAIN}`)"
  - "traefik.http.routers.service-web.entrypoints=websecure"
  - "traefik.http.routers.service-web.tls.certresolver=letsencrypt"
  - "traefik.http.services.service-web.loadbalancer.server.port=3000"
  # API endpoint
  - "traefik.http.routers.service-api.rule=Host(`api.${DOMAIN}`)"
  - "traefik.http.routers.service-api.entrypoints=websecure"
  - "traefik.http.routers.service-api.tls.certresolver=letsencrypt"
  - "traefik.http.services.service-api.loadbalancer.server.port=8080"
  - "traefik.docker.network=dokploy-network"

Pattern 6: Middleware for Security Headers

Add security headers or other middleware:

labels:
  - "traefik.enable=true"
  - "traefik.http.routers.app.rule=Host(`${DOMAIN}`)"
  - "traefik.http.routers.app.entrypoints=websecure"
  - "traefik.http.routers.app.tls.certresolver=letsencrypt"
  - "traefik.http.routers.app.middlewares=security-headers@docker"
  # Define middleware
  - "traefik.http.middlewares.security-headers.headers.stsSeconds=31536000"
  - "traefik.http.middlewares.security-headers.headers.stsIncludeSubdomains=true"
  - "traefik.http.middlewares.security-headers.headers.contentTypeNosniff=true"
  - "traefik.http.middlewares.security-headers.headers.frameDeny=true"
  - "traefik.http.services.app.loadbalancer.server.port=3000"
  - "traefik.docker.network=dokploy-network"

Pattern 7: CORS Middleware (for APIs)

Enable CORS for API services:

labels:
  - "traefik.enable=true"
  - "traefik.http.routers.api.rule=Host(`api.${DOMAIN}`)"
  - "traefik.http.routers.api.entrypoints=websecure"
  - "traefik.http.routers.api.tls.certresolver=letsencrypt"
  - "traefik.http.routers.api.middlewares=cors@docker"
  # CORS middleware
  - "traefik.http.middlewares.cors.headers.accessControlAllowMethods=GET,POST,PUT,DELETE,OPTIONS"
  - "traefik.http.middlewares.cors.headers.accessControlAllowHeaders=Content-Type,Authorization"
  - "traefik.http.middlewares.cors.headers.accessControlAllowOriginList=https://${DOMAIN}"
  - "traefik.http.middlewares.cors.headers.accessControlMaxAge=100"
  - "traefik.http.services.api.loadbalancer.server.port=8080"
  - "traefik.docker.network=dokploy-network"

---

Complete Examples

Example 1: Basic HTTPS Service (Paaster)

services:
  paaster:
    image: wardpearce/paaster:3.1.7
    networks:
      - paaster-net
      - dokploy-network
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.paaster.rule=Host(`${PAASTER_DOMAIN}`)"
      - "traefik.http.routers.paaster.entrypoints=websecure"
      - "traefik.http.routers.paaster.tls.certresolver=letsencrypt"
      - "traefik.http.services.paaster.loadbalancer.server.port=3000"
      - "traefik.docker.network=dokploy-network"

Example 2: Git Service with SSH (Forgejo)

services:
  forgejo:
    image: codeberg.org/forgejo/forgejo:9
    ports:
      - "${SSH_PORT:-2222}:22"  # SSH access (raw port, not Traefik)
    networks:
      - forgejo-net
      - dokploy-network
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.forgejo.rule=Host(`${FORGEJO_DOMAIN}`)"
      - "traefik.http.routers.forgejo.entrypoints=websecure"
      - "traefik.http.routers.forgejo.tls.certresolver=letsencrypt"
      - "traefik.http.services.forgejo.loadbalancer.server.port=3000"
      - "traefik.docker.network=dokploy-network"

Example 3: Service with Admin Subdomain

services:
  app:
    image: myapp:1.0.0
    networks:
      - app-net
      - dokploy-network
    labels:
      # Main application
      - "traefik.enable=true"
      - "traefik.http.routers.app.rule=Host(`${DOMAIN}`)"
      - "traefik.http.routers.app.entrypoints=websecure"
      - "traefik.http.routers.app.tls.certresolver=letsencrypt"
      - "traefik.http.services.app.loadbalancer.server.port=8080"
      # Admin panel on subdomain
      - "traefik.http.routers.app-admin.rule=Host(`admin.${DOMAIN}`)"
      - "traefik.http.routers.app-admin.entrypoints=websecure"
      - "traefik.http.routers.app-admin.tls.certresolver=letsencrypt"
      - "traefik.http.services.app-admin.loadbalancer.server.port=9000"
      - "traefik.docker.network=dokploy-network"

---

Service Port Reference

Common service ports to use in loadbalancer configuration:

Service Type	Typical Port	Example
Nginx/Apache	80	AnonUpload
Node.js apps	3000	Paaster, Forgejo
Python/Flask	5000	Flask apps
Django/Gunicorn	8000	Paperless-ngx
Java/Spring	8080	Spring Boot
Go apps	8080	Various
Admin panels	9000-9999	Admin UIs

---

Quality Standards

Mandatory Labels

• traefik.enable=true

• traefik.http.routers.${name}.rule

  - Domain matching

• traefik.http.routers.${name}.entrypoints=websecure

• traefik.http.routers.${name}.tls.certresolver=letsencrypt

• traefik.http.services.${name}.loadbalancer.server.port

• traefik.docker.network=dokploy-network

Naming Conventions

• Router names must be unique across all services
• Use service name as router name (e.g.,

  paaster

  ,

  forgejo

  )
• For multiple routers on one service, append suffix (e.g.,

  app-web

  ,

  app-api

  )

Security Requirements

• Always use

  websecure

  entrypoint (HTTPS)
• Always use

  letsencrypt

  or

  cloudflare

  certresolver
• Consider adding security headers middleware for sensitive apps

---

Common Pitfalls

Pitfall 1: Missing dokploy-network label

Issue: Traefik can't reach service Solution: Always include

traefik.docker.network=dokploy-network

Pitfall 2: Duplicate router names

Issue: Routing conflicts, unpredictable behavior Solution: Ensure each router name is unique across all compose files

Pitfall 3: Wrong port in loadbalancer

Issue: 502 Bad Gateway errors Solution: Use the internal container port, not the exposed port

Pitfall 4: Service not on dokploy-network

Issue: Traefik can't route to service Solution: Service must be connected to

dokploy-network

Pitfall 5: Using HTTP entrypoint

Issue: Unencrypted traffic Solution: Always use

websecure

, never

web

for production

---

Integration

Skills-First Approach (v2.0+)

This skill is part of the skills-first architecture - loaded during Generation phase to add Traefik routing labels after base compose structure is created.

Related Skills

• dokploy-compose-structure

  : Network setup

• dokploy-cloudflare-integration

  : Cloudflare DNS challenge, Zero Trust

• dokploy-security-hardening

  : Security headers

Invoked By

• /dokploy-create

  command: Phase 3 (Generation) - Step 2

Order in Workflow (Progressive Loading)

1. dokploy-compose-structure

   : Create base structure
2. This skill: Add Traefik routing labels (Step 2)

3. dokploy-health-patterns

   : Add health checks

4. dokploy-cloudflare-integration

   : Add CF integration (if applicable)

5. dokploy-environment-config

   : Configure environment

6. dokploy-template-toml

   : Create template.toml

See:

.claude/commands/dokploy-create.md

for full workflow