# 05 - Pipeline Bitbucket

> Cómo funciona el pipeline de 7 pasos que despliega `proyectosacc`.

---

## 1. ¿Qué es un pipeline?

Un **pipeline** es una serie de pasos automáticos que se ejecutan cada vez que alguien sube código al repositorio.

En Cómputo Contable Soft, todos los pipelines web usan **7 pasos** estandarizados. Esto significa que, sin importar el proyecto, siempre hay los mismos pasos con los mismos nombres.

---

## 2. Los 7 pasos del pipeline

### Paso 1: `01_image-setup`
**Prepara la computadora virtual donde se va a compilar todo.**

Qué hace:
1. Actualiza los paquetes del sistema.
2. Instala herramientas necesarias: `openssh-client`, `openjdk-21-jdk`, `aws-cli`.
3. Configura las llaves SSH y los `known_hosts`.
4. Carga los scripts de utilería (`logger_bash.sh`, `telegram_alert.sh`).

> 💡 **En palabras simples**: como cuando llegas a una cocina nueva y primero lavas los trastes, prendes la estufa y sacas los utensilios.

---

### Paso 2: `02_repo-config`
**Descarga todos los repositorios que necesita la aplicación.**

Qué hace:
1. Clona el repositorio principal de la aplicación.
2. Clona los repositorios de componentes compartidos (por ejemplo, `cmp-commons`, `cmp-security`).
3. Clona `ci-cd-commons` (scripts base de CCsoft).

> 💡 **En palabras simples**: bajas todos los ingredientes de la receta antes de empezar a cocinar.

---

### Paso 3: `03_dependencies`
**Compila o descarga todo lo que la aplicación necesita para funcionar.**

Qué hace:
1. Compila las librerías compartidas.
2. Descarga dependencias de Maven, Gradle, npm, etc.
3. Publica las librerías locales si es necesario.

> 💡 **En palabras simples**: preparas la masa, cortas las verduras y sacas los condimentos antes de armar el platillo final.

---

### Paso 4: `04_build`
**Compila el frontend React y la API backend.**

Qué hace:
1. **Frontend**: ejecuta `npm run build` (o `npm ci && npm run build`) para generar la carpeta `build/` con el React estático.
2. **Backend**: ejecuta el comando de build de la API (por ejemplo, `./gradlew clean bootJar` para Java).
3. Genera los archivos finales: la carpeta `build/` para el frontend y el `.jar` para la API.

> 💡 **En palabras simples**: aquí cocinamos dos platillos: la entrada (frontend) y el plato fuerte (API).

---

### Paso 5: `05_publish`
**Sube el frontend a S3 y el artefacto de la API a Amazon S3.**

Qué hace:
1. **Frontend**: sincroniza la carpeta `build/` al bucket S3 designado para el sitio estático (`aws s3 sync build/ s3://bucket-name`).
2. **Backend**: sube el `.jar` (o artefacto equivalente) al bucket S3 para que la EC2 lo descargue después.
3. Esto evita transferir archivos grandes directamente por SSH y permite recuperar versiones anteriores fácilmente.

> 💡 **En palabras simples**: pones la entrada en el mostrador (S3) y el plato fuerte en la bandeja de la cocina (S3) para servirlo después.

---

### Paso 6: `06_install`
**Descarga el artefacto de la API en el servidor EC2.**

Qué hace:
1. Se conecta por SSH al servidor EC2 como `thoth`.
2. Ejecuta un script de preparación que descarga el `.jar` desde **S3** y lo coloca en `/home/thoth/deploy/artifacts/current/`.
3. También hace una copia de seguridad de la versión anterior.
4. **Aún no reinicia el servicio**: eso ocurre en el paso 7.

> 💡 **En palabras simples**: pones el plato fuerte en el plato y lo dejas listo, pero aún no lo sirves.

---

### Paso 7: `07_deploy`
**Invalida la caché de CloudFront, despliega la API y verifica que todo esté saludable.**

Qué hace:
1. **Invalida la caché de CloudFront** (`aws cloudfront create-invalidation`) para que los usuarios vean la nueva versión del frontend inmediatamente.
2. Se conecta por SSH al servidor EC2 como `thoth` y ejecuta `bash /home/thoth/deploy/setup/deploy.sh`.
3. El script `deploy.sh` crea o actualiza el servicio de `systemd`, detiene la versión anterior e inicia la nueva con el usuario `osiris`.
4. Ejecuta un **health check** en la API para verificar que responde correctamente.
5. Envía una notificación por Telegram con el resultado.

> 💡 **En palabras simples**: actualizas el menú en todos los restaurantes (CloudFront) y sirves el plato fuerte calentito desde la cocina (EC2).

---

## 3. Diagrama del pipeline

```
┌─────────────────────────────────────────────────────────────────────────────┐
│                        BITBUCKET PIPELINE                                   │
│                                                                             │
│  1. image-setup    ▶  Instala herramientas                                  │
│         │                                                                   │
│         ▼                                                                   │
│  2. repo-config    ▶  Descarga repositorios                                  │
│         │                                                                   │
│         ▼                                                                   │
│  3. dependencies   ▶  Compila librerías y dependencias                       │
│         │                                                                   │
│         ▼                                                                   │
│  4. build          ▶  Compila React frontend + API backend (.jar)            │
│         │                                                                   │
│         ▼                                                                   │
│  5. publish        ▶  Sube frontend a S3 web + API .jar a S3 artifacts       │
│         │                                                                   │
│         ▼                                                                   │
│  6. install        ▶  Prepara la API en el servidor EC2                      │
│         │                                                                   │
│         ▼                                                                   │
│  7. deploy         ▶  Invalida CloudFront, reinicia API y health check       │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘
```

---

## 4. ¿Cómo se conecta el pipeline a la EC2?

La conexión se hace por **SSH** (Secure Shell).

1. El pipeline tiene guardada la **llave privada** de `thoth` en una variable segura de Bitbucket.
2. Al llegar al paso `05_publish` o `06_install`, el pipeline decodifica la llave y la guarda en `/root/.ssh/sacc4_key`.
3. Ejecuta un comando `ssh` usando esa llave para ejecutar scripts remotos.
4. La **llave pública** correspondiente ya está en el archivo `~/.ssh/authorized_keys` del usuario `thoth` en la EC2.
5. ¡La puerta se abre y el pipeline puede ejecutar comandos en el servidor!

### Ejemplo del comando que usa el pipeline
```bash
ssh -p 22 \
  -i /root/.ssh/sacc4_key \
  -o StrictHostKeyChecking=no \
  thoth@<IP_DE_LA_EC2> \
  "bash /home/thoth/deploy/setup/deploy.sh"
```

---

## 5. ¿De dónde salen los secrets?

Los **secrets** (contraseñas, llaves, tokens) viven en las **variables de repositorio** de Bitbucket.

### Cómo se configuran
1. Entra al repositorio en Bitbucket.
2. Ve a **Repository settings > Pipelines > Repository variables**.
3. Agrega cada variable y márcala como **Secured** 🔒.
4. Las variables marcadas como secured se ofuscan en los logs (aparecen como `***`).

### Variables principales

| Variable | Descripción |
|----------|-------------|
| `PROYECTOSACC_SSH_KEY` | Llave privada SSH (en base64) dedicada para conectar al servidor |
| `PROYECTOSACC_SERVER_IP` | IP pública de la EC2 |
| `PROYECTOSACC_SSH_PORT` | Puerto SSH (normalmente `22`) |
| `PROYECTOSACC_SERVER_USER` | Usuario SSH para despliegue (`thoth`) |
| `PROYECTOSACC_TELEGRAM_BOT_TOKEN` | Token del bot de Telegram para alertas |
| `PROYECTOSACC_TELEGRAM_CHAT_ID` | ID del chat donde llegan las alertas |
| `AWS_ACCESS_KEY_ID` | Credencial de AWS para subir a S3 |
| `AWS_SECRET_ACCESS_KEY` | Credencial secreta de AWS |
| `CLOUDFRONT_DISTRIBUTION_ID` | ID de la distribución de CloudFront para invalidaciones |
| `S3_FRONTEND_BUCKET` | Nombre del bucket S3 donde se publica el frontend |

### ⚠️ Regla de oro
**NUNCA** escribas secrets directamente en el código del pipeline (`bitbucket-pipelines.yml`). Siempre usa variables de entorno.

---

## 6. Integración con proyectos CI/CD compartidos

`proyectosacc` no trabaja solo. Se conecta con otros proyectos de CI/CD de la empresa que proveen piezas reutilizables:

- **`ci-cd-commons`**: scripts base compartidos como `telegram_alert.sh` y `logger_bash.sh`.
- **`ci-cd-saac4`**: módulos de Terraform, patrones de infraestructura y scripts de despliegue específicos para la familia SACC.

Esto significa que parte del pipeline y de los scripts de despliegue vienen de esos repositorios, no de este. Es como armar una casa con ladrillos que ya están hechos en otra fábrica.

---

*Anterior: [`04-usuarios-y-permisos.md`](04-usuarios-y-permisos.md)*  
*Siguiente: [`06-scripts-de-despliegue.md`](06-scripts-de-despliegue.md)*
