Run Módulo Horario locally with Docker Compose

The fastest way to run Módulo Horario is with Docker Compose, which starts all four backend services and both databases in a single command. If you prefer to run services directly with Python, see the manual setup section below.

Docker (recommended)
Manual setup (without Docker)

Prerequisites

Make sure you have the following installed before you begin:

Docker and Docker Compose v2
Node.js 18 or higher (for the frontend)
Git
openssl (used by the secrets script; included on macOS and most Linux distributions)

Clone the repository

git clone https://github.com/Luisanchez0/modulo_Horario.git
cd modulo_Horario

Generate secrets

Run the setup script to create services/.env with secure, randomly generated values:

bash setup-secrets.sh

The script writes three secrets to services/.env:

Variable	Purpose
`JWT_SECRET`	Signs and verifies all JWT tokens (HS256)
`ADMIN_CREATION_KEY`	Required to register the first admin account
`INTERNAL_API_KEY`	Authenticates inter-service HTTP calls via the `X-Internal-Key` header

Never commit services/.env to version control. The file is already listed in .gitignore.

Start the backend services

cd services
docker compose up --build

Docker Compose starts four application services alongside MySQL 8 and PostgreSQL 16. Wait until you see all four uvicorn startup messages:

usuarios-service  | Uvicorn running on http://0.0.0.0:8001
materias-service  | Uvicorn running on http://0.0.0.0:8002
aulas-service     | Uvicorn running on http://0.0.0.0:8003
horario-service   | Uvicorn running on http://0.0.0.0:8004

Verify service health

In a new terminal, check that all services are responding:

curl http://localhost:8001/health

Expected response:

{"status": "ok", "service": "usuarios-service"}

You can check the other three services on ports 8002, 8003, and 8004 — each returns {"status": "ok"}.

Start the frontend

In a separate terminal, from the project root:

cd frontend
npm install
npm run dev

Vite starts the development server at http://localhost:5173.

Open http://localhost:5173 in your browser and sign in with the development credentials:

Email: [email protected]
Password: 1234

These credentials are for local development only. Before deploying to any shared or production environment, rotate all secrets by re-running bash setup-secrets.sh and updating your deployment configuration. See the Security guide for details.

Generate your first schedule

Once logged in:

Navigate to Horarios in the sidebar.
Create an academic period (for example, “Semester 2026-1”).
Add teachers in Docentes, subjects in Materias, and classrooms in Aulas.
Return to Horarios and click Generate to let the algorithm build a conflict-free timetable.
View the result in the Calendar tab or export it to PDF.

Use this approach if you want faster iteration on a single service or prefer not to run Docker.

Prerequisites

Install MySQL and PostgreSQL locally, then create the required databases:

# Ubuntu / Debian
sudo apt install mysql-server postgresql postgresql-contrib

# macOS
brew install mysql postgresql

-- MySQL
CREATE DATABASE docentes_db;
CREATE DATABASE aulas_db;

-- PostgreSQL
CREATE DATABASE materias_db;
CREATE DATABASE horarios_db;

Backend services

Run each service in its own terminal. The pattern is the same for all four — only the port and environment variables differ.

usuarios-service (port 8001)

cd services/usuarios-service
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

export DATABASE_URL="mysql+pymysql://root:password@localhost/docentes_db"
export JWT_SECRET=$(openssl rand -hex 32)
export ADMIN_CREATION_KEY=$(openssl rand -hex 16)
export INTERNAL_API_KEY=$(openssl rand -hex 16)

uvicorn main:app --reload --port 8001

materias-service (port 8002)

cd services/materias-service
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

export DATABASE_URL="postgresql+asyncpg://postgres:password@localhost:5432/materias_db"
export USUARIOS_SERVICE_URL="http://localhost:8001"

uvicorn app.main:app --reload --port 8002

aulas-service (port 8003)

cd services/aulas-service
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

export DATABASE_URL="mysql+pymysql://root:password@localhost/aulas_db"
export USUARIOS_SERVICE_URL="http://localhost:8001"

uvicorn main:app --reload --port 8003

horario-service (port 8004)

cd services/horario-service
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

export DATABASE_URL="postgresql://postgres:password@localhost:5432/horarios_db"
export JWT_SECRET="<same value as usuarios-service>"
export INTERNAL_API_KEY="<same value as usuarios-service>"
export USUARIOS_SERVICE_URL="http://localhost:8001"
export MATERIAS_SERVICE_URL="http://localhost:8002"
export AULAS_SERVICE_URL="http://localhost:8003"

uvicorn main:app --reload --port 8004

Frontend

cd frontend
npm install
npm run dev

When running without Docker, JWT_SECRET and INTERNAL_API_KEY must be the same value across all services that use them, or inter-service calls and token verification will fail.

Get Started

Core Features

Deployment & Operations

Security

Run Módulo Horario locally with Docker Compose

Prerequisites

Backend services

Build docs developers (and LLMs) love

Get Started

Core Features

Deployment & Operations

Security

Documentation Index

​Prerequisites

​Backend services

Build docs developers (and LLMs) love

Prerequisites

Backend services