🏗️ Arquitectura de Containerización - Índice Maestro¶
Versión: 2.0 Última actualización: 2025-10-04 Sistema de numeración: 4 Capas (00-09, 10-19, 20-89, 90-99)
🔍 Navegación Rápida¶
🧱 Capa 0: Fundamentos (00-09)¶
Componentes reutilizables y patrones base.
| Código | Carpeta | Propósito | Contenido Principal |
|---|---|---|---|
| 00 | templates | Dockerfiles reutilizables | Base, Build, Dev, Test |
| 01 | patterns | Patrones arquitectónicos | Network, Volumes, Composition |
| 02 | strategies | Documentación estratégica | Dockerfile, Registry, Security |
| 03 | configurations | Configs base | Compose templates, .env files |
🔧 Capa 1: Herramientas (10-19)¶
Tooling para desarrollo y operaciones.
| Código | Carpeta | Propósito | Contenido Principal |
|---|---|---|---|
| 10 | devtools | Desarrollo local | DevContainer, Vagrant, Local Testing |
| 11 | registry_tools | Gestión de imágenes | Push, Tag, Cleanup scripts |
| 12 | debugging | Troubleshooting | Tools, Debugging guides |
| 13 | automation | Scripts útiles | Health, Backup, Monitoring, Deploy |
🚀 Capa 2: Servicios (20-89)¶
Servicios concretos organizados por dominio.
| Código | Categoría | Propósito | Servicios Disponibles | Puertos |
|---|---|---|---|---|
| 20 | documentation_services | Docs & APIs | MkDocs, Swagger, Storybook | 8000, 8080, 6006 |
| 30 | data_services | Bases de datos | PostgreSQL, Redis, Elasticsearch, MongoDB | 5432, 6379, 9200, 27017 |
| 40 | messaging_services | Mensajería | RabbitMQ, Kafka, NATS | 5672, 9092, 4222 |
| 50 | monitoring_services | Observabilidad | Prometheus, Grafana, Loki, Jaeger | 9090, 3000, 3100, 16686 |
| 60 | media_services | Multimedia | FossFlow, Image processor, Video transcoder | 8080, - , - |
| 70 | build_services | Artefactos | Nexus, Artifactory, Registry | 8081, 8082, 5000 |
| 80 | search_services | Búsqueda | Typesense, Meilisearch, Algolia proxy | 8108, 7700, - |
🎭 Capa 3: Orquestación (90-99)¶
Composición de stacks y gestión centralizada.
| Código | Stack | Propósito | Servicios Incluidos | Uso |
|---|---|---|---|---|
| 90_00 | development_stack | Stack completo dev | Todos los servicios en modo desarrollo | Desarrollo local completo |
| 90_01 | production_stack | Stack optimizado | Servicios críticos para producción | Deploy a producción |
| 90_02 | testing_stack | Stack para CI/CD | Servicios necesarios para testing | Pipelines de CI/CD |
| 90_03 | minimal_stack | Stack mínimo | Solo servicios esenciales | Quick start / demos |
| 90_99 | management | Gestión central | Scripts de orquestación | Administración del sistema |
🔎 Cómo Navegar¶
🎯 Por Función¶
¿Necesitas PostgreSQL?
¿Necesitas un Dockerfile base?
¿Quieres levantar todo el sistema?
→ Capa 3 (Orquestación)
→ Stack 90_00 (Development)
→ 03_05_90_orchestration/03_05_90_00_development_stack/
🔍 Por Patrón de Uso¶
Desarrollo Local¶
- Setup inicial:
03_05_10_devtools/03_05_10_00_devcontainer/ - Levantar servicios:
03_05_90_orchestration/03_05_90_00_development_stack/ - Debugging:
03_05_12_debugging/
Nuevo Servicio¶
- Template base:
03_05_00_templates/03_05_00_00_base/ - Patrones de red:
03_05_01_patterns/03_05_01_00_networking/ - Compose template:
03_05_03_configurations/03_05_03_00_compose_templates/
Deployment a Producción¶
- Build image:
03_05_11_registry_tools/ - Production stack:
03_05_90_orchestration/03_05_90_01_production_stack/ - Monitoring:
03_05_50_monitoring_services/
📐 Convenciones de Numeración¶
Sistema de 4 Capas¶
| Rango | Capa | Propósito | Ejemplos |
|---|---|---|---|
| 00-09 | Fundamentos | Componentes reutilizables y abstractos | Templates, Patterns, Strategies |
| 10-19 | Herramientas | Tooling de soporte | DevTools, Registry, Debugging, Automation |
| 20-89 | Servicios | Servicios concretos por dominio | Documentation, Data, Messaging, Monitoring |
| 90-99 | Orquestación | Composición y gestión | Development Stack, Production Stack |
Nomenclatura de Servicios¶
Ejemplo:
🎯 Reglas de Oro¶
1. Single Source of Truth¶
Cada servicio vive en UNA carpeta canónica. Los stacks componen servicios mediante extends, no los duplican.
✅ Correcto:
# 03_05_90_00_development_stack/docker-compose.yml
services:
postgres:
extends:
file: ../../03_05_30_data_services/03_05_30_00_postgres/docker-compose.yml
service: postgres
❌ Incorrecto:
# Duplicar definición del servicio
services:
postgres:
image: postgres:15
# ... configuración duplicada
2. Extends Pattern¶
Los stacks de orquestación extienden servicios base, no los redefinen.
3. Semantic Naming¶
El número indica claramente la función:
- 00-09: Base/Foundation
- 10-19: Tools
- 20-89: Services (agrupados por dominio)
- 90-99: Orchestration
4. No Mixing Layers¶
- Templates (Capa 0) NO incluyen servicios
- Servicios (Capa 2) NO incluyen orquestación
- Orquestación (Capa 3) NO duplica definiciones
5. Layer Dependencies¶
Capa 3 (Orchestration)
↓ depends on
Capa 2 (Services)
↓ depends on
Capa 1 (Tools) & Capa 0 (Foundation)
📊 Mapa Visual¶
03_05_containerization/
│
├─ 🧱 CAPA 0: FUNDAMENTOS (00-09)
│ ├─ 00_templates/ ← Dockerfiles base
│ ├─ 01_patterns/ ← Patrones arquitectónicos
│ ├─ 02_strategies/ ← Documentación estratégica
│ └─ 03_configurations/ ← Configs reutilizables
│
├─ 🔧 CAPA 1: HERRAMIENTAS (10-19)
│ ├─ 10_devtools/ ← DevContainer, Vagrant
│ ├─ 11_registry_tools/ ← Build, Push, Cleanup
│ ├─ 12_debugging/ ← Troubleshooting
│ └─ 13_automation/ ← Health, Backup, Deploy
│
├─ 🚀 CAPA 2: SERVICIOS (20-89)
│ ├─ 20_documentation_services/ ← MkDocs, Swagger
│ ├─ 30_data_services/ ← PostgreSQL, Redis
│ ├─ 40_messaging_services/ ← RabbitMQ, Kafka
│ ├─ 50_monitoring_services/ ← Prometheus, Grafana
│ ├─ 60_media_services/ ← FossFlow, Image processor
│ ├─ 70_build_services/ ← Nexus, Registry
│ └─ 80_search_services/ ← Typesense, Meilisearch
│
└─ 🎭 CAPA 3: ORQUESTACIÓN (90-99)
└─ 90_orchestration/
├─ 90_00_development_stack/ ← Full dev environment
├─ 90_01_production_stack/ ← Optimized production
├─ 90_02_testing_stack/ ← CI/CD testing
├─ 90_03_minimal_stack/ ← Essential services only
└─ 90_99_management/ ← Central management scripts
🚀 Quick Start Examples¶
Ejemplo 1: Levantar Stack de Desarrollo¶
cd 03_05_90_orchestration/03_05_90_00_development_stack
docker-compose up -d
# Servicios disponibles:
# - MkDocs: http://localhost:8000
# - PostgreSQL: localhost:5432
# - Grafana: http://localhost:3000
Ejemplo 2: Crear Nuevo Servicio¶
# 1. Copiar template base
cp 03_05_00_templates/03_05_00_00_base/Dockerfile.alpine \
03_05_30_data_services/03_05_30_04_mydb/Dockerfile
# 2. Adaptar configuración
cd 03_05_30_data_services/03_05_30_04_mydb
nano Dockerfile
# 3. Crear docker-compose.yml
nano docker-compose.yml
# 4. Agregar al stack de desarrollo
cd ../../03_05_90_orchestration/03_05_90_00_development_stack
# Editar docker-compose.yml para extender el nuevo servicio
Ejemplo 3: Build y Push de Imagen¶
cd 03_05_11_registry_tools
./build_push.ps1 -Service mkdocs -Tag v2.0.0 -Registry audiolab.local:5000
📚 Recursos Adicionales¶
Documentación por Capa¶
- Capa 0: Ver READMEs en cada subcarpeta de
03_05_00_templates/ - Capa 1: Guías en
03_05_12_debugging/03_05_12_01_guides/ - Capa 2: Cada servicio tiene su propio README con configuración
- Capa 3: Cada stack incluye QUICK_START.md
Estrategias y Best Practices¶
Consultar 03_05_02_strategies/ para:
- Dockerfile optimization
- Registry management
- Security guidelines
- Performance tuning
Troubleshooting¶
Si algo falla:
1. Revisar 03_05_12_debugging/03_05_12_01_guides/COMMON_ISSUES.md
2. Usar herramientas en 03_05_12_debugging/03_05_12_00_tools/
3. Consultar logs con docker-compose logs -f [service]
🔄 Migración desde Estructura Antigua¶
Si vienes de la estructura 03_06_XX, consultar:
- BACKUPS/containerization_migration_20251004/ANALYSIS_REPORT.md
- Mapeo de migración en el backup
🎯 Próximos Pasos¶
- ✅ Estructura de carpetas creada
- ⏳ Migrar archivos existentes a nueva estructura
- ⏳ Crear stacks de orquestación
- ⏳ Configurar CI/CD
- ⏳ Documentar servicios individuales
Mantenido por: AudioLab Infrastructure Team Contacto: See repository maintainers Versión de este índice: 2.0