Skip to main content

Construcción de Caddy con xcaddy y módulos personalizados

Introducción

Este artículo documenta la construcción personalizada de Caddy mediante xcaddy, incorporando únicamente los módulos necesarios para el uso habitual en la infraestructura. El objetivo es disponer de un binario controlado, reproducible y alineado con las necesidades reales, evitando dependencias externas o configuraciones parciales.

El proceso se automatiza mediante un script que gestiona la compilación, la instalación del binario resultante, la validación de la configuración y el reinicio del servicio. Este enfoque permite actualizar Caddy de forma coherente, sin instalaciones manuales ni pasos intermedios frágiles.

¿Por qué usar xcaddy?

Caddy no incluye todos los módulos posibles en su binario oficial. Determinadas funcionalidades, como el DNS challenge con proveedores externos o módulos HTTP específicos, requieren que el binario se compile explícitamente con ellos.

xcaddy es la herramienta oficial que permite:

  • Construir un binario único de Caddy con módulos adicionales.
  • Mantener control total sobre qué capacidades se incluyen.
  • Evitar binarios genéricos con dependencias innecesarias.
  • Reproducir el mismo binario en distintos entornos.

Este enfoque es especialmente útil cuando Caddy actúa como pieza central del frontend HTTPS.

Características del enfoque

  • Compilación automatizada mediante xcaddy.
  • Inclusión explícita de los módulos necesarios.
  • Sustitución directa del binario de Caddy existente.
  • Validación y formateo del Caddyfile.
  • Reinicio controlado del servicio y comprobación de estado.

Módulos incluidos

El binario se construye con los siguientes módulos:

  • DNS Cloudflare: permite realizar validaciones ACME mediante DNS challenge, necesario cuando no se exponen puertos públicos o se quiere evitar HTTP-01.
  • transform-encoder: se utiliza para transformar y personalizar el formato de logs, facilitando formatos compatibles con nginx u otros sistemas de análisis.

El script actual no incluye módulos adicionales; cualquier ampliación debe declararse explícitamente en la fase de build.

Requisitos previos

Para ejecutar el script de construcción es necesario:

  • Go instalado en el sistema.
  • xcaddy disponible en el entorno.
  • Caddy gestionado como servicio mediante systemd.

Si alguno de estos elementos falta, la compilación no podrá completarse.

Instalación manual de Go

Se instala Go de forma manual para asegurar la versión utilizada durante la compilación:

sudo rm -rf /usr/local/go && sudo tar -C /usr/local -xzf go1.23.3.linux-amd64.tar.gz
export PATH=$PATH:/usr/local/go/bin
echo 'export PATH=$PATH:/usr/local/go/bin' >> ~/.bashrc
source ~/.bashrc
go version

Este método evita depender de versiones empaquetadas potencialmente desactualizadas.

Instalación de xcaddy desde el repositorio oficial

sudo apt install -y debian-keyring debian-archive-keyring apt-transport-https
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/xcaddy/gpg.key' | sudo gpg --dearmor -o /usr/share/keyrings/caddy-xcaddy-archive-keyring.gpg
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/xcaddy/debian.deb.txt' | sudo tee /etc/apt/sources.list.d/caddy-xcaddy.list
sudo apt update && sudo apt install xcaddy
xcaddy version

La instalación desde el repositorio oficial asegura compatibilidad con las versiones actuales de Caddy.

Script de construcción

La lógica completa de compilación, instalación y validación se encuentra en el siguiente repositorio:

El script realiza las siguientes acciones, de forma secuencial:

  • Construye Caddy mediante xcaddy build, incluyendo únicamente los módulos definidos.
  • Verifica que el binario generado responde correctamente (caddy --version).
  • Reemplaza el binario existente en /usr/bin/caddy sin interacción.
  • Ejecuta el formateo del Caddyfile mediante caddy fmt.
  • Reinicia el servicio de Caddy gestionado por systemd.
  • Comprueba que el servicio queda activo tras el reinicio.

El script está diseñado para fallar de forma temprana si ocurre cualquier error crítico durante el proceso, evitando dejar el sistema en un estado inconsistente.

Errores comunes y decisiones importantes

  • Si Go o xcaddy no están disponibles, la compilación falla.
  • El servicio de Caddy debe estar gestionado por systemd.
  • El formateo del Caddyfile no es obligatorio, pero evita errores sutiles.
  • El binario se reemplaza sin confirmación interactiva, asumiendo que se desea actualizar.

Este comportamiento es intencionado para favorecer automatización y consistencia.

Resumen breve

  • Instalar Go y xcaddy.
  • Ejecutar el script de construcción.
  • Verificar que el servicio arranca correctamente.

Notas personales

El script puede adaptarse fácilmente para incluir otros módulos o ajustarse a distintos escenarios. La selección actual cubre las necesidades habituales sin añadir complejidad innecesaria.

Referencias

Back to top