proyectosacc-mirror/GUIA_DESARROLLO.md

📋 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

{
  "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)

# 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

# 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)

# 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

# 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

# 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