proyectosacc-mirror/docs/09-runbook-deploy.md

09 - Runbook: Deploy Manual

Qué hacer si el pipeline automático falla y necesitas desplegar a mano.

---

1. ¿Cuándo hacer un deploy manual?

Un deploy manual significa que tú, persona humana, ejecutas los pasos que normalmente hace el pipeline automático.

Haz un deploy manual cuando:

• 🔴 El pipeline de Bitbucket falló y no se puede reintentar.
• 🟡 Necesitas desplegar una corrección urgente fuera de horario.
• 🟠 El servidor EC2 fue recreado y el pipeline no está configurado todavía.

---

2. Paso a paso: deploy manual

Un deploy manual ahora tiene dos partes: subir el frontend a S3 + CloudFront, y desplegar la API en la EC2.

---

PARTE A: Subir el frontend React a S3 e invalidar CloudFront

Esta parte puedes hacerla desde tu computadora local o desde cualquier máquina con AWS CLI configurada.

Paso A1: Ve a la carpeta del frontend compilado

cd /ruta/al/proyecto/frontend/build

Si no has compilado el frontend aún:

npm ci
npm run build

Paso A2: Sincroniza la carpeta build/ con S3

aws s3 sync . s3://ccsoft-proyectosacc-frontend --delete

Paso A3: Invalida la caché de CloudFront

aws cloudfront create-invalidation \
  --distribution-id <DISTRIBUTION_ID> \
  --paths "/*"

💡 Nota: el DISTRIBUTION_ID lo encuentras en la consola de AWS o en los outputs de Terraform.

Paso A4: Verifica el frontend

Abre tu navegador y visita:

https://sacc.ccsoft.mx

Si ves la interfaz de SACC, la parte A fue exitosa.

---

PARTE B: Desplegar la API backend en la EC2

Paso B1: Conéctate al servidor EC2

Necesitas la IP pública de la instancia y la llave SSH dedicada generada para proyectosacc.

ssh -i ~/.ssh/tu_llave.pem ubuntu@<IP_DE_LA_EC2>

O si ya estás dentro de la red de la empresa:

ssh thoth@<IP_DE_LA_EC2>

---

Paso B2: Conviértete en el usuario thoth

Si entraste como ubuntu, cambia al usuario de despliegue:

sudo su - thoth

---

Paso B3: Ve al directorio de despliegue

cd /home/thoth/deploy

---

Paso B4: Descarga el artefacto compilado de la API

Si el artefacto está en S3, descárgalo:

aws s3 cp s3://ccsoft-artifacts-sacc4/develop/proyectosacc-app-1.0.0.jar \
  /home/thoth/deploy/artifacts/current/

Si no tienes acceso a S3, pide el archivo .jar a un compañero y súbelo con scp.

---

Paso B5: Ejecuta el script de deploy de la API

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

Este script hará lo siguiente automáticamente:

1. Hará backup de la versión anterior.
2. Detendrá el servicio actual.
3. Copiará el nuevo archivo a su lugar.
4. Configurará y recargará systemd.
5. Iniciará el nuevo servicio.
6. Hará un health check.

---

Paso B6: Verifica que el servicio esté corriendo

sudo systemctl status proyectosacc-app.service

Deberías ver algo como:

● proyectosacc-app.service - Proyecto SACC App Service
   Loaded: loaded (/etc/systemd/system/proyectosacc-app.service; enabled)
   Active: active (running) since Mon 2026-04-14 10:30:00 UTC

Si dice active (running), ¡excelente!

---

Paso B7: Verifica el health check de la API

curl http://localhost:8080/actuator/health

La respuesta debe incluir:

{"status":"UP"}

---

Paso B8: Verifica la API desde fuera

Desde tu navegador o con curl, prueba un endpoint de la API:

curl https://sacc.ccsoft.mx/api/actuator/health

Si responde correctamente, el deploy manual completo fue exitoso.

---

3. Cómo revisar si el deploy funcionó

Frontend (S3 + CloudFront)

• Abre https://sacc.ccsoft.mx en el navegador.
• Revisa la consola de AWS > S3 para ver que los archivos nuevos estén en el bucket.
• Verifica el estado de la invalidación de CloudFront en la consola de AWS.

API (EC2)

Revisar los logs del servicio

sudo journalctl -u proyectosacc-app.service -n 50 --no-pager

Revisar el archivo de log de la aplicación

tail -n 50 /var/log/proyectosacc/proyectosacc-app/proyectosacc-app-service.log

Revisar que Nginx esté funcionando

sudo systemctl status nginx

Revisar que la API responda en el puerto correcto

ss -tlnp | grep 8080

---

4. Errores comunes y cómo arreglarlos

Error 1: "Permission denied" al conectarse por SSH

Causa: la llave SSH no tiene los permisos correctos o no está en authorized_keys.

Solución:

# En tu computadora local
chmod 600 ~/.ssh/tu_llave.pem

# En el servidor, como thoth
chmod 700 ~/.ssh
chmod 600 ~/.ssh/authorized_keys

---

Error 2: "No such file or directory" al ejecutar deploy.sh

Causa: el script no está donde esperas o la ruta es incorrecta.

Solución:

# Busca el script
find /home/thoth -name "deploy.sh"

# Luego ejecútalo con la ruta completa
bash /home/thoth/deploy/setup/deploy.sh

---

Error 3: El servicio no inicia (failed)

Causa: puede ser que falta Java, que el puerto 8080 ya está ocupado, o que hay un error en el archivo .jar.

Solución:

# Ver qué dice el log
sudo journalctl -u proyectosacc-app.service -n 100 --no-pager

# Ver si el puerto 8080 está ocupado
sudo lsof -i :8080

# Verificar que Java esté instalado
java -version

---

Error 4: Health check falla después del deploy

Causa: la aplicación inició pero no responde correctamente, o tarda más de lo esperado.

Solución:

# Espera unos segundos más y vuelve a intentar
curl -v http://localhost:8080/actuator/health

# Revisa si hay errores en el log de la app
tail -n 100 /var/log/proyectosacc/proyectosacc-app/proyectosacc-app-service.log

Si sigue fallando, considera ejecutar el rollback (ver 10-runbook-rollback.md).

---

Anterior: 08-seguridad-y-secretos.md
Siguiente: 10-runbook-rollback.md