wild-cloud/wild-pc
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add gateway.tls=acme: Let's Encrypt wildcard cert via DNS-01

Browse Source 
internal-CA HTTPS forces every device to trust a private root, which breaks down
on some clients (Android browsers). acme mode instead obtains a real Let's Encrypt
wildcard cert (*.<domain>) via a DNS-01 challenge, so browsers trust it with zero
CA install — while services stay internal-only (no inbound exposure, no public A
records; only a transient _acme-challenge TXT touches the public zone, and LAN DNS
resolves the names to a private IP).

- Config: GatewayConfig/NodeConfig gain domain, acme_email, acme_dns_provider
  (plumbed through load/save + registry + deploy, omitted-when-empty for
  round-trip stability). tls stays the discriminator: off | internal | acme.
- Caddyfile generator: acme branch emits a global {email, acme_dns <provider>
  {env.TOKEN}} block + one *.<domain> wildcard site with host matchers derived
  from the service name (<name>.<domain>); path/static stay on :<port>. Shared
  _host_matcher_block helper (reused by off-mode). CASTLE_ACME_STAGING=1 toggles
  the LE staging CA; acme-without-domain falls back to HTTP with a warning.
- deploy(): _acme_preflight warns (never writes) when domain, the gateway-service
  token env, or the CLOUDFLARE_API_TOKEN secret is missing.
- install.sh: opt-in --with-dns-plugin[=provider] builds a DNS-plugin Caddy via
  xcaddy (pinned) to /usr/local/bin/caddy, which the gateway picks up on deploy.
- Tests: TestCaddyfileTlsAcme (global block, wildcard site, derived host matcher,
  path routes on :port, staging toggle, no-domain fallback). Docs: gateway.tls
  modes table + full acme/DNS-01 section (setup, wild-central LAN DNS, staging).
This commit is contained in:
Paul Payne
2026-06-30 18:45:13 -07:00
parent b726e79c23
commit 121f970f14
7 changed files with 329 additions and 17 deletions
Download Patch File Download Diff File Expand all files Collapse all files

17
core/src/castle_core/config.py
View File

@@ -110,7 +110,14 @@ class GatewayConfig:
port: int = 9000
# None/"off" → HTTP-only gateway. "internal" → Caddy serves host routes over
# HTTPS with its local CA (browsers get a secure context; trust the root CA).
# "acme" → real Let's Encrypt wildcard cert (*.domain) via a DNS-01 challenge;
# publicly trusted, no CA to install.
tls: str | None = None
# acme mode only: the zone for the wildcard cert and host-route subdomains
# (e.g. "civil.payne.io" → host routes become <service>.civil.payne.io).
domain: str | None = None
acme_email: str | None = None
acme_dns_provider: str = "cloudflare"
@dataclass
@@ -253,6 +260,9 @@ def load_config(root: Path | None = None) -> CastleConfig:
gateway = GatewayConfig(
port=gateway_data.get("port", 9000),
tls=gateway_data.get("tls"),
domain=gateway_data.get("domain"),
acme_email=gateway_data.get("acme_email"),
acme_dns_provider=gateway_data.get("acme_dns_provider", "cloudflare"),
)
# repo: field points to the git repo for repo-relative sources
@@ -397,6 +407,13 @@ def save_config(config: CastleConfig) -> None:
gateway_data: dict = {"port": config.gateway.port}
if config.gateway.tls:
gateway_data["tls"] = config.gateway.tls
if config.gateway.domain:
gateway_data["domain"] = config.gateway.domain
if config.gateway.acme_email:
gateway_data["acme_email"] = config.gateway.acme_email
# Only persist the provider when non-default, to keep castle.yaml minimal.
if config.gateway.acme_dns_provider and config.gateway.acme_dns_provider != "cloudflare":
gateway_data["acme_dns_provider"] = config.gateway.acme_dns_provider
data: dict = {"gateway": gateway_data}
if config.repo:
data["repo"] = str(config.repo)

39
core/src/castle_core/deploy.py
View File

@@ -16,6 +16,7 @@ from pathlib import Path
from castle_core.config import (
DATA_DIR,
SECRETS_DIR,
SPECS_DIR,
CastleConfig,
ensure_dirs,
@@ -23,6 +24,7 @@ from castle_core.config import (
resolve_env_split,
)
from castle_core.generators.caddyfile import (
_DNS_TOKEN_ENV,
generate_caddyfile_from_registry,
service_proxy_targets,
)
@@ -77,6 +79,9 @@ def deploy(target_name: str | None = None, root: Path | None = None) -> DeployRe
castle_root=str(config.root),
gateway_port=config.gateway.port,
gateway_tls=config.gateway.tls,
gateway_domain=config.gateway.domain,
acme_email=config.gateway.acme_email,
acme_dns_provider=config.gateway.acme_dns_provider,
)
# Load existing registry to preserve entries not being redeployed,
@@ -129,6 +134,11 @@ def deploy(target_name: str | None = None, root: Path | None = None) -> DeployRe
caddyfile_path.write_text(caddyfile_content)
result.messages.append(f"Caddyfile written: {caddyfile_path}")
# acme mode needs a domain + a DNS-provider token; warn (don't fail) if the
# prerequisites the operator must set up by hand are missing.
if (config.gateway.tls or "").lower() == "acme":
_acme_preflight(config, result.messages)
# Reload systemd daemon
subprocess.run(["systemctl", "--user", "daemon-reload"], check=False)
@@ -145,6 +155,35 @@ def deploy(target_name: str | None = None, root: Path | None = None) -> DeployRe
_GATEWAY_NAME = "castle-gateway"
def _acme_preflight(config: CastleConfig, messages: list[str]) -> None:
"""Warn (never fail, never write) if acme-mode prerequisites are missing.
acme mode needs a `gateway.domain`, the DNS-provider token mapped into the
castle-gateway service env, and the matching secret on disk — all operator
steps (castle never rewrites the user-authored gateway service YAML)."""
gw = config.gateway
if not gw.domain:
messages.append(
"Warning: gateway.tls=acme but gateway.domain is unset — host routes "
"won't get a wildcard cert (serving plain HTTP on the gateway port)."
)
return
token_env = _DNS_TOKEN_ENV.get(gw.acme_dns_provider or "cloudflare", "CLOUDFLARE_API_TOKEN")
svc = config.services.get(_GATEWAY_NAME)
env = dict(svc.defaults.env) if (svc and svc.defaults and svc.defaults.env) else {}
if token_env not in env:
messages.append(
f"Warning: acme mode needs {token_env} in the {_GATEWAY_NAME} service env. "
f"Add to services/{_GATEWAY_NAME}.yaml → defaults.env: "
f"{token_env}: ${{secret:{token_env}}}"
)
if not (SECRETS_DIR / token_env).exists():
messages.append(
f"Warning: secret '{token_env}' not found in {SECRETS_DIR} — place the "
f"DNS-provider API token there (Cloudflare token scope: Zone:DNS:Edit)."
)
def _reload_gateway(messages: list[str]) -> None:
"""Reload Caddy if the gateway is running, so new routes take effect."""
gw_unit = unit_name(_GATEWAY_NAME)

77
core/src/castle_core/generators/caddyfile.py
View File

@@ -14,6 +14,7 @@ a **target**, of one **kind**:
from __future__ import annotations
import os
from dataclasses import dataclass
from pathlib import Path
@@ -21,6 +22,14 @@ from castle_core.config import SPECS_DIR, CastleConfig
from castle_core.manifest import ServiceSpec
from castle_core.registry import NodeRegistry
# DNS-01 provider → the env var the Caddyfile reads its API token from. The token
# reaches Caddy via the gateway service's defaults.env (a mode-0600 EnvironmentFile).
_DNS_TOKEN_ENV = {"cloudflare": "CLOUDFLARE_API_TOKEN"}
# Let's Encrypt staging directory — opt in via CASTLE_ACME_STAGING=1 to avoid the
# production rate limits while testing, then cut over to prod (unset the env var).
_ACME_STAGING_CA = "https://acme-staging-v02.api.letsencrypt.org/directory"
@dataclass
class GatewayRoute:
@@ -156,13 +165,28 @@ def compute_routes(
return routes
def _host_matcher_block(label: str, host: str, target: str) -> list[str]:
"""A `@host_X host <host> / handle @host_X { reverse_proxy <target> }` block.
Shared by the off-mode `:<port>` site and the acme wildcard site so the two
can't drift. `label` names the matcher (service name, or the address)."""
matcher = f"@host_{label.replace('-', '_').replace('.', '_')}"
return [
f" {matcher} host {host}",
f" handle {matcher} {{",
f" reverse_proxy {target}",
" }",
"",
]
def generate_caddyfile_from_registry(
registry: NodeRegistry,
remote_registries: dict[str, NodeRegistry] | None = None,
) -> str:
"""Render the route list to a Caddyfile.
Two modes, set by `gateway.tls`:
Three modes, set by `gateway.tls`:
- **off (default)** — HTTP-only. Everything (host matchers + path prefixes +
static) lives in one `:<port>` site with `auto_https off`, so a named host
@@ -172,15 +196,44 @@ def generate_caddyfile_from_registry(
redirects :80). This makes those hosts a browser "secure context". Path
prefixes, static frontends, and the dashboard stay on the HTTP `:<port>`
site — give a service a `proxy.caddy.host` to put it on HTTPS.
- **acme** — host routes are served under a single `*.<domain>` site with a
real Let's Encrypt **wildcard** cert obtained via a DNS-01 challenge (one
cert for all of them). Publicly trusted → no CA install on clients. Each
host route maps to `<service-name>.<domain>`. Requires `gateway.domain`;
the DNS provider token reaches Caddy via `{env.<TOKEN>}`.
"""
routes = compute_routes(registry, None, remote_registries)
gw_port = registry.node.gateway_port
tls_internal = (registry.node.gateway_tls or "").lower() == "internal"
node = registry.node
gw_port = node.gateway_port
mode = (node.gateway_tls or "").lower()
tls_internal = mode == "internal"
domain = node.gateway_domain
tls_acme = mode == "acme" and bool(domain) # acme without a domain → off-mode
host_routes = [r for r in routes if r.is_host]
lines: list[str] = []
if tls_internal:
if tls_acme:
# Global ACME options: LE account email + DNS-01 provider token (from env).
provider = node.acme_dns_provider or "cloudflare"
token_env = _DNS_TOKEN_ENV.get(provider, "CLOUDFLARE_API_TOKEN")
lines.append("{")
if node.acme_email:
lines.append(f" email {node.acme_email}")
lines.append(f" acme_dns {provider} {{env.{token_env}}}")
if os.environ.get("CASTLE_ACME_STAGING") == "1":
lines.append(f" acme_ca {_ACME_STAGING_CA}")
lines += ["}", ""]
# One wildcard site → a single DNS-01 cert covers every host route, so a
# new host-routed service needs no new cert or challenge.
if host_routes:
lines.append(f"*.{domain} {{")
for r in host_routes:
sub = r.name or r.address.split(".")[0]
lines += _host_matcher_block(r.name or r.address, f"{sub}.{domain}", r.target)
lines.append("}")
lines.append("")
elif tls_internal:
# Per-host HTTPS sites via Caddy's internal CA. `tls internal` overrides
# ACME for that host, so no public cert is attempted; clients must trust
# the Caddy root CA (`caddy trust`, then distribute root.crt).
@@ -195,6 +248,9 @@ def generate_caddyfile_from_registry(
else:
# HTTP-only: keep auto-HTTPS off so the bare-port site stays plain HTTP
# and named hosts don't trigger cert provisioning.
if mode == "acme" and not domain:
lines.append("# gateway.tls=acme but gateway.domain is unset — host routes")
lines.append("# fall back to plain-HTTP matchers on the gateway port.")
lines += ["{", " auto_https off", "}", ""]
lines.append(f":{gw_port} {{")
@@ -224,16 +280,9 @@ def generate_caddyfile_from_registry(
"",
]
elif r.is_host: # host-based proxy
if tls_internal:
continue # emitted as its own HTTPS site block above
matcher = f"@host_{(r.name or r.address).replace('-', '_').replace('.', '_')}"
lines += [
f" {matcher} host {r.address}",
f" handle {matcher} {{",
f" reverse_proxy {r.target}",
" }",
"",
]
if tls_internal or tls_acme:
continue # emitted as its own HTTPS / wildcard site above
lines += _host_matcher_block(r.name or r.address, r.address, r.target)
else: # path-prefix proxy (local or remote)
if r.kind == "remote":
lines.append(f" # {r.name} on {r.node}")

16
core/src/castle_core/registry.py
View File

@@ -21,7 +21,12 @@ class NodeConfig:
hostname: str = ""
castle_root: str | None = None # repo path, for dev commands
gateway_port: int = 9000
gateway_tls: str | None = None # None/"off" → HTTP-only; "internal" → Caddy local-CA HTTPS
# None/"off" → HTTP-only; "internal" → Caddy local-CA HTTPS; "acme" → Let's
# Encrypt wildcard (*.gateway_domain) via DNS-01.
gateway_tls: str | None = None
gateway_domain: str | None = None # acme: zone for wildcard cert + host subdomains
acme_email: str | None = None
acme_dns_provider: str = "cloudflare"
def __post_init__(self) -> None:
if not self.hostname:
@@ -85,6 +90,9 @@ def load_registry(path: Path | None = None) -> NodeRegistry:
castle_root=node_data.get("castle_root"),
gateway_port=node_data.get("gateway_port", 9000),
gateway_tls=node_data.get("gateway_tls"),
gateway_domain=node_data.get("gateway_domain"),
acme_email=node_data.get("acme_email"),
acme_dns_provider=node_data.get("acme_dns_provider", "cloudflare"),
)
deployed: dict[str, Deployment] = {}
@@ -143,6 +151,12 @@ def save_registry(registry: NodeRegistry, path: Path | None = None) -> None:
if registry.node.gateway_tls:
data["node"]["gateway_tls"] = registry.node.gateway_tls
if registry.node.gateway_domain:
data["node"]["gateway_domain"] = registry.node.gateway_domain
if registry.node.acme_email:
data["node"]["acme_email"] = registry.node.acme_email
if registry.node.acme_dns_provider and registry.node.acme_dns_provider != "cloudflare":
data["node"]["acme_dns_provider"] = registry.node.acme_dns_provider
for name, comp in registry.deployed.items():
entry: dict = {