From cd63df4f591fc6712fd3f9a5ed6d9fb1aa49d562 Mon Sep 17 00:00:00 2001 From: Michael Wegener Date: Tue, 21 Jul 2026 14:08:07 +0200 Subject: [PATCH] docs(caddy): add agent0.localhost reverse proxy + RFC 6761 wildcard learning - New site: https://agent0.localhost -> reverse_proxy 192.168.0.141:8090 (first non-localhost backend; remote LAN host running uvicorn) - Config in dedicated /etc/caddy/conf.d/agent0.localhost.conf - Regenerated mkcert cert: 19 -> 20 SANs, valid until 2028-10-21 - Key learning: *.localhost wildcard is NOT honored by curl/system trust even for single-label subdomains - .localhost is a special-use TLD per RFC 6761; every subdomain needs an explicit SAN. Corrects prior assumption in stack.md and manual-overrides.md. Updates: docs/tech/stack.md, docs/tech/manual-overrides.md, CHANGELOG.md --- CHANGELOG.md | 1 + docs/tech/manual-overrides.md | 3 ++- docs/tech/stack.md | 15 +++++++++------ 3 files changed, 12 insertions(+), 7 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 24c4f44..ce726fe 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -18,6 +18,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - Identified failed `archlinux-keyring-wkd-sync.service` in system health check. ### Added +- Added `agent0.localhost` (-> `reverse_proxy 192.168.0.141:8090`, `flush_interval -1`) to Caddy in a dedicated file `/etc/caddy/conf.d/agent0.localhost.conf`. First non-localhost backend (remote LAN host running a uvicorn app). Regenerated mkcert cert to add explicit `agent0.localhost` SAN; cert now has 20 SANs, valid until 2028-10-21 (2026-07-21). Key learning: the `*.localhost` wildcard is NOT honored by curl/system trust even for single-label subdomains - `.localhost` is a special-use TLD per RFC 6761, so every subdomain needs an explicit SAN. This corrects the prior assumption in `docs/tech/stack.md` and `docs/tech/manual-overrides.md` that single-label subdomains were wildcard-covered. Total `*.localhost` sites now 18. - Regenerated mkcert cert at `/etc/caddy/localhost{,-key}.pem` to add explicit SANs for `platform.localhost`, `packages.localhost`, and `onlyoffice.docs.localhost` (pre-existing in Caddy config but missing from cert, causing TLS validation failures). Cert now has 19 SANs, valid until 2028-10-12 (2026-07-12). - Added `platform.localhost` (-> `localhost:10080`, amicron-platform Docker) and `packages.localhost` (-> `localhost:20080`, satis Docker) to `/etc/caddy/conf.d/localhost-dev.conf`. Docker port mappings updated: `~/internal/amicron-platform/docker-compose.override.yml` `10080:80`, `~/internal/satis/docker-compose.yml` nginx `20080:80`. Both upstreams plain HTTP on high ports; Caddy terminates TLS. Also documented `onlyoffice.docs.localhost` in `docs/tech/stack.md` (pre-existing in Caddy config, was undocumented). Total `*.localhost` sites now 17. The three form the local E2E test triangle: `platform.localhost` (ERP) -> `packages.localhost` (Satis) -> shared Firebird 3.0.14 database (token validation), mirroring the production `platform.auc.de` + `packages.auc.de` + shared Firebird setup (2026-07-12). - Enabled click-and-drag window movement and resizing under the SUPER modifier, and enabled border dragging to resize tiled windows natively, updating both the Hyprland configuration template and keybindings cheatsheet (2026-07-09). diff --git a/docs/tech/manual-overrides.md b/docs/tech/manual-overrides.md index 76d070e..e1b99f1 100644 --- a/docs/tech/manual-overrides.md +++ b/docs/tech/manual-overrides.md @@ -6,7 +6,7 @@ tags: - manual-overrides - infrastructure - configuration -last_updated: '2026-07-12' +last_updated: '2026-07-21' --- # Manual System Overrides @@ -22,6 +22,7 @@ This document tracks all persistent system changes implemented manually that are | Date | Change | Rationale | Ansible Status | |------|--------|-----------|----------------| +| 2026-07-21 | Added `agent0.localhost` (-> `reverse_proxy 192.168.0.141:8090`, `flush_interval -1`) in dedicated file `/etc/caddy/conf.d/agent0.localhost.conf`. First non-localhost backend (remote LAN host running a uvicorn app). Regenerated mkcert cert to add explicit `agent0.localhost` SAN; cert now has 20 SANs total, valid until 2028-10-21. Old cert/key backed up as `localhost{,-key}.pem.bak.`. Total `*.localhost` sites now 18. | User request to expose the remote agent backend on local HTTPS. Key learning: the `*.localhost` wildcard is NOT honored by curl/system trust even for single-label subdomains - `.localhost` is a special-use TLD (RFC 6761), so every subdomain needs an explicit SAN. This corrects the prior assumption that single-label subdomains were covered by the wildcard. | Same as parent Caddy row - candidate for Ansible role when issue #92 resolves | | 2026-07-12 | Regenerated mkcert cert at `/etc/caddy/localhost{,-key}.pem` to add explicit SANs for `platform.localhost`, `packages.localhost`, and `onlyoffice.docs.localhost` (the latter was pre-existing in Caddy config but missing from the cert, causing TLS validation failures). Cert now has 19 SANs total, valid until 2028-10-12. | `onlyoffice.docs.localhost` is a multi-label subdomain not covered by `*.localhost` wildcard. Required explicit SAN. | Same as parent Caddy row | | 2026-07-12 | Added `platform.localhost` (-> `localhost:10080`) and `packages.localhost` (-> `localhost:20080`) to `/etc/caddy/conf.d/localhost-dev.conf`. Docker port mappings: `~/internal/amicron-platform/docker-compose.override.yml` `10080:80`, `~/internal/satis/docker-compose.yml` nginx `20080:80`. Both upstreams are plain HTTP on high ports; Caddy terminates TLS. Also documented `onlyoffice.docs.localhost` (pre-existing in config, was undocumented). Total sites now 17. | Local HTTPS dev for amicron-platform (ERP), satis (Composer package repository), and shared Firebird 3.0.14 database. The three form the local E2E test triangle: `platform.localhost` (ERP) -> `packages.localhost` (Satis) -> Firebird (token validation). Mirrors the production `platform.auc.de` + `packages.auc.de` + shared Firebird setup. | Same as parent Caddy row - candidate for Ansible role when issue #92 resolves | | 2026-07-06 | Caddy reverse-proxy + mkcert TLS at `/etc/caddy/` (`Caddyfile` + `conf.d/localhost-dev.conf` + `localhost{,-key}.pem`) | Local HTTPS dev for 14 `*.localhost` sites (mcp, artifacts, onlyoffice, demo.satware.com clone, 10 placeholders). Caddy runs as systemd `caddy.service` on port 443. NOT managed by this repo - no `caddy` Ansible role exists. The `onlyoffice.localhost` site (-> `localhost:3847`) is emitting `context canceled` SSE aborts; see `docs/learnings/2026-07-06-caddy-onlyoffice-mcp-sse-investigation.md` and GitLab issue [satware/mcp/onlyoffice#92](https://gitlab.satware.com/satware/mcp/onlyoffice/-/work_items/92). | Candidate for Ansible role (`caddy` + `mkcert`); defer until issue #92 resolves to avoid masking root cause | diff --git a/docs/tech/stack.md b/docs/tech/stack.md index 15e8ea8..7d27bf6 100644 --- a/docs/tech/stack.md +++ b/docs/tech/stack.md @@ -106,10 +106,10 @@ for the active Caddy/OnlyOffice investigation. |------|-------| | Package | `caddy` (pacman) | | Service | `caddy.service` (enabled, runs as `caddy` user) | -| Config | `/etc/caddy/Caddyfile` + `/etc/caddy/conf.d/localhost-dev.conf` | -| TLS cert | mkcert-generated pair at `/etc/caddy/localhost{,-key}.pem`; includes explicit SANs for all 19 hostnames (wildcard `*.localhost` only covers single-label subdomains like `mcp.localhost`; multi-label hosts like `onlyoffice.docs.localhost` and `demo.satware.com.localhost` require explicit SANs) | +| Config | `/etc/caddy/Caddyfile` + `/etc/caddy/conf.d/*.conf` (main site file `localhost-dev.conf`, plus per-service files like `agent0.localhost.conf`) | +| TLS cert | mkcert-generated pair at `/etc/caddy/localhost{,-key}.pem`; includes explicit SANs for all 20 hostnames, valid until 2028-10-21. The `*.localhost` wildcard is NOT honored by curl/system trust even for single-label subdomains like `agent0.localhost` (empirically verified 2026-07-21: `.localhost` is a special-use TLD per RFC 6761); every subdomain MUST be listed explicitly. Multi-label hosts like `onlyoffice.docs.localhost` additionally require explicit SANs because wildcards only cover one level. | | Admin endpoint | Unix socket `/run/caddy/admin.socket` | -| Sites | 17 `*.localhost` virtual hosts (see table below) | +| Sites | 18 `*.localhost` virtual hosts (see table below) | #### `*.localhost` sites @@ -123,10 +123,13 @@ for the active Caddy/OnlyOffice investigation. | `platform.localhost` | `reverse_proxy localhost:10080` | amicron-platform Docker (Symfony 7.4 + Vue 3 + Firebird 3.0.14); `~/internal/amicron-platform` | | `packages.localhost` | `reverse_proxy localhost:20080` | satis Docker (Composer package repository with token-based access control); `~/internal/satis` | | `onlyoffice.docs.localhost` | `file_server` root `/home/mw/internal/onlyoffice/docs-site/dist` | Starlight static docs build | +| `agent0.localhost` | `reverse_proxy 192.168.0.141:8090` | First non-localhost backend (remote host on LAN, uvicorn app). Config in dedicated `/etc/caddy/conf.d/agent0.localhost.conf`. `flush_interval -1` enabled. | -Wildcard `*.localhost` only matches single-label subdomains (e.g. `mcp.localhost`). -Multi-label hosts like `onlyoffice.docs.localhost` and `demo.satware.com.localhost` -require explicit SANs in the mkcert cert - they are NOT covered by the wildcard. +Wildcard `*.localhost` only matches single-label subdomains (e.g. `mcp.localhost`) +AND is not honored by curl/system trust for the `.localhost` special-use TLD +(RFC 6761) - every subdomain needs an explicit SAN. Multi-label hosts like +`onlyoffice.docs.localhost` and `demo.satware.com.localhost` require explicit +SANs for both reasons. ### Useful Caddy commands