Environment variables reference for all services

Módulo Horario is configured entirely through environment variables. Each service reads its configuration at startup and will fail immediately if any required variable is missing. For local development, copy services/.env.example to services/.env and fill in the values. For production, use AWS Secrets Manager or HashiCorp Vault — never commit .env files to version control.

The root services/.env file provides shared variables (database passwords, shared secrets) that Docker Compose injects into each service. Service-level .env.example files show the full variable set for each individual service.

Shared variables (root `.env`)

These variables are defined once in services/.env and referenced by docker-compose.yml across multiple services.

Variable	Required	Description
`MYSQL_ROOT_PASSWORD`	Yes	Root password for the MySQL container. Used by `usuarios-service` and `aulas-service`.
`MYSQL_DATABASE`	Yes	Default MySQL database name. Set to `docentes_db`.
`POSTGRES_USER`	Yes	PostgreSQL username. Used by `horario-service` and `materias-service`.
`POSTGRES_PASSWORD`	Yes	PostgreSQL password.
`POSTGRES_DB`	Yes	Default PostgreSQL database name. Set to `postgres`.
`JWT_SECRET`	Yes	Secret key for signing and verifying JWT tokens. Generate with `openssl rand -hex 32`.
`ADMIN_CREATION_KEY`	Yes	Key required in the `X-Admin-Key` header to create admin accounts. Generate with `openssl rand -hex 16`.
`INTERNAL_API_KEY`	Yes	Shared key used for authenticated inter-service HTTP calls. Generate with `openssl rand -hex 16`.
`CORS_ALLOW_ORIGINS`	Yes	Comma-separated list of allowed CORS origins. Restrict to actual domains in production.

Service variables

usuarios-service (port 8001)

usuarios-service manages user accounts, authentication, and JWT issuance. It connects to MySQL.

Variable	Type	Required	Default	Description
`APP_PORT`	integer	No	`8001`	Port the service binds to.
`DATABASE_URL`	string	Yes	—	MySQL connection string. Format: `mysql+pymysql://user:password@host:port/database`
`JWT_SECRET`	string	Yes	—	Secret key for HS256 JWT signing. Must match across any service that verifies tokens.
`ADMIN_CREATION_KEY`	string	Yes	—	Key checked by `POST /auth/register-admin` via the `X-Admin-Key` header.
`INTERNAL_API_KEY`	string	Yes	—	Key used to authenticate incoming requests from other services.
`CORS_ALLOW_ORIGINS`	string	Yes	—	Comma-separated list of origins permitted by the CORS middleware.

Example (usuarios-service/.env.example):

APP_PORT=8001
DATABASE_URL=mysql+pymysql://usuario:password@localhost:3307/docentes_db
JWT_SECRET=cambia_esta_clave
ADMIN_CREATION_KEY=clave_admin_segura
INTERNAL_API_KEY=horarios-internal-key
CORS_ALLOW_ORIGINS=http://localhost:5173,http://localhost:8001,http://localhost:8002,http://localhost:8003,http://localhost:8004

Docker Compose injection:

usuarios-service:
  environment:
    DATABASE_URL: mysql+pymysql://root:${MYSQL_ROOT_PASSWORD}@mysql/docentes_db
    JWT_SECRET: ${JWT_SECRET}
    ADMIN_CREATION_KEY: ${ADMIN_CREATION_KEY}
    INTERNAL_API_KEY: ${INTERNAL_API_KEY}
    CORS_ALLOW_ORIGINS: ${CORS_ALLOW_ORIGINS}
    APP_PORT: 8001

horario-service (port 8004)

horario-service manages academic schedules and depends on all three other services for docente, materia, and aula data. It connects to PostgreSQL.

Variable	Type	Required	Default	Description
`APP_PORT`	integer	No	`8004`	Port the service binds to.
`APP_NAME`	string	No	`Horario Service`	Application name shown in logs and error responses.
`DATABASE_URL`	string	Yes	—	PostgreSQL connection string. Format: `postgresql://user:password@host:port/database`
`USUARIOS_SERVICE_URL`	string	Yes	—	Base URL of `usuarios-service` for docente lookups and token verification.
`MATERIAS_SERVICE_URL`	string	Yes	—	Base URL of `materias-service` for subject lookups.
`AULAS_SERVICE_URL`	string	Yes	—	Base URL of `aulas-service` for classroom lookups.
`INTERNAL_API_KEY`	string	Yes	—	Key sent in outgoing inter-service requests. Must match the key expected by other services.
`UPSTREAM_TIMEOUT_SECONDS`	integer	No	`5`	Timeout in seconds for HTTP calls to upstream services.
`CORS_ALLOW_ORIGINS`	string	Yes	—	Comma-separated list of allowed CORS origins.

Example (horario-service/.env.example):

APP_PORT=8004
DATABASE_URL=postgresql://usuario:password@localhost:5433/horarios_db
APP_NAME="Horario Service"
USUARIOS_SERVICE_URL=http://localhost:8001
MATERIAS_SERVICE_URL=http://localhost:8002
AULAS_SERVICE_URL=http://localhost:8003
INTERNAL_API_KEY=horarios-internal-key
UPSTREAM_TIMEOUT_SECONDS=5
CORS_ALLOW_ORIGINS=http://localhost:5173,http://localhost:8001,http://localhost:8002,http://localhost:8003,http://localhost:8004

Docker Compose injection:

horario-service:
  environment:
    DATABASE_URL: postgresql://${POSTGRES_USER}:${POSTGRES_PASSWORD}@postgres:5432/horarios_db
    APP_NAME: Horario Service
    APP_PORT: 8004
    USUARIOS_SERVICE_URL: http://usuarios-service:8001
    MATERIAS_SERVICE_URL: http://materias-service:8002
    AULAS_SERVICE_URL: http://aulas-service:8003
    INTERNAL_API_KEY: ${INTERNAL_API_KEY}
    CORS_ALLOW_ORIGINS: ${CORS_ALLOW_ORIGINS}
    UPSTREAM_TIMEOUT_SECONDS: 5

materias-service (port 8002)

materias-service manages academic subjects. It connects to PostgreSQL and delegates authentication to usuarios-service.

Variable	Type	Required	Default	Description
`APP_PORT`	integer	No	`8002`	Port the service binds to.
`DATABASE_URL`	string	Yes	—	PostgreSQL async connection string. Format: `postgresql+asyncpg://user:password@host:port/database`
`USUARIOS_SERVICE_URL`	string	Yes	—	Base URL of `usuarios-service` used to validate tokens on protected routes.
`UPSTREAM_TIMEOUT_SECONDS`	integer	No	`5`	Timeout in seconds for calls to `usuarios-service`.
`CORS_ALLOW_ORIGINS`	string	Yes	—	Comma-separated list of allowed CORS origins.

Docker Compose injection:

materias-service:
  environment:
    DATABASE_URL: postgresql+asyncpg://${POSTGRES_USER}:${POSTGRES_PASSWORD}@postgres:5432/materias_db
    USUARIOS_SERVICE_URL: http://usuarios-service:8001
    UPSTREAM_TIMEOUT_SECONDS: 5
    CORS_ALLOW_ORIGINS: ${CORS_ALLOW_ORIGINS}
    APP_PORT: 8002

aulas-service (port 8003)

aulas-service manages classrooms. It connects to MySQL and delegates authentication to usuarios-service.

Variable	Type	Required	Default	Description
`APP_PORT`	integer	No	`8003`	Port the service binds to.
`DATABASE_URL`	string	Yes	—	MySQL connection string. Format: `mysql+pymysql://user:password@host:port/database`
`USUARIOS_SERVICE_URL`	string	Yes	—	Base URL of `usuarios-service` for authentication delegation.
`UPSTREAM_TIMEOUT_SECONDS`	integer	No	`5`	Timeout in seconds for calls to `usuarios-service`.
`CORS_ALLOW_ORIGINS`	string	Yes	—	Comma-separated list of allowed CORS origins.

Docker Compose injection:

aulas-service:
  environment:
    DATABASE_URL: mysql+pymysql://root:${MYSQL_ROOT_PASSWORD}@mysql/aulas_db
    USUARIOS_SERVICE_URL: http://usuarios-service:8001
    UPSTREAM_TIMEOUT_SECONDS: 5
    CORS_ALLOW_ORIGINS: ${CORS_ALLOW_ORIGINS}
    APP_PORT: 8003

Production values

Variable	How to generate
`JWT_SECRET`	`openssl rand -hex 32`
`ADMIN_CREATION_KEY`	`openssl rand -hex 16`
`INTERNAL_API_KEY`	`openssl rand -hex 16`
`MYSQL_ROOT_PASSWORD`	Use a password manager or `openssl rand -base64 24`
`POSTGRES_PASSWORD`	Use a password manager or `openssl rand -base64 24`

Never set CORS_ALLOW_ORIGINS=* in production. Always specify the exact domains your frontend is served from. Wildcard CORS disables the same-origin protection for all browsers.

Get Started

Core Features

Deployment & Operations

Security

Environment variables reference for all services

Shared variables (root `.env`)

Service variables

Production values

Build docs developers (and LLMs) love

Get Started

Core Features

Deployment & Operations

Security

Documentation Index

​Shared variables (root .env)

​Service variables

​Production values

Build docs developers (and LLMs) love

Shared variables (root `.env`)

Service variables

Production values