Saltar a contenido
Caddy

Proxy inverso · TLS (cifrado de comunicaciones) · HTTPS (protocolo web cifrado) · Certificados

📌 v2.11.2 · 2026-03-06

Caddy — El director de tráfico

Gestionaría todas las conexiones, asegura que viajen cifradas con TLS y renueva los certificados automáticamente. Sin Caddy, escribirías direcciones IP y puertos en lugar de nombres.

🏠 Despliegue real

Caddy corre en el host como servicio systemd (caddy.service) y sirve 4 dominios públicos vía duckdns.org:

Dominios configurados

Dominio Tipo Backend Propósito
tonatiuh.duckdns.org file_server /home/tonatiuh/SmallCountry/web/site Sitio web de SmallCountry (MkDocs estático)
forgejo-sc.duckdns.org reverse_proxy localhost:3000 Forgejo git
opencode-sc.duckdns.org reverse_proxy localhost:8788 opencode WebUI
hermes-sc.duckdns.org reverse_proxy localhost:8787 Hermes Agent WebUI

Caddyfile real

tonatiuh.duckdns.org {
    root * /home/tonatiuh/SmallCountry/web/site
    file_server
}

forgejo-sc.duckdns.org {
    reverse_proxy localhost:3000
}

opencode-sc.duckdns.org {
    reverse_proxy localhost:8788
    header {
        -Content-Security-Policy
        -Content-Security-Policy-Report-Only
        Content-Security-Policy "default-src 'self'; script-src 'self' 'unsafe-inline'; style-src 'self' 'unsafe-inline'; img-src 'self' data: blob:; font-src 'self' data:; connect-src 'self' wss://opencode-sc.duckdns.org"
    }
}

hermes-sc.duckdns.org {
    reverse_proxy localhost:8787
    header {
        -Content-Security-Policy
        -Content-Security-Policy-Report-Only
        Content-Security-Policy "default-src 'self'; script-src 'self' 'unsafe-inline' https://cdnjs.cloudflare.com; style-src 'self' 'unsafe-inline' https://cdnjs.cloudflare.com; img-src 'self' data: blob:; font-src 'self' data:; connect-src 'self' wss://hermes-sc.duckdns.org"
    }
}

Despliegue automatizado (CI/CD)

El sitio de tonatiuh.duckdns.org se despliega automáticamente mediante Forgejo Actions:

  1. Cada push a main con cambios en la documentación lanza el pipeline
  2. forgejo-sc.duckdns.org/smallcountry/ci-docs:latest construye el sitio con MkDocs
  3. El workflow copia site/* al directorio /home/tonatiuh/SmallCountry/web/site
  4. Caddy sirve los archivos estáticos sin necesidad de recarga

Permisos

Caddy corre como usuario caddy. Para poder leer los archivos dentro de /home/tonatiuh/ se añadió caddy al grupo tonatiuh:

sudo usermod -aG tonatiuh caddy
sudo systemctl restart caddy

Como usuario

Qué podrás hacer

  • No necesitas hacer nada. Caddy es transparente: convierte servicio.sc en la conexión correcta al servicio.
  • Todo el tráfico va cifrado con TLS.

Cómo se accederá

Plataforma Cómo
Navegador Transparente — los usuarios nunca interactúan directamente con Caddy
Ubuntu Transparente
Android Transparente
FireTV Transparente

Integración con otros servicios de SmallCountry

Servicio Relación
Authentik forward_auth en cada ruta — Caddy delega la autenticación a Authentik
Pi-hole Resuelve los nombres .sc para que Caddy reciba las peticiones
Forgejo Actions CI/CD que despliega el sitio estático en Caddy
Todos los servicios Es el proxy inverso de todo SmallCountry — toda petición web pasa por Caddy
CA interna de SmallCountry**** Certificados TLS internos para todos los servicios

Servicios que lo hacen posible

  • Caddy server — binario nativo, instalado como servicio systemd
  • Forgejo Actions — CI/CD con imagen Docker personalizada para builds offline
Para el administrador (diseño previsto)

Datos del servicio
LXC (contenedor ligero de Proxmox) 102
IP 10.10.10.102
Tier A
Impacto 🔴 Crítico — caída = ningún servicio web responde

Almacenamiento persistente
ZFS (sistema de archivos con integridad de datos) dataset rpool/datos/caddy
Montaje en LXC /opt/caddy/
Subdirectorios config/ data/ logs/
Backup PBS (sistema de copias de seguridad de Proxmox) diario + Caddyfile versionado en Forgejo

Healthcheck

curl -s https://caddy.sc:2019/config/

Logs y diagnóstico

docker logs --tail 100 caddy

Backup manual

zfs snapshot rpool/datos/caddy@manual-$(date +%Y%m%d)

Problemas comunes

  • "Servicio no responde": verificar que Caddy está corriendo y que el backend está up
  • "Certificado inválido": forzar renovación → docker exec caddy caddy reload
Para el arquitecto (diseño previsto)

Relaciones con otros servicios

flowchart LR
    PiHole[Pi-hole DNS] -->|Resuelve dominios .sc| Caddy[Caddy LXC 102]
    Caddy[Caddy LXC 102] -->|Delega autenticación| Authentik[Authentik LXC 105]
    Caddy[Caddy LXC 102] -->|TLS reverse_proxy| Backends[Todos los backends]
    Backends[Todos los backends] -->|vmbr2 y vmbr3| ServiciosFamilia[Servicios de familia, IoT y finca]
    Backends[Todos los backends] -->|vmbr1| ServiciosAdmin[Servicios de administración]

Configuración de red

Bridge Puerto Acceso desde
vmbr1 443 Red de administración
vmbr2 443 Red de familia
vmbr3 443 Red de IoT / finca

En Pi-hole

*.sc  →  10.10.10.102

En Caddy

servicio.sc {
    forward_auth authentik.sc
    reverse_proxy <!-- TODO: IP y puerto del backend -->10.10.{subred}.{lxc}:{puerto}
}

En Authentik
Provider Proxy — cada servicio usa forward_auth
Grupos asignados Según el servicio: familia / empresa / admin / finca

Orquestación

Componente Path
Rol Ansible roles/caddy/
Playbook deploy-caddy.yml
Módulo OpenTofu modules/caddy/
Semaphore Proyecto caddy, Template deploy
Forgejo Actions .forgejo/workflows/caddy.yml
Repo Forgejo infra-core/
Ficha versionada docs/fichas/programas/caddy.md

Secciones relacionadas

🌐 Enlaces de interés

Sitio oficial · Documentación · GitHub

📋 Relacionado con
🔧 Operaciones