Portainer/COOLIFY-TEMPLATE.md

Coolify Compose Template — TheHomelessSherlock

Proxy & Networking Rules

Our Setup

• Proxy: coolify-proxy (Traefik v3) configured with --providers.docker.network=proxy
• TLS: certresolver letsencrypt via HTTP challenge
• Domain routing: configured in Coolify UI, NOT in compose labels

Rule 1 — Every service exposed via HTTP/HTTPS must be on the proxy network

services:
  myapp:
    image: myimage:latest
    pull_policy: always
    networks:
      - internal
      - proxy                    # ← mandatory for Traefik to reach it
    labels:
      traefik.http.services.myapp.loadbalancer.server.port: "3000"  # ← mandatory port label

networks:
  internal:
    driver: bridge
  proxy:
    external: true               # ← always external, pre-created by Coolify

Rule 2 — Internal-only services do NOT need proxy

services:
  mydb:
    image: postgres:16
    networks:
      - internal                 # ← only internal, no proxy

networks:
  internal:
    driver: bridge

Rule 3 — Mail-relay access via mail_internal network

Services that need to send mail via the internal mail-relay must be on mail_internal:

services:
  myapp:
    networks:
      - internal
      - proxy
      - mail_internal           # ← only services that need mail
    environment:
      SMTP_HOST: mail-relay     # ← container name as hostname
      SMTP_PORT: 587

networks:
  mail_internal:
    external: true              # ← pre-created: docker network create mail_internal

Rule 4 — Labels: only port + optional middleware

Coolify manages routing labels automatically. Only set:

labels:
  # MANDATORY: tell Traefik which port your app listens on
  traefik.http.services.myapp.loadbalancer.server.port: "3000"

  # OPTIONAL: define reusable middleware (e.g. security headers, redirects)
  traefik.http.middlewares.myapp-headers.headers.stsSeconds: "31536000"
  traefik.http.middlewares.myapp-headers.headers.stsIncludeSubdomains: "true"

NEVER add these (Coolify adds them automatically based on UI config):

• traefik.enable
• traefik.docker.network
• traefik.http.routers.*

Rule 5 — pull_policy: always on main service

Ensures the latest image is pulled on every deploy:

services:
  myapp:
    image: myimage:latest
    pull_policy: always         # ← add to main/frontend service only

Rule 6 — Authentik middleware

To protect a service with Authentik SSO, use the middleware defined in the authentik stack:

In Coolify UI: add this label to your application under "Labels":

traefik.http.routers.<your-router-name>.middlewares=ths-authentik@docker

Or in your compose labels (will be merged with Coolify's auto-labels):

labels:
  traefik.http.services.myapp.loadbalancer.server.port: "3000"
  # The router name Coolify generates follows: https-0-<uuid>-<servicename>
  # Use Coolify UI "Labels" field to add the middleware after first deploy

Full Example — Minimal web app with DB and mail

services:
  myapp:
    image: myimage:latest
    pull_policy: always
    restart: unless-stopped
    depends_on:
      - myapp-db
    environment:
      DB_HOST: myapp-db
      DB_PORT: 5432
      SMTP_HOST: mail-relay
      SMTP_PORT: 587
    networks:
      - internal
      - proxy
      - mail_internal
    labels:
      traefik.http.services.myapp.loadbalancer.server.port: "3000"

  myapp-db:
    image: postgres:16
    restart: unless-stopped
    environment:
      POSTGRES_DB: myapp
      POSTGRES_USER: myapp
      POSTGRES_PASSWORD: ${DB_PASSWORD}
    volumes:
      - /opt/myapp/db:/var/lib/postgresql/data:Z
    networks:
      - internal

networks:
  internal:
    driver: bridge
  proxy:
    external: true
  mail_internal:
    external: true

Pre-created networks on the host

These networks must exist before deploying stacks that use them:

# Already created by Coolify:
# docker network create proxy  ← created as part of Coolify install

# Create manually once:
docker network create mail_internal

Coolify UI checklist per application

1. Ports Exposes: set to the app's HTTP port (must match loadbalancer.server.port label)
2. Domain: set FQDN (e.g. myapp.sherlockhomeless.net)
3. Base Directory: set to the subdirectory (e.g. /gitea, /n8n)
4. Environment Variables: fill from stack.env template