Remote-Pulse Caddy Snippet Integration¶

Status: Manual (F7-4)
Owner: Ramón Kamibayashi
Context: homelab-ctl.py currently only syncs managed.caddy (dynamic docker routes). The rp.caddy snippet is static infrastructure and must be deployed via Ansible or manually.

⚠️ Estado real (2026-07-12): el snippet rp.caddy no está desplegado en /etc/caddy/snippets/ de .247/.248 (solo hay wp-pulse-*). El routing de rp vive inline en el Caddyfile principal (→ 192.168.0.196:8080); el ls .../rp.caddy de troubleshooting fallará. Ver rp-public-routing.md.

Current Architecture¶

homelab-ctl.py sync flow: 1. Collects docker labels + static.yaml routes 2. Writes managed.caddy to VM 208 3. Calls deploy_to_lxc_caddies() → scp to LXC 270/271 4. Reloads Caddy on all hosts

Limitation: Only handles managed.caddy, not Caddyfile includes or snippets.

Remote-Pulse Snippet Deployment¶

The snippets/rp.caddy file is static infrastructure (doesn't change with docker labels), so it's deployed separately:

Option 1: Ansible (Recommended)¶

cd ~/docs-repo
ansible-playbook -i ansible/inventory.yml ansible/playbook.yml \
  --tags rp-caddy,rp-install-assets \
  --limit caddy_lxc

This: - Copies snippets/rp.caddy to /etc/caddy/snippets/ on LXC 270/271 - Syncs install scripts to /var/lib/caddy/rp-install/ - Does NOT modify Caddyfile (must import snippet manually, see below)

Option 2: Manual scp¶

# From homelab-infra repo root
scp ansible/roles/caddy_lxc/files/snippets/rp.caddy [email protected]:/etc/caddy/snippets/
scp ansible/roles/caddy_lxc/files/snippets/rp.caddy [email protected]:/etc/caddy/snippets/

Caddyfile Import (One-Time Setup)¶

After deploying the snippet, manually add import to main Caddyfile:

ssh [email protected]
vi /etc/caddy/Caddyfile

Add after the global block and before the wildcard site:

{
    # ... existing global config
}

# Import Remote-Pulse bootstrap routes (F7-4)
import snippets/rp.caddy

# Wildcard site
*.monxas.casa {
    # ... existing routes
}

Verify syntax:

caddy validate --config /etc/caddy/Caddyfile

Reload:

systemctl reload caddy

Repeat for LXC 248 (secondary).

Why Not in homelab-ctl.py?¶

The rp.caddy snippet could be integrated into homelab-ctl.py, but:

Scope: homelab-ctl currently handles dynamic routes (docker labels → managed.caddy). Static infra (like rp.caddy, Loki auth, etc.) lives in Ansible.
Frequency: rp.caddy changes rarely (only when API routes evolve), unlike managed.caddy (every docker compose change).
Consistency: Keeping static infra in Ansible aligns with TLS certs, systemd units, etc.

Future enhancement: If more static snippets emerge, consider extending homelab-ctl to sync a snippets/ directory tree alongside managed.caddy.

Validation After Deploy¶

# From laptop/dev machine
~/docs-repo/scripts/validate-rp-routing.sh rp.monxas.casa

Expected output:

✓ Install script accessible
✓ SHA256SUMS accessible
✓ Enrollment endpoint accessible (HTTP 422)
✓ Non-public endpoint correctly denied (HTTP 401)
✓ Health check passed
✓ All endpoints validated

Troubleshooting¶

Import not working¶

Symptom: caddy validate returns "import snippets/rp.caddy: file does not exist"

Fix: Verify file exists:

ls -lh /etc/caddy/snippets/rp.caddy

If missing, deploy via Ansible (Option 1 above).

Routes conflict with existing wildcard¶

Symptom: caddy validate returns "duplicate site address"

Cause: rp.monxas.casa and dash.rp.monxas.casa must be before the *.monxas.casa wildcard block in Caddyfile order. Import must come before wildcard.

Fix: Move import snippets/rp.caddy line above *.monxas.casa {.

Install scripts return 404¶

Symptom: curl https://rp.monxas.casa/install returns 404

Cause: Assets not synced to /var/lib/caddy/rp-install/

Fix:

ansible-playbook -i ansible/inventory.yml ansible/playbook.yml \
  --tags rp-install-assets \
  --limit caddy_lxc -vv

Last updated: 2026-05-25 (F7-4)