ENCLAVR DOCS

Update a Caddy mask and directory

The complete Caddyfile is an OpenBao-backed namespace document selected by the host's caddy_mask_proxy.config_ref. The landing page is rendered during the Caddy deployment action from that document and the namespace's declared services and extra links.

Hosts may share that document while the namespace directory remains on its declared authoritative host. On other hosts, or when the directory is disabled, the generated enclavr_web_directory snippet returns HTTP 404. Its import stays valid without serving directory content or changing the other site routes.

  1. Locate the owner host and selected Caddy document in the authoritative assets. Confirm that the Caddy proxy is enabled on that host.
  2. Edit the protected document on the designated namespace-writer host: launch ./enclavr → Config → Edit config, select the Caddy document, press v, then y at the editor plan. Vim opens the whole document in the same terminal. Use /text to search or :12000 to jump to a line; :wq returns to Enclavr and :cq cancels this edit. The CLI alternative is ./enclavr priv edit --namespace <namespace> --component caddy-mask. Preserve certificate storage, challenge forwarding, access policy, TLS settings, and routes.
  3. Add or change the HTTPS site block. Browser-facing site addresses in the Caddyfile are collected into the namespace directory at the next Caddy deployment. www aliases share their primary site's card. Use web_directory.links for interfaces that have no Caddy site block.
  4. Review and publish the complete document. Saving in Vim returns a draft without changing OpenBao. In the TUI component list press r to review, then y to publish. The guarded workflow validates the document, shows a value-free plan, performs a version-bound write, and reads it back. Standalone staged pull/check/push commands have been retired.
  5. Publish the changed Caddyfile. On the writer, launch ./enclavr → Config → Prepare Caddy publication, select the affected Caddy host, review with r, and confirm with y. Then use Config → Publish Caddy publication for the same host, review and confirm. The forms manage the protected snapshot internally. Publication records the Caddyfile's content hash and checks conflicts on that document. Unrelated assets, secrets or users changes require no republication. See Caddy publication troubleshooting.
  6. Deploy on each affected Caddy host: ./enclavr host deploy --only caddy-mask-proxy.deploy --yes. A saved namespace change is not a completed rollout until every serving proxy has accepted it.
  7. Verify Caddy configuration, container health, DNS, TLS, the directory page, and the destination from an appropriate client. The directory status dot means configured; it is not a live reachability test.

Independent certificates behind Global Accelerator

OpenBao is the configuration and secrets authority. Caddy can independently store certificates, keys and its ACME account in each host's persistent volume using storage file_system /data/caddy. Omit storage_connection_ref in this mode. Routine Caddy changes do not need OpenBao recovery credentials.

With Global Accelerator forwarding directly to EC2 Caddy hosts, public DNS continues to point to the accelerator. Use HTTP-01 validation and disable TLS-ALPN challenges on every issuer. Configure each host's caddy_mask_proxy.http_challenge_peer with the other's literal Tailscale IP:port. Additional independent issuers, including a private application proxy, belong in http_challenge_peers. These become CADDY_HTTP_CHALLENGE_PEER and CADDY_HTTP_CHALLENGE_PEERS in the container.

Each HTTP site must serve local active challenges first and forward unmatched /.well-known/acme-challenge/* requests once to each declared peer, preserving Host and path. Copy the repository's configs/caddy-http-challenge.caddy snippet into the protected Caddyfile and import it first inside each HTTP site's route, before redirects or access checks. Include sites formerly using automatic redirects. The repository's enclavr_acme_relay handler checks other issuers until it finds the token; a healthy peer returning 404 may not own that token. The hop marker stops unknown tokens from looping. Client credentials and cookies are not forwarded. Keep application restrictions outside the challenge path and permit public TCP 80 validation through the accelerator. This needs no DNS challenge records or third-party plugin.

Keep the existing local volumes. Verify forwarding both ways, simultaneous tokens for the same hostname, unknown-token 404s, peer failure and ordinary access denials. Verify TLS/upstreams on both hosts, repeat deployment to confirm no unnecessary recreation, and monitor each host's certificate expiry. Peer connectivity is required when validation lands on another host.

A private application instance owns an approved service-specific Caddy document, selected by config_ref, with its own instance_name, listen_addresses, and config_profile. Its configuration, persistent certificate storage and lifecycle remain independent of the public proxies. Reuse common code and templates; reference or derive common values instead of duplicating configuration fields. Share a document only when the instances intentionally require the same configuration. HTTP-01 forwarding is the necessary connection to public ingress. Verify the application's certificate and origin before publishing Unbound overrides for clients that should connect directly.

Optional shared OpenBao certificate storage

Only a Caddyfile explicitly selecting storage openbao requires a concealed OpenBao storage connection with caddy_mask_proxy.storage_connection_ref. That connection can access only the namespace's shared Caddy certificate-object and lock paths. Do not reuse the namespace writer or a normal host runtime connection. The repository builds the custom Caddy binary from digest-pinned official Caddy images. In this optional mode OpenBao carries certificates and keys as well as configuration.

When a filesystem-backed proxy is converted for the first time, deploy the current primary first. Its manager streams existing Caddy storage directly into OpenBao and rolls back to the old configuration if import fails. Verify primary TLS before deploying a secondary or enabling its load-balancer traffic.

For the public docs.enclavr.io route, point the protected Caddy site block at docs:8080 on the Caddy mask Compose network. Do not import the private directory access policy for that public block.

See Edit private data safely for the provider and writer boundaries behind this procedure.