diff --git a/README.md b/README.md new file mode 100644 index 0000000..9e2b8c9 --- /dev/null +++ b/README.md @@ -0,0 +1,106 @@ +# 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. + +## 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 + +```bash +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`: + +```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 + +```bash +cd /opt/KonCad +docker compose up -d +``` + +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. + +## 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 + +```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`.