Files
KonCad/README.md
T
2026-04-06 22:06:24 +02:00

3.4 KiB

KonCad

Web UI for managing a dockerized Caddy instance. Parses the Caddyfile into structured sections — global options and per-site blocks — so you don't have to edit raw config files.

Features

  • Structured editor — separate panels for global options and each site block
  • Admin API toggle — one checkbox adds/removes admin :2019 from global options
  • Upstream reachability check — warns before deploy if any reverse_proxy target is unreachable, with option to deploy anyway
  • Atomic deploy — posts config to Caddy's /load endpoint which validates and applies in one step; bad configs are rejected without disrupting the running instance
  • Persistence — writes the Caddyfile to disk only after Caddy accepts the new config

Requirements

  • Docker + Docker Compose
  • A running Caddy container with the admin API enabled and reachable (see setup below)
  • Both containers on the same Docker network with a shared Caddyfile volume

Setup

1. Prepare the directory

mkdir -p /opt/KonCad/caddy
cp /opt/KonCad/caddy/Caddyfile.example /opt/KonCad/caddy/Caddyfile
cp /opt/KonCad/.env.example /opt/KonCad/.env

2. Configure environment

Edit .env:

CADDY_ADMIN_URL=http://caddy:2019
CADDYFILE_PATH=/etc/caddy/Caddyfile
Variable Default Description
CADDY_ADMIN_URL http://localhost:2019 URL of Caddy's admin API (use service name in Compose)
CADDYFILE_PATH /etc/caddy/Caddyfile Path to the Caddyfile inside the KonCad container

3. Initial Caddyfile

KonCad communicates with Caddy via the admin API. The admin API must be bound to a network-accessible address (not just localhost) so KonCad can reach it across containers:

{
    admin :2019
}

Note: By default Caddy binds the admin API to localhost:2019, which is not reachable from other containers. The admin :2019 directive (no host) binds to all interfaces.

4. Start

cd /opt/KonCad
docker compose up -d

KonCad is available at http://<host>:8080.

Docker Compose layout

services:
  caddy:
    image: caddy:latest
    volumes:
      - ./caddy:/etc/caddy   # shared with KonCad

  koncad:
    build: .
    ports:
      - "8080:80"
    volumes:
      - ./caddy:/etc/caddy   # shared with Caddy
    env_file: .env

Both services mount ./caddy so KonCad can read and write the same Caddyfile that Caddy uses.

Usage

Action Description
Global Options panel Edit top-level Caddy options (email, logging, etc.)
Enable Admin API checkbox Adds/removes admin :2019 from global options
+ Add Site Creates a new site block
Remove (per site) Deletes that site block
Deploy Validates config via Caddy's /load API and applies it; shows errors inline if rejected

If any reverse_proxy upstream is unreachable at deploy time, a warning modal lists them — you can cancel or deploy anyway.

Deployment

# From the dev machine:
cd ~/git && ./deploy.sh "your message"

# Or single-project:
./deploy.sh --project KonCad "your message"

Credentials and target host are read from ~/.config/homelab-deploy/config.env.