update README to reflect current architecture
This commit is contained in:
1 parent
db86ff63e4
commit
c000cfae4c
1 file changed
+18
-67
@@ -1,85 +1,48 @@
|
|||||||
# KonCad
|
# 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
|
## Features
|
||||||
|
|
||||||
- **Structured editor** — separate panels for global options and each site block
|
- **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
|
- **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
|
- **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
|
- **Atomic deploy** — posts config to Caddy's `/load` endpoint; bad configs are rejected without disrupting the running instance
|
||||||
- **Persistence** — writes the Caddyfile to disk only after Caddy accepts the new config
|
|
||||||
|
|
||||||
## Requirements
|
## Requirements
|
||||||
|
|
||||||
- Docker + Docker Compose
|
- Docker + Docker Compose
|
||||||
- A running Caddy container with the admin API enabled and reachable (see setup below)
|
- An existing Caddy container with the admin API enabled (`admin :2019` in global options)
|
||||||
- Both containers on the same Docker network with a shared Caddyfile volume
|
- Both containers on the same Docker network
|
||||||
|
|
||||||
## Setup
|
## Setup
|
||||||
|
|
||||||
### 1. Prepare the directory
|
### 1. Clone and configure
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
mkdir -p /opt/KonCad/caddy
|
git clone https://git.d4nn13.de/d4nn13/KonCad /opt/KonCad
|
||||||
cp /opt/KonCad/caddy/Caddyfile.example /opt/KonCad/caddy/Caddyfile
|
|
||||||
cp /opt/KonCad/.env.example /opt/KonCad/.env
|
|
||||||
```
|
```
|
||||||
|
|
||||||
### 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
|
### 2. Start
|
||||||
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
|
```bash
|
||||||
cd /opt/KonCad
|
cd /opt/KonCad
|
||||||
docker compose up -d
|
docker compose up -d --build
|
||||||
```
|
```
|
||||||
|
|
||||||
KonCad is available at `http://<host>:8080`.
|
KonCad is available at `http://<host>:8080`.
|
||||||
|
|
||||||
## Docker Compose layout
|
On first load it imports your existing Caddyfile (read-only). After the first deploy, KonCad manages its own copy.
|
||||||
|
|
||||||
```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
|
## 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 |
|
| **Enable Admin API** checkbox | Adds/removes `admin :2019` from global options |
|
||||||
| **+ Add Site** | Creates a new site block |
|
| **+ Add Site** | Creates a new site block |
|
||||||
| **Remove** (per site) | Deletes that 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.
|
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`.
|
|
||||||
Reference in new issue
Block a user