Matriz de configuración y variables¶

Los nombres siguientes son los que reconoce el checkout actual. Los valores de secreto son siempre referencias env:NOMBRE; la columna "secreto" indica que el valor final no debe aparecer en .env.example, código, logs o tickets.

Aplicación, API y persistencia¶

Variable	Uso	Default seguro	Secreto
APP_ENV	entorno mostrado por API	development	no
APP_NAME	nombre del servicio	SchemaSafe NoSQL	no
CONNECTION_PROFILE	fixture, local o secure	fixture	no
BACKEND_HOST / BACKEND_PORT	bind local de Uvicorn	0.0.0.0 / 8000	no
FRONTEND_PORT / FRONTEND_ORIGIN	bind/origen del navegador	5173 / http://localhost:5173	no
VITE_API_BASE_URL	URL de API compilada en frontend	http://localhost:8000	no
DATABASE_PATH	SQLite demo	data/schemasafe.db	no
DATABASE_URL_REF	referencia de URL PostgreSQL	vacío (SQLite)	referencia
SCHEMASAFE_DATABASE_URL_REF	referencia documentada para scripts OPS-03	env:SCHEMASAFE_DATABASE_URL	referencia
AUDIT_RETENTION_DAYS	retención lógica de auditoría	90	no
REPORT_RETENTION_DAYS	retención lógica de reportes	90	no
AUTH_SIGNING_KEY_REF	referencia de firma HMAC	vacío en fixture	referencia
SCHEMASAFE_AUTH_SIGNING_KEY	valor resuelto de la firma	vacío en ejemplo	sí
AUTH_ISSUER / AUTH_AUDIENCE	claims obligatorios del token	schemasafe-local / schemasafe-api	no
VITE_AUTH_TOKEN	token corto para demo del frontend	vacío	sí
VITE_PROJECT_ID	proyecto inicial de la UI	default	no
RATE_LIMIT_ENABLED	activa límite por cliente para el API público	false	no
RATE_LIMIT_REQUESTS	solicitudes por ventana y cliente	120; 1–10000	no
RATE_LIMIT_WINDOW_SECONDS	duración de la ventana del límite	60; 1–3600	no

Puertos publicados por Docker¶

Variable	Uso	Default
SCHEMASAFE_BACKEND_PORT	backend del perfil app	8000
SCHEMASAFE_FRONTEND_PORT	frontend del perfil app	5173
SCHEMASAFE_MONGODB_PORT	MongoDB del perfil de integración	27017
SCHEMASAFE_POSTGRES_PORT	PostgreSQL del perfil app/postgres	5432

Los puertos publicados de CouchDB (5984) y Cassandra (9042) están fijados por el perfil de integración actual y no tienen variables SCHEMASAFE_* de override. Los defaults de usuario/base/contraseña de Compose son únicamente para pruebas locales sintéticas; un entorno compartido debe sustituirlos por referencias externas.

MongoDB¶

Variable	Uso	Default/límite	Secreto
MONGODB_URI_REF	URI live	vacío	referencia
MONGODB_DATABASE	limitar base descubierta	vacío	no
MONGODB_TLS_ENABLED / MONGODB_TLS_CA_FILE	TLS y CA	false / vacío	ruta opcional
MONGODB_TIMEOUT_MS	timeout de cliente	1000 ms	no
MONGODB_MAX_DOCUMENTS	máximo de muestra	1000	no

CouchDB¶

Variable	Uso	Default/límite	Secreto
COUCHDB_URL	endpoint live	vacío; https:// en secure	no
COUCHDB_DATABASE	limitar base	vacío	no
COUCHDB_USERNAME_REF / COUCHDB_PASSWORD_REF	credenciales separadas	vacío	referencias
COUCHDB_TLS_VERIFY / COUCHDB_TLS_CA_FILE	verificación y CA	true / vacío	ruta opcional
COUCHDB_TIMEOUT_MS	timeout HTTP	1000 ms; 100–60000	no
COUCHDB_MAX_DOCUMENTS	máximo de documentos	1000	no
COUCHDB_PAGE_SIZE	tamaño de página Mango	100	no

Cassandra¶

Variable	Uso	Default/límite	Secreto
CASSANDRA_CONTACT_POINTS	hosts live	vacío	no
CASSANDRA_PORT	puerto CQL	9042	no
CASSANDRA_KEYSPACE	scope de discovery	vacío	no
CASSANDRA_USERNAME_REF / CASSANDRA_PASSWORD_REF	credenciales	vacío	referencias
CASSANDRA_TLS_ENABLED / CASSANDRA_TLS_CA_FILE	TLS y CA	false / vacío	ruta opcional
CASSANDRA_TIMEOUT_MS	timeout del driver	1000 ms	no
CASSANDRA_MAX_COLUMNS	límite de metadata	200; 1–10000	no

OPS-03¶

Variable	Uso	Regla
SCHEMASAFE_BACKUP_PASSPHRASE_REF	referencia documentada de passphrase	no contiene el valor
SCHEMASAFE_BACKUP_PASSPHRASE	passphrase efectiva del script	solo entorno/gestor; nunca CLI/log
SCHEMASAFE_BACKUP_DIR	destino sugerido	backups, fuera de Git/volúmenes

El checker de documentación compara esta matriz con .env.example para que una variable nueva no quede sin explicación. Las variables SCHEMASAFE_DOCKER_*, SCHEMASAFE_POSTGRES_* y SCHEMASAFE_*_INTEGRATION_* usadas solo por Compose o CI deben permanecer documentadas junto al workflow/runbook que las consume.