Evert Daniel Romero Garrido
5.9 KiB
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_IDlo 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:
- Hará backup de la versión anterior.
- Detendrá el servicio actual.
- Copiará el nuevo archivo a su lugar.
- Configurará y recargará
systemd. - Iniciará el nuevo servicio.
- 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.mxen 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