proyectosacc-mirror/docs/06-scripts-de-despliegue.md

06 - Scripts de Despliegue

Qué hace cada script y cuándo se ejecuta.

---

1. ¿Qué son los scripts de despliegue?

Los scripts son archivos de texto con instrucciones que la computadora puede ejecutar automáticamente.

En proyectosacc usamos scripts escritos en Bash (el lenguaje de comandos de Linux). Todos comienzan con esta línea mágica:

set -euo pipefail

Esto significa tres cosas:

1. set -e: Si un comando falla, el script se detiene inmediatamente.
2. set -u: Si usas una variable que no existe, el script se detiene.
3. set -o pipefail: Si un comando dentro de una "tubería" (|) falla, el script también se detiene.

💡 En palabras simples: es como poner el cinturón de seguridad antes de manejar.

---

1.1. Scripts provenientes de otros proyectos CI/CD

proyectosacc reutiliza scripts y utilerías que viven en repositorios compartidos:

• ci-cd-commons: contiene telegram_alert.sh, logger_bash.sh y otras utilerías base que usan todos los pipelines de la empresa.
• ci-cd-saac4: provee módulos de Terraform y scripts de despliegue adaptados para la familia SACC.

Estos repositorios se clonan dentro de la carpeta /home/thoth/deploy/ (por ejemplo, /home/thoth/deploy/ci-cd-commons/) para que los scripts locales puedan usarlos.

1.2. Nuevo script: deploy-frontend-s3.sh

Este script se ejecuta desde el pipeline de Bitbucket (no dentro de la EC2). Su trabajo es subir el frontend React a S3.

Qué hace:

1. Sincroniza la carpeta build/ con el bucket S3 (aws s3 sync build/ s3://bucket-name --delete).
2. Espera a que la sincronización termine.

💡 Nota: la invalidación de la caché de CloudFront se hace en el paso 7 del pipeline (07_deploy), después de confirmar que la API está saludable. Así evitamos refrescar el frontend antes de que el backend esté listo.

Ejemplo de comando:

bash /home/thoth/deploy/scripts/deploy-frontend-s3.sh

---

2. deploy.sh

¿Qué hace?

Este es el script principal de despliegue de la API backend. Se ejecuta dentro del servidor EC2 y se encarga de instalar la nueva versión del servicio.

Pasos que sigue

1. Crear directorios: verifica que existan las carpetas necesarias (backup, current, pids, logs).
2. Detener servicio anterior: si la aplicación ya está corriendo, la detiene con systemctl.
3. Configurar systemd: crea o actualiza el archivo de servicio para que la app inicie automáticamente.
4. Recargar systemd: ejecuta sudo systemctl daemon-reload.
5. Iniciar servicio: ejecuta sudo systemctl start <nombre-del-servicio>.
6. Health check: hace peticiones a http://localhost:8080/actuator/health para verificar que la app responde.
7. Guardar PID: anota el ID del proceso para poder monitorearlo después.

¿Cuándo se llama?

• En el paso 7 del pipeline (07_deploy).
• También puede ejecutarse manualmente si necesitas hacer un despliegue fuera del pipeline.

Ejemplo de comando

bash /home/thoth/deploy/setup/deploy.sh

---

3. health-check.sh

¿Qué hace?

Verifica que la aplicación esté viva y respondiendo correctamente.

Cómo funciona

1. Intenta conectarse a la URL de salud de la aplicación:

   http://localhost:8080/actuator/health
   

2. Si la respuesta contiene "status":"UP", todo está bien.
3. Si no responde después de varios intentos, reporta un error.

¿Cuándo se llama?

• Dentro de deploy.sh, inmediatamente después de iniciar el servicio.
• También puede usarse manualmente para revisar si la app sigue funcionando horas después del despliegue.

Ejemplo de comando manual

bash /home/thoth/deploy/scripts/health-check.sh

---

4. rollback.sh

¿Qué hace?

Regresa la API backend a la versión anterior si el nuevo despliegue falló. También puede restaurar el frontend en S3 si se habilitó versionamiento de objetos en el bucket.

Pasos que sigue (API en EC2)

1. Busca el último backup en la carpeta /home/thoth/deploy/artifacts/backup/.
2. Detiene el servicio actual.
3. Copia el backup a la carpeta current.
4. Reinicia el servicio con la versión anterior.
5. Ejecuta un health check para confirmar que la versión anterior todavía funciona.

Pasos que sigue (frontend en S3)

Si el frontend también necesita rollback:

1. Identifica la versión anterior del archivo en S3 usando el versionamiento del bucket.
2. Restaura la versión anterior de index.html y los assets estáticos.
3. Invalida la caché de CloudFront para que los usuarios vean la versión anterior.

¿Cuándo se llama?

• Cuando el deploy.sh o el health-check.sh reportan un fallo en la API.
• Manualmente, si descubres que la nueva versión del frontend o la API tiene un bug grave.

Ejemplo de comando

bash /home/thoth/deploy/scripts/rollback.sh

---

5. notify-telegram.sh

¿Qué hace?

Envía mensajes a un grupo o chat de Telegram para informar sobre el estado del pipeline.

Qué tipo de mensajes envía

• 🟢 Éxito: "El despliegue de proyectosacc terminó correctamente."
• 🔴 Error: "El pipeline de proyectosacc falló en el paso 4. Revisar logs."
• 🟡 Advertencia: "Health check falló. Iniciando rollback automático."

¿Cuándo se llama?

• Al inicio del pipeline.
• Al final del pipeline (éxito o fracaso).
• Cuando ocurre un error en cualquier paso.

Variables necesarias

TELEGRAM_BOT_TOKEN=<token-del-bot>
TELEGRAM_CHAT_ID=<id-del-chat>

Ejemplo de comando

bash /home/thoth/deploy/ci-cd-commons/telegram_alert.sh "Despliegue exitoso"

---

6. Resumen de cuándo usar cada script

Script	¿Cuándo se ejecuta?	¿Dónde corre?
deploy-frontend-s3.sh	Paso 5 del pipeline (subir React a S3)	Pipeline (Bitbucket)
deploy.sh	Paso 7 del pipeline (desplegar API en la EC2), o manualmente	Dentro de la EC2
health-check.sh	Después de deploy.sh, o manualmente	Dentro de la EC2
rollback.sh	Cuando deploy.sh o health-check.sh fallan, o manualmente	Pipeline o EC2
notify-telegram.sh	Inicio, fin o error del pipeline	Pipeline (Bitbucket) o EC2

---

7. Dato extra: ¿dónde viven los scripts?

En el servidor EC2, los scripts se organizan así:

/home/thoth/deploy/
├── artifacts/
│   ├── backup/          ← versiones anteriores de la API
│   ├── current/         ← versión activa de la API
│   ├── logs/            ← logs del pipeline
│   └── pids/            ← archivos con el ID de proceso
├── ci-cd-commons/
│   ├── telegram_alert.sh
│   └── logger_bash.sh
├── scripts/
│   ├── deploy-frontend-s3.sh   ← sube React a S3
│   ├── health-check.sh
│   └── rollback.sh
└── setup/
    └── deploy.sh               ← script principal del pipeline para la API (llamado vía SSH)

💡 Nota: el artefacto de la API que termina en artifacts/current/ se descarga desde Amazon S3 durante el paso de instalación del pipeline. No se transfiere directamente por SSH. El frontend React se sube directamente a S3 desde el pipeline.

---

Anterior: 05-pipeline-bitbucket.md
Siguiente: 07-terraform-iac.md