proyectosacc-mirror/docs/05-pipeline-bitbucket.md

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

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
Siguiente: 06-scripts-de-despliegue.md