Cómo automatizar deploys con webhooks y Docker

El proceso de desplegar una aplicación —pasar tu código de desarrollo a producción— puede ser un cuello de botella si se hace a mano. Un git pull, un docker compose build, un docker compose up -d repetido cada vez que hay un cambio es tedioso y propenso a errores. Por eso, automatizar estos despliegues con webhooks y Docker es una mejora directa en la fiabilidad de tu infraestructura.

El problema del despliegue manual en Docker

Cada vez que se lanza una nueva funcionalidad o se corrige un error, necesitas actualizar el servidor. Si haces esto con comandos manuales, siempre existe la posibilidad de olvidar un paso o ejecutar un comando incorrecto. Esto es especialmente crítico cuando trabajas con Docker, donde una mala construcción o un up desincronizado puede dejar tu aplicación en un estado inestable.

El proceso manual introduce variabilidad donde debería haber consistencia. Lo que ganas en control granular en un momento dado, lo pierdes en repetibilidad y seguridad a largo plazo.

Automatización de despliegues con un webhook

Un webhook es simplemente una llamada HTTP que se dispara cuando ocurre un evento específico, como un push a tu repositorio Git. Configuramos el proveedor de Git (GitHub, GitLab, Gitea) para que, cada vez que haya un push a la rama principal, envíe una petición a nuestro servidor. Esta petición es el disparador de nuestra automatización de despliegue.

En el servidor, un pequeño servicio HTTP escucha ese webhook. Cuando lo recibe, ejecuta un script que se encarga de actualizar el código y reconstruir los contenedores Docker.

Montando el sistema: de Git a Docker

Para que esto funcione, necesitas un pequeño servidor HTTP en tu VPS que reciba el webhook. Una opción ligera es usar una herramienta como webhook de adnanh. Lo configuras para que escuche en un puerto específico y, al recibir una petición con la clave secreta correcta, ejecute un script Bash.

Este script Bash se encargará de hacer git pull de tu repositorio, reconstruir las imágenes Docker y reiniciar los servicios. Aquí tienes un ejemplo simplificado de cómo se vería un hooks.json para webhook y el script que ejecutaría:

[
  {
    "id": "deploy-app",
    "execute-command": "/opt/deploy-script.sh",
    "command-working-directory": "/opt/",
    "trigger-rule": {
      "and": [
        {
          "type": "payload-hmac-sha256",
          "secret": "TU_SECRETO_SEGURO",
          "header": "X-Hub-Signature-256"
        },
        {
          "type": "payload-extraction",
          "json": {
            "actual": "$.ref",
            "expect": "refs/heads/main"
          }
        }
      ]
    }
  }
]

El script /opt/deploy-script.sh podría ser algo así:

#!/bin/bash

# Navega al directorio de tu proyecto
cd /ruta/a/tu/proyecto || exit

# Asegúrate de que el repositorio está actualizado
git pull origin main

# Reconstruye y levanta los servicios Docker
docker compose pull
docker compose up -d --build

echo "Deploy completado en $(date)" >> /var/log/deploy.log

Asegúrate de que tu docker-compose.yml está configurado para usar variables de entorno de forma segura, evitando datos sensibles directamente en el código. Tengo una guía sobre variables de entorno en Docker que te puede ser útil para esto.

El tradeoff de la automatización por webhook

La automatización de despliegues con webhooks y Docker simplifica mucho la gestión, pero también añade puntos a considerar. Es una cuestión de equilibrio entre comodidad y control.

Lo que ganas:

Consistencia: Cada despliegue sigue el mismo procedimiento exacto, eliminando errores humanos.
Velocidad: Los cambios se aplican a producción en segundos o minutos después de un push a Git.
Trazabilidad: Cada actualización está ligada a un commit específico, facilitando la identificación de problemas.
Menos trabajo manual: Libera tiempo del equipo para tareas de mayor valor.

Lo que complicas:

Configuración inicial: Requiere montar el servicio de webhook y los scripts en el servidor.
Seguridad: El endpoint del webhook debe estar bien protegido con secretos y firewalls.
Dependencia: Si el servicio de webhook falla, los despliegues automáticos se detienen.
Depuración: Los problemas pueden ser más difíciles de diagnosticar al principio si el script no es robusto.

Lo que no negocias:

Versionado de código: Tu código fuente debe estar en Git y seguir un buen sistema de ramas, como explico en mi artículo sobre Git para equipos pequeños.
Backups: Un sistema de despliegue automatizado no sustituye una buena estrategia de copias de seguridad.
Rollbacks: Siempre debes tener un plan para revertir un despliegue si algo sale mal. Esto es un requisito para despliegues sin miedo.

Si ya tienes un sistema de despliegue montado y buscas optimizarlo, te interesa mi artículo sobre monitorización VPS básica para mantenerlo bajo control. Y si te planteas automatizar más flujos en tu negocio, tengo una guía sobre cómo poner n8n en producción con Docker y Traefik.