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

```bash
cd /ruta/al/proyecto/frontend/build
```

Si no has compilado el frontend aún:
```bash
npm ci
npm run build
```

#### Paso A2: Sincroniza la carpeta `build/` con S3

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

#### Paso A3: Invalida la caché de CloudFront

```bash
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`.

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

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

```bash
ssh thoth@<IP_DE_LA_EC2>
```

---

#### Paso B2: Conviértete en el usuario thoth

Si entraste como `ubuntu`, cambia al usuario de despliegue:

```bash
sudo su - thoth
```

---

#### Paso B3: Ve al directorio de despliegue

```bash
cd /home/thoth/deploy
```

---

#### Paso B4: Descarga el artefacto compilado de la API

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

```bash
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
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

```bash
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

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

La respuesta debe incluir:
```json
{"status":"UP"}
```

---

#### Paso B8: Verifica la API desde fuera

Desde tu navegador o con `curl`, prueba un endpoint de la API:
```bash
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
```bash
sudo journalctl -u proyectosacc-app.service -n 50 --no-pager
```

#### Revisar el archivo de log de la aplicación
```bash
tail -n 50 /var/log/proyectosacc/proyectosacc-app/proyectosacc-app-service.log
```

#### Revisar que Nginx esté funcionando
```bash
sudo systemctl status nginx
```

#### Revisar que la API responda en el puerto correcto
```bash
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**:
```bash
# 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**:
```bash
# 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**:
```bash
# 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**:
```bash
# 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`](10-runbook-rollback.md)).

---

*Anterior: [`08-seguridad-y-secretos.md`](08-seguridad-y-secretos.md)*  
*Siguiente: [`10-runbook-rollback.md`](10-runbook-rollback.md)*