Ekklesia/deploy/Caddyfile.split.example

# Ekklesia reference proxy configuration for the split topology (ADR 0045): the Dashboard and the API
# on separate hostnames of one site, for example dash.example.org and api.example.org. For the
# default same-origin topology use Caddyfile.example instead. Copy this file to deploy/Caddyfile.
#
# Hostnames, the ACME contact, and the tunnel connector's address come from the proxy service's
# environment (deploy/.env): EKKLESIA_DASHBOARD_HOSTNAME is the Dashboard's, EKKLESIA_HOSTNAME the
# API's (which also serves the display host), EKKLESIA_STORAGE_HOSTNAME the storage origin's. Only
# the two site blocks below differ from Caddyfile.example.
{
	# ACME account contact. Certificates use the HTTP-01 challenge on port 80 by default, which needs
	# all three hostnames to resolve publicly to this host with 80 and 443 reachable.
	email {$EKKLESIA_ACME_EMAIL}

	# DNS-01, for an installation that keeps Ekklesia off the public Internet, serves only a LAN
	# (split-horizon DNS), or is reachable only through Cloudflare Tunnel. Cloudflare terminates TLS at
	# its edge, so HTTP-01 cannot reach this proxy through a tunnel.
	#
	# DNS-01 needs a DNS provider module that the stock Caddy image does not contain. Build an image
	# with it (for example `xcaddy build --with github.com/caddy-dns/cloudflare`), pin that image by
	# digest in your own overlay, give it CLOUDFLARE_API_TOKEN through a root-owned env file, then
	# enable:
	#
	# acme_dns cloudflare {env.CLOUDFLARE_API_TOKEN}

	servers {
		# A client-address header is honored only from the tunnel connector's fixed address
		# (compose.tunnel.yaml). From every other peer, the client address is the TCP peer itself and
		# any such header is ignored. Without a tunnel, nothing has this address.
		trusted_proxies static {$EKKLESIA_TUNNEL_ADDRESS}/32
		client_ip_headers CF-Connecting-IP
		trusted_proxies_strict
	}

	# Access logs are off unless enabled. If you enable them, keep request headers out: they carry
	# cookies and forwarding chains (docs/development/security.md, launch checklist item 7).
}

# What every request to the API carries upstream: exactly one forwarding header, overwritten with
# the client address Caddy resolved, and none of the headers a caller could use to choose its own.
(ekklesia_forwarding) {
	header_up X-Forwarded-For {client_ip}
	header_up -CF-Connecting-IP
	header_up -X-Real-IP
	header_up -Forwarded
	header_up -True-Client-IP
}

# The Dashboard: its page and its one script, nothing else. Emailed verification and reset links land
# on `/` with a query. `/api/*` is refused here on purpose, so the session cookie has exactly one
# home, the API hostname, and the Dashboard can never fall back to a same-origin API.
{$EKKLESIA_DASHBOARD_HOSTNAME} {
	@dashboard path / /assets/ekklesia-dashboard/*

	handle @dashboard {
		reverse_proxy api:3000 {
			import ekklesia_forwarding
		}
	}

	handle {
		respond 404
	}
}

# The API, and the display host on the API's own origin: a screen's pages, service worker, device
# cookies, and requests are all same-origin (ADR 0045). Nothing is served at `/`.
{$EKKLESIA_HOSTNAME} {
	@api path /api/* /display/* /assets/ekklesia-display/*

	# Module realtime is Server-Sent Events: flush every event immediately.
	@realtime path /api/v1/module-realtime/*

	handle @realtime {
		reverse_proxy api:3000 {
			import ekklesia_forwarding
			flush_interval -1
		}
	}

	handle @api {
		# Request bodies stream through unbuffered and unlimited here; the API enforces the platform's
		# ceilings itself (8 KiB for authentication, up to 32 MiB for a streamed module route).
		reverse_proxy api:3000 {
			import ekklesia_forwarding
		}
	}

	handle {
		respond 404
	}
}

# Browsers fetch signed object URLs here (S3_DELIVERY_ENDPOINT, ADR 0031).
{$EKKLESIA_STORAGE_HOSTNAME} {
	reverse_proxy https://object-storage:8443 {
		# An S3 signature covers the Host header: pass the original through unchanged, or every signed
		# URL fails verification.
		header_up Host {host}
		header_up -CF-Connecting-IP
		header_up -X-Real-IP
		header_up -Forwarded
		header_up -True-Client-IP
		transport http {
			# object-storage presents a certificate from the installation-private CA.
			tls_trust_pool file /etc/caddy/ekklesia-ca.crt
			tls_server_name object-storage
		}
	}
}