diff --git a/README.md b/README.md index 9e2b8c9..80a422a 100644 --- a/README.md +++ b/README.md @@ -1,85 +1,48 @@ # KonCad -Web UI for managing a dockerized [Caddy](https://caddyserver.com/) instance. Parses the Caddyfile into structured sections — global options and per-site blocks — so you don't have to edit raw config files. +Web UI for managing an existing dockerized [Caddy](https://caddyserver.com/) 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 check** — blocks editing if Caddy's admin API is unreachable on load - **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 +- **Atomic deploy** — posts config to Caddy's `/load` endpoint; bad configs are rejected without disrupting the running instance ## 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 +- An existing Caddy container with the admin API enabled (`admin :2019` in global options) +- Both containers on the same Docker network ## Setup -### 1. Prepare the directory +### 1. Clone and configure ```bash -mkdir -p /opt/KonCad/caddy -cp /opt/KonCad/caddy/Caddyfile.example /opt/KonCad/caddy/Caddyfile -cp /opt/KonCad/.env.example /opt/KonCad/.env +git clone https://git.d4nn13.de/d4nn13/KonCad /opt/KonCad ``` -### 2. Configure environment +Edit `docker-compose.yml` to match your environment: -Edit `.env`: +| Setting | Description | +|---|---| +| `CADDY_ADMIN_URL` | URL of Caddy's admin API — use the container name as hostname | +| `CADDYFILE_IMPORT` | Path to your existing Caddyfile (read-only, used once on first boot) | +| `- /opt/caddy:/caddy:ro` | Adjust to wherever your Caddy config directory lives | +| `caddy-network` | Replace with your existing Caddy Docker network name | -```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 +### 2. Start ```bash cd /opt/KonCad -docker compose up -d +docker compose up -d --build ``` KonCad is available at `http://:8080`. -## Docker Compose layout - -```yaml -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. +On first load it imports your existing Caddyfile (read-only). After the first deploy, KonCad manages its own copy. ## Usage @@ -89,18 +52,6 @@ Both services mount `./caddy` so KonCad can read and write the same Caddyfile th | **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 | +| **Deploy** | Validates and applies config via Caddy's `/load` API; 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 - -```bash -# 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`.