Configuration

Configuration — capas de configuración (no secreta) usadas por la plataforma. ↓ Environments · ⬆ Documentación AITHA

This document describes the configuration layers used by the platform.

Configuration Layers

Base topology (non-secret)

Files:

• deployment/topology.env.template (tracked)
• deployment/topology.env (generated)

Defines stable host ports and local URLs used by project .env templates and (when applicable) remote deployment.

It also defines shared non-secret topology defaults such as PUBLIC_BASE_DOMAIN.

Global config (non-secret)

File: .env (generated from .env.template)

Global orchestration settings shared by projects (network name, internal service URLs, global defaults).

This is also where shared public service URLs such as CHATWOOT_PUBLIC_URL and ZITADEL_PUBLIC_URL live.

Global secrets

Local dev file: .env.secrets (generated from .env.secrets.example)

Passwords/tokens used across projects for local development.

For remote servers, prefer Ansible Vault (core2_env_secrets) and let remote deploy render the server-side .env.secrets during deployment.

Project templates and generated env

Files:

• */.env.template or */.env.example (tracked)
• */.env (generated)

Project .env files are generated by ./infra env generate by merging topology + .env + .env.secrets into each project template.

Remote deployment configuration

File: deployment/remote.env (tracked)

Defines remote-only knobs and the public endpoint registry (REMOTE_ENDPOINT_DOMAIN_*, REMOTE_ENDPOINT_PORT_*, etc.).

Remote endpoint domains should reuse PUBLIC_BASE_DOMAIN from deployment/topology.env or shared public URLs from .env when a service already exposes its canonical public hostname there.

El portal se sirve en dos hostnames

Un solo contenedor (platform/portal), dos endpoints:

Endpoint	Host	Qué sirve
PORTAL	nex.<dominio>	Host canónico: NEXTAUTH_URL/PORTAL_URL, login, dashboard, iframes
PORTAL_ENTRY	portal.<dominio>	Solo la portada de acceso (/, EntryView)

middleware.ts reenvía al host canónico cualquier ruta distinta de / que llegue por el host de entrada: la sesión vive en las cookies de nex.<dominio> y no se comparte entre subdominios. Con PORTAL_ENTRY_URL vacío o igual a PORTAL_URL el reenvío se desactiva — es lo correcto en local, donde ambos son localhost.

Las redirect_uris de Zitadel se generan desde {{PORTAL_URL}} (security/zitadel/bootstrap.json), así que al cambiar estos hosts hay que re-correr el bootstrap de Zitadel o el login queda con la URI vieja.

Notes

• The shared Docker network name is DOCKER_NETWORK_NAME (root .env).
• Avoid editing generated */.env by hand; change deployment/topology.env, .env, .env.secrets or the relevant */.env.template instead.