Caddy-proxy voor eigen domeinen
Eigen domeinen van kerken (mychurch.org → de B1-website van de kerk) komen binnen op één Windows EC2-server die Caddy draait. Die server beheert de TLS-certificaten, zet elk domein om naar de {sub}.b1.church-site en stuurt het verzoek door met een aangepaste Host-header. De volledige configuratie bestaat uit twee bestanden: een statische Caddyfile en een hosts.map die wordt ververst vanuit de Membership API. Daardoor overleeft de server een herstart zonder enige runtime-status. Deze pagina beschrijft hoe de server vanaf nul wordt opgebouwd, hoe hij werkt, en welke in de praktijk getoetste valkuilen iedereen moet kennen die hem opnieuw opbouwt.
Hoe een verzoek, zodra het bij B1App aankomt, wordt omgezet naar een kerk en site, staat beschreven in Websiteroutering & meerdere sites.
Onderdelen
| Onderdeel | Wat het is |
|---|---|
| EC2-instantie | Windows Server; Elastic IP 3.23.251.61 (wereldwijd opgenomen in de DNS van kerken; het IP is permanent, instanties zijn vervangbaar) |
C:\caddy\caddy.exe | Aangepaste Caddy-build met de techknowlogick/certmagic-s3-opslagmodule; de standaard Caddy kan de certificaatopslag niet lezen |
C:\caddy\Caddyfile | De volledige proxyconfiguratie: on-demand TLS, map van host naar upstream, redirects van www naar apex, en :80 naar https |
C:\caddy\hosts.map | Eén regel {domain} {sub}.b1.church per routeerbaar domein, geïmporteerd in het map-blok van de Caddyfile |
sync-hostmap.ps1 + taak CaddyHostmapSync | Geplande taak (elke 5 minuten en bij het opstarten, als SYSTEM) die hosts.map vanuit de API ververst en Caddy alleen bij een wijziging soepel herlaadt |
Windows-service caddy (WinSW-wrapper) | Draait caddy.exe run --config C:\caddy\Caddyfile --adapter caddyfile; herstart automatisch bij een fout. Caddy is niet SCM-bewust, dus een wrapper is nodig |
S3-bucket churchapps-caddy-certs | Gedeelde certificaatopslag (region us-east-2, prefix certs); certificaten blijven behouden bij het opnieuw opbouwen van instanties |
IAM-rol CaddyRole | Geeft de instantie toegang tot S3; Caddy gebruikt de standaard AWS-credentialketen (geen sleutels in de configuratie) |
De twee API-eindpunten waarvan de server afhankelijk is
Beide zitten in de Membership API. authorize is anoniem; hostmap vereist sinds Api PR #67 (2026-08-16) de header x-internal-key: <INTERNAL_API_KEY>. sync-hostmap.ps1 leest deze sleutel uit C:\caddy\internal-key.txt:
| Eindpunt | Rol |
|---|---|
GET /membership/domains/authorize?domain={host} | De on-demand TLS ask-poort van Caddy: 200 {"authorized":true} wanneer de host (of, bij een www.-host, de apex) een rij in domains is; anders 404. Dit is de misbruikbeveiliging: Caddy geeft geen certificaat uit voor een host die dit eindpunt afwijst |
GET /membership/domains/hostmap | Vereist x-internal-key (of een server-admin-JWT). text/plain, gesorteerde en ontdubbelde regels {domain} {sub}.b1.church (sitebewust: een domein dat aan een secundaire site is toegewezen, verwijst naar het subdomein van die site). Bron van de map |
Verloop van een verzoek
- De browser zet
mychurch.orgom naar3.23.251.61(apex-A-record, ofCNAME proxy.b1.church). - Caddy beëindigt de TLS-verbinding. Certificaat aanwezig in S3 → gebruiken; onbekende SNI →
authorizewordt gevraagd; 200 → on demand uitgeven via Let's Encrypt; 404 → de handshake wordt geweigerd (geen certificaat, geen antwoord; een onbekende host krijgt een TLS-weigering, geen HTTP-fout). - De
mapzet de Host om naar{sub}.b1.church;www.{apex}krijgt een 302 naar de apex; een geautoriseerde maar niet-gemapte host (een gloednieuw domein binnen het synchronisatievenster van maximaal 5 minuten) krijgt een schone 404. reverse_proxyverbindt met{sub}.b1.church:443met SNI en een Host die is herschreven naar de upstream, zodat de Vercel-edge de B1App-site serveert. Caddy stuurt het oorspronkelijke domein van de bezoeker ook mee alsX-Church-Host(Vercel overschrijftX-Forwarded-Hostmet de herschreven Host). De B1App-middleware accepteert deze alleen wanneer/domains/public/lookup/{host}deze op hetzelfde{sub}afbeeldt als de aanvraag-host. Daarna stelt de middleware hem beschikbaar alsx-public-hostvoor de canoniekeLink-header,robots.txtensitemap.xml. Door de client meegestuurdex-public-hostwordt altijd verwijderd. Schema.orgChurchJsonLdgebruikt nog steeds deb1.church-URL (headers daar lezen zou de pagina's dynamisch maken).- Poort 80 verwerkt ACME HTTP-01-uitdagingen en stuurt al het overige met een 308 door naar https.
Propagatie van nieuwe domeinen: een domein dat in B1Admin is opgeslagen, wordt binnen ongeveer 5 minuten routeerbaar (de synchronisatietaak); het certificaat wordt uitgegeven bij de eerste HTTPS-aanvraag.
De server vanaf nul opbouwen
Samengevat uit de in de praktijk getoetste procedure (de volledige stap-voor-stap-handleiding met kopieer-en-plakcommando's staat in de ops-werkruimte, niet in deze repository). Eerst de voorvereisten; zonder die lukt de opbouw niet:
- IAM: koppel
CaddyRole(S3-toegang tot de certificaatbucket) aan de instantie. Controleer via IMDSv2 vanaf de server. Let op: een kale IMDS-GET die 401 teruggeeft, betekent alleen dat IMDSv2 is afgedwongen, niet dat er geen rol is. - API-status:
authorizemoet 404 teruggeven voor een verzonnen domein, enhostmap(met de headerx-internal-key) moet 200 teruggeven, vóór alles andere.
Daarna:
- Binary: download een aangepaste build van de build-service van Caddy:
https://caddyserver.com/api/download?os=windows&arch=amd64&p=github.com/techknowlogick/certmagic-s3(~57 MB tegenover ~45 MB voor de standaardversie; v2.11.4 op het moment van schrijven). De keuze van de module is belangrijk:techknowlogick/certmagic-s3gebruikt de sleutelsbucket/region/prefix, die overeenkomen met de bestaande certificaatstructuur; dess098-fork gebruikthost/endpointen vindt de bestaande certificaten niet. - Bestanden: plaats
Caddyfile+sync-hostmap.ps1+internal-key.txt(productie-INTERNAL_API_KEY, één regel) inC:\caddy\; vul de map eenmalig metsync-hostmap.ps1 -NoReload. - Controles vóór de eerste start:
caddy list-modulesmoet de s3-opslagmodule tonen;caddy adaptmoet in het opslagblok"module":"s3","bucket":"churchapps-caddy-certs","region":"us-east-2","prefix":"certs"uitvoeren;caddy validatemoet slagen. - Service: installeer via WinSW (service-id
caddy, automatisch herstarten bij een fout, roterende logs). Draait als LocalSystem, dat IMDS bereikt voor de rol-credentials. - Synchronisatietaak: registreer
CaddyHostmapSync(SYSTEM, elke 5 minuten en bij het opstarten, uitvoeringslimiet van 4 minuten). - Verificatie vóór de overschakeling: forceer de omzetting van domeinen naar
127.0.0.1metcurl --resolve(de server heeft geen echt verkeer totdat het EIP is verplaatst). Een bestaand domein moet serveren met een geldig, overgenomen certificaat;www.moet een 302 geven; een onbekende host moet een TLS-weigering krijgen; enRestart-Service caddymoet terugkomen met serveren zonder handmatig opnieuw voorbereiden. Die herstarttest is het hele doel van het statische ontwerp. - Livegang: koppel het Elastic IP
3.23.251.61opnieuw aan de nieuwe instantie. De DNS van kerken verandert nooit.
In de praktijk getoetste valkuilen (op de harde manier geleerd; niet opnieuw introduceren)
| Valkuil | Symptoom | Oplossing |
|---|---|---|
tls_server_name {vars.upstream} in de transport van reverse_proxy | Elk geproxied domein geeft een 502: de map-placeholders worden leeg op het moment van de TLS-verbinding ("either ServerName or InsecureSkipVerify must be specified") | Gebruik de transport-eigen placeholder: tls_server_name {http.reverse_proxy.upstream.host} |
Dubbele sleutels of rommelregels in hosts.map | De map-handler van Caddy geeft een harde fout bij een dubbele invoersleutel; één foute regel kan de hele configuratie uitschakelen | Het synchronisatiescript normaliseert witruimte, laat foutieve regels vallen (weigert alleen als meer dan 20% fout is), ontdubbelt met de eerste waarde als winnaar, en schrijft UTF-8 zonder BOM (een BOM beschadigt de eerste map-sleutel). De API filtert ook lege domeinrijen of rijen met spaties bij de bron |
Register-ScheduledTask -RepetitionDuration ([TimeSpan]::MaxValue) | Het registreren van de taak mislukt stilzwijgend (XML buiten bereik, niet-beëindigende fout) | Bouw de herhaling als een CIM-instantie van MSFT_TaskRepetitionPattern met Interval = "PT5M" en zonder duur; voeg een ExecutionTimeLimit van 4 minuten toe (de eerste SYSTEM-uitvoering kan blijven hangen bij een koude TLS/CRL-opzoeking) |
De admin-API luistert alleen op localhost:2019. De verouderde runtime-modus maakte deze op afstand bereikbaar, zodat de Membership API routeconfiguraties kon pushen. Het statische ontwerp heeft geen externe pushes nodig, en het kleinere oppervlak is bewust gekozen. caddy reload (lokaal uitgevoerd door het synchronisatiescript) is de enige gebruiker van de admin-API.
CaddyHelper in de API (en de eindpunten /membership/domains/caddy + /caddy/init) bestaan nog steeds als terugvalroute naar de oude, runtime-geconfigureerde modus. Ze worden verwijderd zodra de statische server een paar weken stabiel heeft gedraaid. Daarna zijn authorize + hostmap de enige integratiepunten.
Beheer
- Logs: WinSW-logs met rotatie in
C:\caddy\(stdout/stderr van de service; fouten van de reverse-proxy komen incaddy-service.err.logterecht); synchronisatiegeschiedenis inC:\caddy\sync-hostmap.log. - Hostmap geforceerd verversen:
Start-ScheduledTask -TaskName CaddyHostmapSync. - Configuratiewijziging: bewerk
C:\caddy\Caddyfile, voer daarnacaddy validate+caddy reloaduit (ofRestart-Service caddy; herstarts zijn ontworpen om veilig te zijn). - Massale verwijdering van domeinen activeert de krimpbeveiliging van het synchronisatiescript, bewust; verplaats het oude
hosts.mapopzij en voer de taak opnieuw uit om een bewuste grote krimp te accepteren. - DNS-instructies voor kerken blijven voor altijd gelijk: apex
A 3.23.251.61ofCNAME proxy.b1.church.
Gerelateerde pagina's
- Websiteroutering & meerdere sites: hoe het geproxied verzoek in B1App wordt omgezet naar een kerk en site
- API-implementatie: de implementatie van de Membership API die
authorize/hostmaplevert