Skip to content

Commit bf2c6e7

Browse files
2-Coatl2-Coatl
committed
docs(arquitectura): actualizar canvas devcontainer host vagrant
1 parent ff50ee4 commit bf2c6e7

40 files changed

Lines changed: 776 additions & 102 deletions

File tree

‎.devcontainer/.env.example‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
# DevContainer environment variables for local development
2+
3+
# Django settings
4+
DJANGO_SETTINGS_MODULE=callcentersite.settings.development
5+
DEBUG=True
6+
7+
# PostgreSQL (default database)
8+
POSTGRES_HOST=db_postgres
9+
POSTGRES_PORT=5432
10+
POSTGRES_DB=callcenter_db
11+
POSTGRES_USER=postgres
12+
POSTGRES_PASSWORD=postgres
13+
14+
# MariaDB (legacy database)
15+
MARIADB_HOST=db_mariadb
16+
MARIADB_PORT=3306
17+
MARIADB_DATABASE=callcenter_legacy
18+
MARIADB_USER=root
19+
MARIADB_ROOT_PASSWORD=root
20+
21+
# Django superuser (for development)
22+
DJANGO_SUPERUSER_USERNAME=admin
23+
DJANGO_SUPERUSER_EMAIL=admin@example.com
24+
DJANGO_SUPERUSER_PASSWORD=admin
25+
26+
# Python runtime flags
27+
PYTHONUNBUFFERED=1
28+
PYTHONDONTWRITEBYTECODE=1
29+
30+
# Timezone
31+
TZ=America/Mexico_City

‎.devcontainer/Dockerfile‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,11 @@
11
# =============================================================================
22
# CALLCENTER DJANGO API - DEVCONTAINER
33
# =============================================================================
4-
# Base image: Python 3.11 on Debian Bookworm
5-
# Includes: PostgreSQL client, MariaDB client, development tools
6-
# =============================================================================
7-
8-
FROM mcr.microsoft.com/devcontainers/python:3.11-bookworm
4+
# Base image: Python 3.12 on Debian Bookworm
5+
# Includes: PostgreSQL client, MariaDB client, development tools
6+
# =============================================================================
7+
8+
FROM mcr.microsoft.com/devcontainers/python:3.12-bookworm
99

1010
# =============================================================================
1111
# METADATA

‎.devcontainer/PROCEDIMIENTO.md‎

Lines changed: 77 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,77 @@
1+
# Procedimiento operativo del DevContainer
2+
3+
Este documento resume el flujo de ejecución del DevContainer en Linux (coexistente con Vagrant) y cómo se orquesta dentro de un pipeline CI/CD. Se incluyen diagramas PlantUML listos para generar vistas de flujo y de secuencia.
4+
5+
## ¿Cómo llamar al análisis inicial?
6+
Si necesitas un diagnóstico para entender "qué estamos haciendo" en el DevContainer y su pipeline, propón un **Análisis de Paridad Operativa DevContainer–CI/CD**. El objetivo es validar que los flujos locales (Codespaces/Vagrant), los hooks del contenedor y las etapas de CI usan las mismas variables, comandos y expectativas de cobertura.
7+
8+
## Paso a paso (Linux + Vagrant)
9+
1. **Preparar el host / Codespaces**
10+
- Dado que los hosts locales tienen **restricción de Docker**, usa GitHub Codespaces (Dev Containers en la nube). No es necesario instalar Docker Engine en tu máquina.
11+
- Si operas con Vagrant para las bases fuera de Codespaces, expón los puertos (p. ej., `15432` para PostgreSQL y `13306` para MariaDB) y consúmelos desde el contenedor remoto.
12+
- Copia `.devcontainer/.env.example` a `.devcontainer/.env` y ajusta credenciales/hosts.
13+
14+
2. **Inicializar el workspace**
15+
- Abre el repo en VS Code y selecciona "Reopen in Container".
16+
- `init_host.sh` valida estructura, scripts y genera `.env` si falta.
17+
18+
3. **Construir e iniciar el contenedor**
19+
- `on_create.sh` prepara el runtime (Python 3.12, Git) y `update_content.sh` instala dependencias.
20+
- `post_create.sh` aplica migraciones y crea el superusuario inicial.
21+
- `post_start.sh` corre chequeos rápidos (p. ej., `pytest -q` limitado) y registra versiones.
22+
23+
4. **Conectar a bases de datos**
24+
- Desde la app en el contenedor usa los hosts internos (`db_postgres`, `db_mariadb`).
25+
- Para usar Vagrant como origen, edita `.devcontainer/.env` con los puertos publicados y reinicia el contenedor; los servicios del compose pueden deshabilitarse comentando las secciones de DB si no se necesitan.
26+
27+
5. **Ciclo de desarrollo (TDD)**
28+
- Escribe tests antes del código, ejecuta `pytest --maxfail=1 --cov=.`.
29+
- Mantén cobertura ≥ 80% y refactoriza tras cada ciclo Red→Green→Refactor.
30+
31+
## Pipeline CI/CD recomendado
32+
1. **Trigger**: push o PR hacia ramas principales.
33+
2. **Jobs**:
34+
- **lint**: `flake8`/`ruff` y verificación de formato.
35+
- **test**: `pytest --cov` con servicios efímeros de Postgres/MariaDB (usando el mismo compose o contenedores dedicados).
36+
- **build**: imagen de aplicación (opcional si producción no usa Docker) + empaquetado de artefactos.
37+
- **deploy**: solo en ramas protegidas; reutiliza las mismas variables declaradas en `.devcontainer/.env.example` para paridad de entorno.
38+
3. **Gates**: el despliegue se habilita sólo si lint + tests + cobertura ≥ 80% pasan.
39+
40+
## Diagrama PlantUML - Flujo de lifecycle (actividad)
41+
```plantuml
42+
@startuml
43+
start
44+
:Init host (init_host.sh);
45+
if (Env file existe?) then (No)
46+
:Copiar .env.example a .env;
47+
endif
48+
:Build & create container (devcontainer.json);
49+
:Setup runtime (on_create.sh);
50+
:Instalar deps (update_content.sh);
51+
:Base de datos y migraciones (post_create.sh);
52+
:Smoke tests / versiones (post_start.sh);
53+
stop
54+
@enduml
55+
```
56+
57+
## Diagrama PlantUML - Ejecución CI/CD
58+
```plantuml
59+
@startuml
60+
actor Developer
61+
participant "GitHub Actions" as CI
62+
participant "Servicios DB" as DB
63+
64+
Developer -> CI: Push/PR
65+
CI -> DB: Levantar Postgres/MariaDB efímeros
66+
CI -> CI: Job lint (flake8/ruff)
67+
CI -> CI: Job tests (pytest --cov)
68+
CI -> CI: Calcular cobertura (gate ≥ 80%)
69+
CI -> CI: Job build (imagen/artefactos)
70+
CI -> Developer: Publicar resultados
71+
@enduml
72+
```
73+
74+
## Referencia rápida
75+
- Ejecuta los scripts manualmente desde `infrastructure/devcontainer/scripts/` si necesitas debug.
76+
- Los logs se almacenan en `infrastructure/devcontainer/logs/` (creados automáticamente).
77+
- Alinea las variables de `.devcontainer/.env` con las que usarás en CI y en producción sin contenedores para minimizar sorpresas.

‎.devcontainer/devcontainer.json‎

Lines changed: 2 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -40,21 +40,6 @@
4040
// ==========================================================================
4141

4242
"features": {
43-
// CPython Precompilado (Instalador Personalizado - SPEC_INFRA_001 Fase 3)
44-
// Para generar el artefacto: make build_cpython VERSION=3.12.6
45-
// Para desarrollo local: usa artifactUrl con path local
46-
// Para producción: usa GitHub Release URL
47-
"./infrastructure/cpython/installer": {
48-
"version": "3.12.6",
49-
// DESARROLLO LOCAL: Path relativo al workspace
50-
"artifactUrl": "/workspaces/${localWorkspaceFolderBasename}/infrastructure/cpython/artifacts/cpython-3.12.6-ubuntu20.04-build1.tgz",
51-
"checksumUrl": "/workspaces/${localWorkspaceFolderBasename}/infrastructure/cpython/artifacts/cpython-3.12.6-ubuntu20.04-build1.tgz.sha256",
52-
// PRODUCCIÓN: Descomentar cuando el Release esté publicado
53-
// "artifactUrl": "https://github.com/2-Coatl/IACT---project/releases/download/cpython-3.12.6-build1/cpython-3.12.6-ubuntu20.04-build1.tgz",
54-
// "checksumUrl": "https://github.com/2-Coatl/IACT---project/releases/download/cpython-3.12.6-build1/cpython-3.12.6-ubuntu20.04-build1.tgz.sha256",
55-
"installPrefix": "/opt/python",
56-
"skipValidation": false
57-
},
5843
"ghcr.io/devcontainers/features/git:1": {
5944
"version": "latest"
6045
},
@@ -102,8 +87,8 @@
10287

10388
// Settings
10489
"settings": {
105-
// Python - Apunta al CPython precompilado
106-
"python.defaultInterpreterPath": "/opt/python-3.12.6/bin/python3",
90+
// Python - intérprete provisto por la imagen base
91+
"python.defaultInterpreterPath": "/usr/local/bin/python3",
10792
"python.linting.enabled": true,
10893
"python.linting.pylintEnabled": false,
10994
"python.linting.flake8Enabled": true,

‎.devcontainer/docker_compose.yml‎

Lines changed: 61 additions & 63 deletions
Original file line numberDiff line numberDiff line change
@@ -33,45 +33,37 @@ services:
3333
# Persist pip cache
3434
- devcontainer-pip-cache:/home/vscode/.cache/pip
3535

36-
# Network
37-
networks:
38-
- callcenter-network
39-
40-
# Ports
41-
ports:
42-
- "8000:8000" # Django runserver
43-
44-
# Environment variables
45-
environment:
46-
# Django settings
47-
DJANGO_SETTINGS_MODULE: "callcentersite.settings.development"
48-
DEBUG: "True"
49-
50-
# PostgreSQL (default database)
51-
POSTGRES_HOST: db_postgres
52-
POSTGRES_PORT: 5432
53-
POSTGRES_DB: callcenter_db
54-
POSTGRES_USER: postgres
55-
POSTGRES_PASSWORD: postgres
56-
57-
# MariaDB (legacy database)
58-
MARIADB_HOST: db_mariadb
59-
MARIADB_PORT: 3306
60-
MARIADB_DATABASE: callcenter_legacy
61-
MARIADB_USER: root
62-
MARIADB_ROOT_PASSWORD: root
63-
64-
# Django superuser (for development)
65-
DJANGO_SUPERUSER_USERNAME: admin
66-
DJANGO_SUPERUSER_EMAIL: admin@example.com
67-
DJANGO_SUPERUSER_PASSWORD: admin
68-
69-
# Python
70-
PYTHONUNBUFFERED: 1
71-
PYTHONDONTWRITEBYTECODE: 1
72-
73-
# Timezone
74-
TZ: America/Mexico_City
36+
# Network
37+
networks:
38+
- callcenter-network
39+
40+
# Ports
41+
ports:
42+
- "8000:8000" # Django runserver
43+
44+
env_file:
45+
- .env
46+
47+
# Environment variables
48+
environment:
49+
DJANGO_SETTINGS_MODULE: ${DJANGO_SETTINGS_MODULE}
50+
DEBUG: ${DEBUG}
51+
POSTGRES_HOST: ${POSTGRES_HOST}
52+
POSTGRES_PORT: ${POSTGRES_PORT}
53+
POSTGRES_DB: ${POSTGRES_DB}
54+
POSTGRES_USER: ${POSTGRES_USER}
55+
POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
56+
MARIADB_HOST: ${MARIADB_HOST}
57+
MARIADB_PORT: ${MARIADB_PORT}
58+
MARIADB_DATABASE: ${MARIADB_DATABASE}
59+
MARIADB_USER: ${MARIADB_USER}
60+
MARIADB_ROOT_PASSWORD: ${MARIADB_ROOT_PASSWORD}
61+
DJANGO_SUPERUSER_USERNAME: ${DJANGO_SUPERUSER_USERNAME}
62+
DJANGO_SUPERUSER_EMAIL: ${DJANGO_SUPERUSER_EMAIL}
63+
DJANGO_SUPERUSER_PASSWORD: ${DJANGO_SUPERUSER_PASSWORD}
64+
PYTHONUNBUFFERED: ${PYTHONUNBUFFERED}
65+
PYTHONDONTWRITEBYTECODE: ${PYTHONDONTWRITEBYTECODE}
66+
TZ: ${TZ}
7567

7668
# Dependencies
7769
depends_on:
@@ -89,8 +81,8 @@ services:
8981
# ===========================================================================
9082
# POSTGRESQL SERVICE (Default Database)
9183
# ===========================================================================
92-
db_postgres:
93-
image: postgres:15-alpine
84+
db_postgres:
85+
image: postgres:15-alpine
9486

9587
container_name: callcenter-postgres
9688
hostname: db_postgres
@@ -111,16 +103,19 @@ services:
111103
- callcenter-network
112104

113105
# Ports (exposed for external tools)
114-
ports:
115-
- "5432:5432"
116-
117-
# Environment variables
118-
environment:
119-
POSTGRES_DB: callcenter_db
120-
POSTGRES_USER: postgres
121-
POSTGRES_PASSWORD: postgres
122-
POSTGRES_INITDB_ARGS: "--encoding=UTF8 --lc-collate=en_US.UTF-8 --lc-ctype=en_US.UTF-8"
123-
TZ: America/Mexico_City
106+
ports:
107+
- "5432:5432"
108+
109+
env_file:
110+
- .env
111+
112+
# Environment variables
113+
environment:
114+
POSTGRES_DB: ${POSTGRES_DB}
115+
POSTGRES_USER: ${POSTGRES_USER}
116+
POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
117+
POSTGRES_INITDB_ARGS: "--encoding=UTF8 --lc-collate=en_US.UTF-8 --lc-ctype=en_US.UTF-8"
118+
TZ: ${TZ}
124119

125120
# Health check
126121
healthcheck:
@@ -133,8 +128,8 @@ services:
133128
# ===========================================================================
134129
# MARIADB SERVICE (Legacy Database)
135130
# ===========================================================================
136-
db_mariadb:
137-
image: mariadb:10.11
131+
db_mariadb:
132+
image: mariadb:10.11
138133

139134
container_name: callcenter-mariadb
140135
hostname: db_mariadb
@@ -155,16 +150,19 @@ services:
155150
- callcenter-network
156151

157152
# Ports (exposed for external tools)
158-
ports:
159-
- "3306:3306"
160-
161-
# Environment variables
162-
environment:
163-
MARIADB_DATABASE: callcenter_legacy
164-
MARIADB_ROOT_PASSWORD: root
165-
MARIADB_CHARACTER_SET_SERVER: utf8mb4
166-
MARIADB_COLLATION_SERVER: utf8mb4_unicode_ci
167-
TZ: America/Mexico_City
153+
ports:
154+
- "3306:3306"
155+
156+
env_file:
157+
- .env
158+
159+
# Environment variables
160+
environment:
161+
MARIADB_DATABASE: ${MARIADB_DATABASE}
162+
MARIADB_ROOT_PASSWORD: ${MARIADB_ROOT_PASSWORD}
163+
MARIADB_CHARACTER_SET_SERVER: utf8mb4
164+
MARIADB_COLLATION_SERVER: utf8mb4_unicode_ci
165+
TZ: ${TZ}
168166

169167
# Command with custom settings
170168
command: >

‎api/callcentersite/requirements/test.txt‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -59,6 +59,7 @@ pytest-html>=4.1.1
5959
# ENVIRONMENT
6060
# ============================================
6161
python-dotenv>=1.0.0
62+
pyyaml>=6.0.0
6263

6364
mysql-connector-python
6465
psycopg2-binary

‎docs/devops/INDEX.md‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -11,9 +11,10 @@
1111

1212
- **automatizacion/** - Automatizacion CI/CD y planificacion
1313
- **backend/** - DevOps especifico backend
14-
- **frontend/** - DevOps especifico frontend
14+
- **frontend/** - DevOps especifico frontend
1515
- **git/** - Git workflows, estrategias y niveles
1616
- **infraestructura/** - Runbooks operacionales
17+
- **qa/** - Estrategia, análisis y evidencias de QA para DevOps
1718

1819
---
1920

@@ -30,6 +31,9 @@
3031
- [Frontend DevOps](frontend/) - CI/CD frontend
3132
- [Infraestructura](infraestructura/) - Runbooks y operaciones
3233

34+
### Calidad y QA
35+
- [QA DevOps](qa/) - Estrategia y análisis de calidad para pipelines y entornos
36+
3337
---
3438

3539
## Recursos

‎docs/devops/README.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -613,6 +613,14 @@ docs/devops/
613613
3. Configurar backups y DR
614614
4. Implementar logging centralizado
615615

616+
## QA y trazabilidad documental
617+
618+
- La estructura de QA replica el modelo de `docs/gobernanza/qa` para mantener consistencia documental.
619+
- Portada y metadatos: [`qa/README.md`](qa/README.md).
620+
- Índice y ubicaciones: [`qa/INDICE.md`](qa/INDICE.md).
621+
- Análisis vigente: [`qa/QA-ANALISIS-DEVCONTAINER-CODESPACES-SIN-DOCKER-001/`](qa/QA-ANALISIS-DEVCONTAINER-CODESPACES-SIN-DOCKER-001/).
622+
- Nuevos análisis deben usar el prefijo `QA-ANALISIS-*` y registrar evidencias dentro de su carpeta.
623+
616624
---
617625

618626
## Estado Actual

‎docs/devops/qa/INDICE.md‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
# Índice QA DevOps
2+
3+
Inventario de documentos, análisis y evidencias para QA en el dominio DevOps. La estructura replica el modelo de `docs/gobernanza/qa` para mantener consistencia documental.
4+
5+
## Estructura
6+
- `README.md` – portada del espacio y metadatos
7+
- `QA-ANALISIS-DEVCONTAINER-CODESPACES-SIN-DOCKER-001/` – análisis vigente
8+
- `analisis/QA-ANALISIS-PIPELINE-CI-CD-001/` – verificación integral de pipelines CI/CD
9+
- `analisis/` – recopilación planificada de nuevos análisis (prefijo `QA-ANALISIS-*`)
10+
- `registros/` – bitácoras y métricas de pipelines
11+
- `estrategia/` – criterios y umbrales de QA DevOps
12+
13+
## Navegación rápida
14+
- [Portada QA DevOps](README.md)
15+
- [Análisis DevContainer sin Docker en host](QA-ANALISIS-DEVCONTAINER-CODESPACES-SIN-DOCKER-001/)
16+
- [Análisis de pipeline CI/CD](analisis/QA-ANALISIS-PIPELINE-CI-CD-001/)
17+
- [Repositorio de scripts CI/CD](../README.md#scripts-principales)
18+
- [QA transversal en Gobernanza](../../gobernanza/qa/README.md)
19+
20+
## Próximos pasos
21+
- Completar `estrategia/` con criterios cuantificables y métricas de coverage.
22+
- Poblar `registros/` con resultados de pipelines y healthchecks.
23+
- Documentar nuevos análisis directamente en `analisis/` siguiendo la convención `QA-ANALISIS-*` con carpetas de evidencias.

0 commit comments

Comments
 (0)