Instalación y configuración¶

Esta guía le acompaña a través de la instalación de Turbo EA con Docker, la configuración del entorno, la carga de datos de demostración y el inicio de servicios opcionales como sugerencias de IA y el servidor MCP.

Requisitos previos¶

Docker (v20.10+)
Docker Compose (v2.0+)

Aproximadamente 2 GB de espacio libre en disco, unos minutos de ancho de banda para el primer pull de imágenes y los puertos 8920 (HTTP) y opcionalmente 9443 (HTTPS) libres en el host.

Paso 1: Obtener la configuración¶

Necesita docker-compose.yml y un archivo .env configurado en un directorio de trabajo. La forma más sencilla es clonar el repositorio:

git clone https://github.com/vincentmakes/turbo-ea.git
cd turbo-ea
cp .env.example .env

Abra .env y establezca los dos valores obligatorios:

# Credenciales de PostgreSQL (utilizadas por el contenedor de base de datos integrado).
# Elija una contraseña fuerte — persiste en el volumen integrado.
POSTGRES_PASSWORD=choose-a-strong-password

# Clave de firma JWT. Genere una con:
#   python3 -c "import secrets; print(secrets.token_urlsafe(64))"
SECRET_KEY=your-generated-secret

Todo lo demás en .env.example tiene valores predeterminados razonables.

Note

El backend se niega a iniciarse con el SECRET_KEY de ejemplo fuera del entorno de desarrollo. Genere uno real antes de continuar.

Paso 2: Pull y arranque¶

El stack integrado (Postgres + backend + frontend + nginx perimetral) se ejecuta desde imágenes multi-arquitectura precompiladas en GHCR — no se requiere compilación local:

docker compose pull
docker compose up -d

Abra http://localhost:8920 y registre el primer usuario. El primer usuario registrado se promueve automáticamente a Admin.

Para cambiar el puerto del host, establezca HOST_PORT en .env (predeterminado 8920). La terminación HTTPS directa se trata en el Paso 5.

Paso 3: Cargar datos de demostración (opcional)¶

Turbo EA puede iniciarse vacío (solo el metamodelo integrado) o con el conjunto de datos de demostración NexaTech Industries, ideal para evaluación, formación y exploración de funciones.

Establezca el flag de seed en .env antes del primer arranque:

SEED_DEMO=true

Luego docker compose up -d (si ya ha arrancado, consulte «Restablecer y volver a sembrar» más abajo).

Opciones de carga¶

Variable	Predeterminado	Descripción
`SEED_DEMO`	`false`	Carga el conjunto completo de NexaTech Industries, incluidos datos BPM y PPM
`SEED_BPM`	`false`	Carga solo procesos BPM de demostración (subconjunto de `SEED_DEMO`)
`SEED_PPM`	`false`	Carga solo datos de proyectos PPM (subconjunto de `SEED_DEMO`)
`RESET_DB`	`false`	Elimina todas las tablas y las recrea desde cero al iniciar

SEED_DEMO=true ya incluye datos BPM y PPM — no es necesario establecer los flags de subconjunto por separado.

Cuenta de administrador de demostración¶

Cuando se cargan los datos de demostración, se crea una cuenta de administrador predeterminada:

Campo	Valor
Email	`admin@turboea.demo`
Contraseña	`TurboEA!2025`
Rol	Admin

Warning

La cuenta de administrador de demostración utiliza credenciales conocidas y públicas. Cambie la contraseña — o cree su propia cuenta de administrador y deshabilite ésta — para cualquier entorno más allá de la evaluación local.

Qué incluye la demostración¶

Aproximadamente 150 cards a través de las cuatro capas de arquitectura, además de relaciones, etiquetas, comentarios, tareas, diagramas BPM, datos PPM, ADR y un Statement of Architecture Work:

Núcleo EA — Organizaciones, ~20 Capacidades de Negocio, Contextos de Negocio, ~15 Aplicaciones, ~20 Componentes IT, Interfaces, Objetos de Datos, Plataformas, Objetivos, 6 Iniciativas, 5 grupos de etiquetas, 60+ relaciones.
BPM — ~30 procesos de negocio en una jerarquía de 4 niveles con diagramas BPMN 2.0, vínculos elemento-a-card y evaluaciones de procesos.
PPM — Informes de estado, Work Breakdown Structures, ~60 tareas, líneas de presupuesto y coste, y un registro de riesgos sobre las 6 Iniciativas de demostración.
EA Delivery — Architecture Decision Records y Statements of Architecture Work.

Restablecer y volver a sembrar¶

Para borrar la base de datos y empezar de nuevo:

RESET_DB=true
SEED_DEMO=true

Reinicie el stack, luego elimine RESET_DB=true de .env — dejarlo establecido restablecerá la base de datos en cada reinicio:

docker compose up -d
# Verifique que los nuevos datos están ahí, luego edite .env para eliminar RESET_DB

Paso 4: Servicios opcionales (perfiles de Compose)¶

Ambos complementos son opcionales mediante perfiles de Docker Compose y se ejecutan junto al stack principal sin perturbarlo.

Sugerencias de descripción con IA¶

Genere descripciones de cards con un LLM local (Ollama integrado) o un proveedor comercial. El contenedor Ollama integrado es la vía más sencilla para configuraciones autohospedadas.

Añada a .env:

AI_PROVIDER_URL=http://ollama:11434
AI_MODEL=gemma3:4b
AI_AUTO_CONFIGURE=true

Inicie con el perfil ai:

docker compose --profile ai up -d

El modelo se descarga automáticamente en el primer arranque (unos minutos, dependiendo de su conexión). Consulte Capacidades de IA para la referencia completa de configuración, incluido cómo usar OpenAI / Gemini / Claude / DeepSeek en lugar del Ollama integrado.

Servidor MCP¶

El servidor MCP permite que herramientas de IA — Claude Desktop, Cursor, GitHub Copilot y otras — consulten sus datos EA mediante el Model Context Protocol con RBAC por usuario. Es de solo lectura.

docker compose --profile mcp up -d

Consulte Integración MCP para la configuración OAuth y los detalles de las herramientas.

Ambos a la vez¶

docker compose --profile ai --profile mcp up -d

Paso 5: HTTPS directo (opcional)¶

El nginx perimetral integrado puede terminar TLS por sí mismo — útil si no dispone de un proxy inverso externo. Añada a .env:

TURBO_EA_TLS_ENABLED=true
TLS_CERTS_DIR=./certs
TURBO_EA_TLS_CERT_FILE=cert.pem
TURBO_EA_TLS_KEY_FILE=key.pem
HOST_PORT=80
TLS_HOST_PORT=443

Coloque cert.pem y key.pem en ./certs/ (el directorio se monta en modo solo lectura dentro del contenedor de nginx). La imagen deriva server_name y el esquema reenviado de TURBO_EA_PUBLIC_URL, sirve HTTP y HTTPS, y redirige HTTP a HTTPS automáticamente.

Para configuraciones detrás de un proxy inverso existente (Caddy, Traefik, Cloudflare Tunnel), deje TURBO_EA_TLS_ENABLED=false y deje que el proxy gestione TLS.

Anclar una versión¶

docker compose pull toma :latest por defecto. Para anclar a una versión específica en producción, establezca TURBO_EA_TAG:

TURBO_EA_TAG=1.0.0 docker compose up -d

Las versiones publicadas se etiquetan como :<full-version>, :<major>.<minor>, :<major> y :latest. El workflow de publicación excluye las prereleases (-rc.N) de :latest y de las etiquetas cortas :X.Y / :X. Consulte Publicaciones para el árbol completo de etiquetas y la política del canal de prelanzamiento.

Usar un PostgreSQL existente¶

Si ya ejecuta una instancia de PostgreSQL gestionada o compartida, apunte el backend a ella y prescinda del servicio db integrado.

Cree la base de datos y el usuario en su servidor existente:

CREATE USER turboea WITH PASSWORD 'your-password';
CREATE DATABASE turboea OWNER turboea;

Sobreescriba las variables de conexión en .env:

POSTGRES_HOST=your-postgres-host
POSTGRES_PORT=5432
POSTGRES_DB=turboea
POSTGRES_USER=turboea
POSTGRES_PASSWORD=your-password

Luego inicie como de costumbre: docker compose up -d. El servicio db integrado sigue definido en docker-compose.yml; puede dejarlo en reposo o detenerlo explícitamente.

Verificar imágenes¶

Desde 1.0.0 cada imagen publicada está firmada con cosign keyless OIDC y se distribuye con una SBOM SPDX generada por buildkit. Consulte Cadena de suministro para el comando de verificación y cómo obtener la SBOM desde el registry.

Desarrollo desde el código fuente¶

Si desea construir el stack desde el código fuente (modificando código de backend o frontend), use la sobrescritura de Compose para desarrollo:

docker compose -f docker-compose.yml -f dev/docker-compose.dev.yml up -d --build

O el target de conveniencia:

make up-dev

La guía completa para desarrolladores — nomenclatura de ramas, comandos de lint y pruebas, comprobaciones pre-commit — está en CONTRIBUTING.md.

Referencia rápida¶

Escenario	Comando
Primer arranque (datos vacíos)	`docker compose pull && docker compose up -d`
Primer arranque con datos de demostración	Establezca `SEED_DEMO=true` en `.env`, luego el mismo comando
Añadir sugerencias de IA	Añada variables IA, luego `docker compose --profile ai up -d`
Añadir servidor MCP	`docker compose --profile mcp up -d`
Anclar una versión	`TURBO_EA_TAG=1.0.0 docker compose up -d`
Restablecer y volver a sembrar	`RESET_DB=true` + `SEED_DEMO=true`, reinicie, luego elimine `RESET_DB`
Usar Postgres externo	Sobrescriba variables `POSTGRES_*` en `.env`, luego `docker compose up -d`
Construir desde código fuente	`make up-dev`

Próximos pasos¶

Abra http://localhost:8920 (o su HOST_PORT configurado) e inicie sesión. Si cargó datos de demostración, use admin@turboea.demo / TurboEA!2025. De lo contrario, regístrese — el primer usuario se promueve automáticamente a Admin.
Explore el Dashboard para una vista general de su panorama EA.
Personalice tipos de cards y campos — el metamodelo está totalmente basado en datos, sin cambios de código.
Para despliegues productivos, revise Política de compatibilidad y Cadena de suministro.