add README

This commit is contained in:
Daniel committed 2026-04-06 22:06:24 +02:00
1 parent 359a382795
commit 88a40c0d87
1 file changed
+106
+106
View File
@@ -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://<host>: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`.