Quickstart

For Caddy installations outside Docker, see local-mode instances.

Prerequisites

• Docker and Docker Compose
• An existing Caddy container with the admin API enabled on 0.0.0.0:2019

1. Enable Caddy’s admin API

Add the following to your Caddyfile global block:

{
    admin 0.0.0.0:2019
    email {$EMAIL}
}

Note: the CADDY_ADMIN environment variable does not configure this — it must be set in the Caddyfile.

2. Create required directories

mkdir -p /docker/caddy/logs
mkdir -p /docker/caddy-ui

3. Plan administrator setup

No authentication environment variables are needed for a new installation. Open the UI after deployment, create the administrator and save the one-time recovery key. Until setup finishes, management endpoints remain locked. The first visitor can establish credentials, so keep an uninitialized installation reachable only by its intended administrator.

Keep /etc/caddy-ui mounted persistently: it contains the credential hashes alongside the existing settings and metadata.

4. Update your compose file

services:
  caddy:
    image: caddy:latest
    container_name: caddy
    restart: unless-stopped
    ports:
      - 80:80
      - 443:443
    environment:
      - CADDY_LOG_PATH=/var/log/caddy/access.log
      - DOMAIN=example.com
      - EMAIL=you@example.com
      - TZ=America/New_York
    volumes:
      - /docker/caddy/Caddyfile:/etc/caddy/Caddyfile
      - /docker/caddy/data:/data
      - /docker/caddy/config:/config
      - /docker/caddy/logs:/var/log/caddy
    networks:
      - caddy-ui

  caddy-ui-backend:
    image: zackwag/caddy-ui-backend:latest
    container_name: caddy-ui-backend
    restart: unless-stopped
    ports:
      - 9876:3001
    environment:
      - TZ=America/New_York
      # Optional -- opt into installed preview UI languages (reviewed languages are enabled by default)
      - CADDY_UI_ADDITIONAL_LANGUAGES=es-es
      # Browser-facing URL: replace your-server with the host you open in your browser.
      # Required for browser writes over plain HTTP; behind HTTPS use the external HTTPS URL.
      - CADDY_UI_EXTERNAL_URL=http://your-server:9877
      # Authentication is required; create credentials in the UI.
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - /docker/caddy-ui:/etc/caddy-ui
    networks:
      - caddy-ui
    depends_on:
      - caddy

  caddy-ui-frontend:
    image: zackwag/caddy-ui-frontend:latest
    container_name: caddy-ui-frontend
    restart: unless-stopped
    ports:
      - 9877:80
    networks:
      - caddy-ui
    depends_on:
      - caddy-ui-backend

networks:
  caddy-ui:
    driver: bridge

The backend needs only the Docker socket for discovery and file operations in Caddy containers, plus its persistent config directory for credentials, instances, history and settings. It does not need Caddy’s volumes mounted directly.

5. Deploy

docker compose up -d

Open http://your-server:9877 in your browser.

Continue with configuration or instance discovery.