Mantener la documentación técnica al día suele ser un dolor de cabeza. Si el proceso para subir un apunte nuevo implica conectarse por SSH al servidor, tirar un git pull a mano y reiniciar servicios, lo más probable es que terminemos postergándolo.

Para resolver esto en mi entorno, decidí diseñar un pipeline de CI/CD (Integración y Despliegue Continuo) que automatiza por completo el ciclo de vida de una wiki interna (basada en MkDocs) para el equipo de AsterVoIP.

Hoy quiero compartirles cómo conecté mi entorno de desarrollo local, GitHub y un servidor de producción Debian 12, logrando que documentar sea tan simple como hacer un git push.

🏗️ La Arquitectura del Pipeline

El objetivo era claro: escribir Markdown en la comodidad de mi PC local y delegar el despliegue al software. El flujo quedó estructurado en tres capas:

  1. Entorno Local (Fedora): Aquí es donde edito los archivos .md. Utilizo la interfaz gráfica de VS Code para la gestión de Git y un entorno ligero con podman-compose para previsualizar los cambios en tiempo real antes de subirlos.
  2. Orquestador (GitHub Actions): Funciona como el cerebro del sistema. Escucha los cambios en la rama main y dispara un Workflow automatizado.
  3. Servidor de Producción (Debian 12): Un nodo de infraestructura interna que corre el servicio final puramente sobre Docker Compose.

🛠️ El Corazón del Automatismo: El Workflow de GitHub

Para lograr que GitHub viaje a nuestro servidor e instruya a Docker, creamos un archivo de configuración en .github/workflows/deploy.yml.

Este script utiliza una acción basada en SSH para ingresar de forma segura y ejecutar los comandos nativos de la máquina:

YAML

name: Deploy Wiki

on:
  push:
    branches:
      - main

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Ejecutar comandos en el Servidor via SSH
        uses: appleboy/[email protected]
        with:
          host: ${{ secrets.SERVER_HOST }}
          username: ${{ secrets.SERVER_USER }}
          key: ${{ secrets.SERVER_SSH_KEY }}
          port: ${{ secrets.SERVER_PORT }}
          script: |
            cd /opt/mkdocs
            git pull origin main
            docker compose down
            docker compose up -d --build

🔒 Desafíos Técnicos y Seguridad (Lo que aprendí en el camino)

Montar un pipeline suena fácil en los tutoriales, pero en la práctica real siempre surgen los verdaderos desafíos.

1. Autenticación “Llave con Llave” (Deploy Keys)

Uno de los primeros bloqueos fue el git pull automatizado dentro del servidor. Si el repositorio está configurado por HTTPS, el servidor pedirá interactivamente usuario y contraseña de GitHub, rompiendo el script.

La solución: Cambiar el origen del repositorio remoto en producción a SSH ([email protected]:...) y generar un par de llaves criptográficas (ed25519). Registrando la clave pública del servidor como una Deploy Key en GitHub, el servidor Debian obtuvo “pase libre” para descargar los cambios de forma segura y transparente.

2. Aislamiento de Entornos (Podman vs Docker)

En mi máquina local utilizo Podman por una cuestión de políticas de seguridad y ligereza en mi distribución, mientras que el servidor de producción utiliza Docker corporativo. Mantener el pipeline agnóstico a estas herramientas y configurar correctamente las instrucciones de docker compose en el script de Actions fue vital para que el Runner no sufriera errores de comando no encontrado (command not found).

📈 El Resultado

El beneficio es inmediato. Ahora, el flujo de trabajo se reduce a:

  1. Escribir la documentación en VS Code.
  2. Hacer un Commit y Push desde la GUI.
  3. GitHub Actions + Docker hacen la magia: En menos de dos minutos, la imagen de MkDocs se recompila en el servidor Debian y los cambios quedan impactados en vivo para todo el equipo.

Automatizar la infraestructura pequeña o interna no solo ahorra tiempo, sino que estandariza los procesos bajo metodologías DevOps reales.