# 📋 GUÍA COMPLETA PARA DESARROLLO - CI/CD proyectosacc

> **Fecha:** 17 de Abril 2026
> **Proyecto:** proyectosacc (SACC)
> **Repositorio:** https://bitbucket.org/ccsoft1/proyectosacc
> **Cuenta AWS:** 668889063715 (Desarrollo)

---

## 🎯 RESUMEN EJECUTIVO

Esta guía contiene toda la información necesaria para que el equipo de desarrollo configure y use el pipeline CI/CD del proyecto `proyectosacc`.

**Estado del Pipeline:** ✅ Funcionando
**Último Build:** #67 (Exitoso)
**Infraestructura:** ✅ Creada y validada

---

## 📁 ESTRUCTURA DEL PROYECTO

```
proyectosacc/
├── bitbucket-pipelines.yml          # Pipeline CI/CD (7 pasos)
├── scripts/
│   ├── aws-oidc-setup.sh            # Configuración OIDC AWS
│   ├── telegram-pipeline-notify.sh  # Notificaciones Telegram
│   ├── terraform-lock-cleanup.sh    # Limpieza de locks Terraform
│   ├── deploy.sh                    # Script de deploy manual
│   ├── health-check.sh              # Health check de servicios
│   ├── rollback.sh                  # Rollback de deploys
│   └── deploy-frontend-s3.sh        # Deploy frontend a S3
├── terraform/
│   ├── main.tf                      # Infraestructura principal
│   ├── variables.tf                 # Variables de Terraform
│   ├── outputs.tf                   # Outputs de Terraform
│   ├── backend.tf                   # Configuración backend S3
│   ├── backend.dev.hcl              # Backend desarrollo
│   ├── backend.prod.hcl             # Backend producción
│   ├── oidc-bitbucket.tf            # Configuración OIDC
│   ├── provider.tf                  # Providers AWS
│   ├── user-data.sh                 # Script inicialización EC2
│   └── environments/
│       ├── dev.tfvars               # Variables desarrollo
│       └── prod.tfvars              # Variables producción
├── nginx/                           # Configuración nginx
├── docs/                            # Documentación
├── .env.dev                         # Variables entorno dev
├── .env.prod                        # Variables entorno prod
└── .gitignore
```

---

## 🔧 CONFIGURACIÓN REQUERIDA EN BITBUCKET

### 1. Variables de Repositorio (Repository Variables)

Ve a: **Bitbucket → Repositorio → Repository settings → Repository variables**

#### Variables para Desarrollo (developer)

| Variable | Descripción | Valor / Ejemplo |
|----------|-------------|-----------------|
| `AWS_DEFAULT_REGION` | Región AWS | `mx-central-1` |
| `DEV_DB_PASSWORD` | Contraseña BD MariaDB | *(solicitar a Infra)* |
| `DEV_S3_FRONTEND_BUCKET` | Bucket S3 frontend | `ccsoft-proyectosacc-frontend-dev` |
| `DEV_S3_ARTIFACTS_BUCKET` | Bucket S3 artifacts | `ccsoft-proyectosacc-artifacts-dev` |
| `DEV_SERVER_IP_PROYECTOSACC` | IP servidor EC2 | `78.12.135.184` |
| `DEV_SERVER_USER_PROYECTOSACC` | Usuario SSH | `thoth` |
| `DEV_SSH_PORT_PROYECTOSACC` | Puerto SSH | `22` |
| `DEV_SSH_PRIVATE_KEY_THOTH_PROYECTOSACC` | Llave SSH (Base64) | *(solicitar a Infra)* |
| `DEV_TELEGRAM_BOT_TOKEN` | Token bot Telegram | *(solicitar a Infra)* |
| `DEV_TELEGRAM_CHAT_ID` | ID chat Telegram | *(solicitar a Infra)* |

#### Variables para Producción (master)

| Variable | Descripción | Valor / Ejemplo |
|----------|-------------|-----------------|
| `AWS_DEFAULT_REGION` | Región AWS | `mx-central-1` |
| `PROD_DB_PASSWORD` | Contraseña BD MariaDB | *(solicitar a Infra)* |
| `PROD_S3_FRONTEND_BUCKET` | Bucket S3 frontend | *(configurar)* |
| `PROD_S3_ARTIFACTS_BUCKET` | Bucket S3 artifacts | *(configurar)* |
| `PROD_SERVER_IP_PROYECTOSACC` | IP servidor EC2 | *(configurar)* |
| `PROD_SERVER_USER_PROYECTOSACC` | Usuario SSH | `thoth` |
| `PROD_SSH_PORT_PROYECTOSACC` | Puerto SSH | `22` |
| `PROD_SSH_PRIVATE_KEY_THOTH_PROYECTOSACC` | Llave SSH (Base64) | *(solicitar a Infra)* |
| `PROD_TELEGRAM_BOT_TOKEN` | Token bot Telegram | *(solicitar a Infra)* |
| `PROD_TELEGRAM_CHAT_ID` | ID chat Telegram | *(solicitar a Infra)* |

### 2. Configuración OIDC (OpenID Connect)

El pipeline usa OIDC para autenticación con AWS. **No se requieren credenciales estáticas**.

**Configuración ya implementada:**
- Rol IAM: `BitbucketProyectosaccCICDRoleDev`
- Proveedor OIDC: Configurado para Bitbucket
- Alcance: Repositorio `ccsoft1/proyectosacc`

**Para producción:** Se debe crear un rol similar para el entorno prod.

---

## 🚀 PIPELINE CI/CD (7 Pasos)

### Flujo del Pipeline

```
┌─────────────────────────────────────────────────────────────┐
│  RAMA DEVELOPER                                             │
├─────────────────────────────────────────────────────────────┤
│  01_image-setup        → Preparar imagen + SSH keys         │
│  02_pre_terraform_check→ Limpiar locks de Terraform         │
│  03_terraform          → Infraestructura (plan + apply)     │
│  04_build              → Compilar frontend + backend        │
│  05_publish            → Subir a S3                         │
│  06_install            → Instalar JAR en servidor           │
│  07_deploy             → Deploy + Invalidar CloudFront      │
└─────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────┐
│  RAMA MASTER (Producción)                                   │
├─────────────────────────────────────────────────────────────┤
│  01_image-setup        → Preparar imagen + SSH keys         │
│  02_pre_terraform_check→ Limpiar locks de Terraform         │
│  03_terraform          → Infraestructura (plan + apply)     │
│  04_build              → Compilar frontend + backend        │
│  05_publish            → Subir a S3                         │
│  06_install            → Instalar JAR en servidor           │
│  06b_notify_approval   → Notificar espera aprobación        │
│  07_deploy             → Deploy manual (requiere aprobación)│
└─────────────────────────────────────────────────────────────┘
```

### Detalle de Steps

#### Step 01: image-setup
- Instala dependencias: openssh-client, openjdk-21-jdk, wget, unzip, curl
- Instala AWS CLI v2
- Configura llaves SSH para acceso al servidor
- Configura notificaciones Telegram

#### Step 02: pre_terraform_check
- Instala AWS CLI
- Configura credenciales OIDC
- Ejecuta `terraform-lock-cleanup.sh`
- **Previene errores de state lock**

#### Step 03: terraform
- Instala Terraform 1.11.4
- Ejecuta `terraform init`
- Ejecuta `terraform plan` (verificación)
- Ejecuta `terraform apply` (crea/actualiza infraestructura)
- Genera `terraform-outputs.json`

#### Step 04: build
- **Frontend:** Si existe `package.json` → `npm ci && npm run build`
- **Backend:** Si existe `gradlew` → `./gradlew clean bootJar`
- Genera artefactos: `build/**`, `build/libs/*.jar`

#### Step 05: publish
- Sincroniza `build/` con S3 frontend (`aws s3 sync`)
- Copia JAR a S3 artifacts (`aws s3 cp`)

#### Step 06: install
- Descarga JAR desde S3 al servidor EC2
- Configura permisos (`chown osiris:osiris`)

#### Step 07: deploy
- Ejecuta script de deploy en servidor EC2
- Invalida distribución CloudFront
- Notifica éxito por Telegram

---

## 🌐 INFRAESTRUCTURA AWS (Creada)

### Recursos Activos

| Servicio | Recurso | Identificador | Estado |
|----------|---------|---------------|--------|
| **EC2** | Instancia API | `i-044018f36de1020a8` | ✅ running |
| | IP Pública | `78.12.135.184` | ✅ |
| | DNS | `ec2-78-12-135-184.mx-central-1.compute.amazonaws.com` | ✅ |
| **RDS** | Base de datos | `proyectosacc-db-dev` | ✅ available |
| | Endpoint | `proyectosacc-db-dev.cbe2keowyu6w.mx-central-1.rds.amazonaws.com:3306` | ✅ |
| | Motor | MariaDB | ✅ |
| **S3** | Frontend | `ccsoft-proyectosacc-frontend-dev` | ✅ |
| | Artifacts | `ccsoft-proyectosacc-artifacts-dev` | ✅ |
| | Terraform State | `ccsoft-terraform-state` | ✅ |
| **CloudFront** | Distribución | `E2EJ7237VFEJAR` | ✅ Deployed |
| | Dominio | `d3donfm7ov3eyb.cloudfront.net` | ✅ |
| **Route53** | Zona DNS | `dev-sacc.ccsoft.mx` | ✅ |
| **VPC** | Red | `vpc-0fefbaa0848a316dd` (10.1.0.0/16) | ✅ |
| **NAT Gateway** | Salida privada | `nat-0dafd3abd5557cd22` | ✅ |
| **DynamoDB** | Locks Terraform | `terraform-locks` | ✅ |

### Outputs de Terraform

```json
{
  "ec2_public_ip": "78.12.135.184",
  "ec2_public_dns": "ec2-78-12-135-184.mx-central-1.compute.amazonaws.com",
  "rds_endpoint": "proyectosacc-db-dev.cbe2keowyu6w.mx-central-1.rds.amazonaws.com:3306",
  "s3_frontend_bucket": "ccsoft-proyectosacc-frontend-dev",
  "s3_artifacts_bucket": "ccsoft-proyectosacc-artifacts-dev",
  "cloudfront_domain": "d3donfm7ov3eyb.cloudfront.net",
  "cloudfront_distribution_id": "E2EJ7237VFEJAR",
  "route53_record": "dev-sacc.ccsoft.mx",
  "acm_certificate_arn": "arn:aws:acm:us-east-1:668889063715:certificate/521e3ae2-f22b-479f-a5ae-db9700caa248",
  "vpc_id": "vpc-0fefbaa0848a316dd"
}
```

---

## 🔐 ACCESOS Y CREDENCIALES

### Servidor EC2 (Desarrollo)

```bash
# Conexión SSH
ssh -p 22 -i ~/.ssh/sacc4_key thoth@78.12.135.184

# Usuarios configurados
- thoth: Usuario de deploy (CI/CD)
- osiris: Usuario de ejecución de la aplicación
```

### Base de Datos (RDS)

```
Host: proyectosacc-db-dev.cbe2keowyu6w.mx-central-1.rds.amazonaws.com
Port: 3306
Engine: MariaDB
Usuario: *(configurado en Terraform)*
Contraseña: ${DEV_DB_PASSWORD}
```

### S3 Buckets

```bash
# Frontend
aws s3 ls s3://ccsoft-proyectosacc-frontend-dev/

# Artifacts
aws s3 ls s3://ccsoft-proyectosacc-artifacts-dev/
```

---

## 📱 NOTIFICACIONES TELEGRAM

### Bots Configurados
- **@CCAlertasBot** - Alertas críticas
- **@CCDevRoBot** - Notificaciones de desarrollo

### Mensajes Enviados
- ✅ Inicio de pipeline
- ❌ Fallo de pipeline (con detalle del paso)
- ✅ Deploy exitoso
- ⏸️ Espera de aprobación (producción)

---

## 💰 COSTOS MENSUALES ESTIMADOS

| Servicio | Costo Estimado |
|----------|---------------|
| EC2 t3.small | ~$15-20 |
| RDS db.t3.micro | ~$15-20 |
| NAT Gateway | ~$32 |
| S3 (3 buckets) | ~$1-5 |
| CloudFront | ~$1-10 |
| Route53 | ~$0.50 |
| Data Transfer | ~$5-10 |
| **TOTAL** | **~$70-100/mes** |

---

## 🛠️ COMANDOS ÚTILES

### Terraform (Local)

```bash
# Configurar credenciales
export AWS_ACCESS_KEY_ID=...
export AWS_SECRET_ACCESS_KEY=...
export AWS_SESSION_TOKEN=...
export AWS_DEFAULT_REGION=mx-central-1

# Inicializar
cd terraform
terraform init -backend-config=backend.dev.hcl

# Plan
terraform plan -var-file=environments/dev.tfvars -var="db_password=TU_PASSWORD"

# Apply
terraform apply -var-file=environments/dev.tfvars -var="db_password=TU_PASSWORD"

# Outputs
terraform output -json
```

### AWS CLI

```bash
# Verificar identidad
aws sts get-caller-identity

# Listar instancias EC2
aws ec2 describe-instances

# Ver logs de CloudWatch
aws logs tail /aws/lambda/... --follow

# Invalidar CloudFront
aws cloudfront create-invalidation --distribution-id E2EJ7237VFEJAR --paths "/*"
```

### Bitbucket Pipelines

```bash
# Ejecutar pipeline manualmente
# Ir a: Bitbucket → Pipelines → Run pipeline
# Seleccionar rama: developer o master
```

---

## 🚨 TROUBLESHOOTING

### Error: "Error acquiring the state lock"

**Solución:** El pipeline ahora incluye el step `02_pre_terraform_check` que limpia locks automáticamente.

### Error: "Saved plan is stale"

**Solución:** El pipeline ahora ejecuta `plan` y `apply` sin guardar archivo intermedio.

### Error: "aws: command not found"

**Solución:** Cada step instala AWS CLI v2 independientemente.

### Pipeline falla en step 07_deploy

**Verificar:**
1. Llave SSH está configurada en Bitbucket variables
2. Servidor EC2 está running
3. Script `/home/thoth/deploy/setup/deploy.sh` existe en servidor

---

## 📞 CONTACTOS Y SOPORTE

| Rol | Contacto | Uso |
|-----|----------|-----|
| Infraestructura | Área de Tecnología | Credenciales, accesos AWS |
| DevOps | Pipeline issues | Configuración CI/CD |
| Seguridad | Rotación de llaves | SSH, tokens |

---

## ✅ CHECKLIST PARA DESARROLLO

### Antes de hacer push

- [ ] Código compila localmente (`npm run build` o `./gradlew bootJar`)
- [ ] Tests pasan
- [ ] Variables de entorno actualizadas (si aplica)

### Después de merge a developer

- [ ] Pipeline ejecuta automáticamente
- [ ] Revisar notificación de Telegram
- [ ] Verificar deploy en: https://dev-sacc.ccsoft.mx

### Para producción (master)

- [ ] Crear PR a master
- [ ] Revisar plan de Terraform
- [ ] Aprobar deploy manual en Bitbucket
- [ ] Verificar en producción

---

## 📚 DOCUMENTACIÓN ADICIONAL

- **Pipeline completo:** Ver `bitbucket-pipelines.yml`
- **Scripts:** Ver carpeta `scripts/`
- **Terraform:** Ver carpeta `terraform/`
- **Directivas AWS:** Ver `docs/13-directivas-arquitectura-aws.md`

---

**Documento generado:** 17 Abril 2026
**Versión:** 1.0
**Mantenido por:** Área de Tecnología y Desarrollo - CCsoft