Skip to main content
Version: Next

Infrastructure Docker

Repository: leia-org/leia-infrastructure-docker

Docker Compose configurations for orchestrating the complete LEIA system. The repository provides three deployment profiles (full stack, Designer-only, and Workbench-only) covering all 5 microservices, two MongoDB instances, and Redis.

System Architecture​

The LEIA stack is composed of 5 application services backed by 3 infrastructure services:

ServiceImageExposed PortRole
designer-backendghcr.io/leia-org/leia-designer-backend:latestPORT_DESIGNER_BACKEND (3001)REST API for LEIAs, personas, and experiments
designer-frontendghcr.io/leia-org/leia-designer-frontend:latestPORT_DESIGNER_FRONTEND (3004)Web UI for instructors
workbench-backendghcr.io/leia-org/leia-workbench-backend:latestPORT_WORKBENCH_BACKEND (3002)REST API for experiments and sessions
workbench-frontendghcr.io/leia-org/leia-workbench-frontend:latestPORT_WORKBENCH_FRONTEND (3005)Web UI for workbench users
runnerghcr.io/leia-org/leia-runner:latestPORT_RUNNER (3003)AI session execution engine
mongodb-designermongo:latestMONGO_PORT_DESIGNER (27017)Database for Designer
mongodb-workbenchmongo:latestMONGO_PORT_WORKBENCH (27018)Database for Workbench
redisredis:latestREDIS_PORT (6379)Cache and task queue for Runner

All application images are pulled from the GitHub Container Registry (GHCR) and are built automatically via GitHub Actions in each service repository.

Inter-service communication​

Inside a running Compose stack, services communicate with each other via their container names. No external URLs are needed.

CallerCalleeContainer URLAuth header
designer-frontenddesigner-backendhttp://designer-backend:80Authorization: Bearer <jwt>
workbench-frontendworkbench-backendhttp://workbench-backend:80JWT / admin secret / share token
workbench-backenddesigner-backendhttp://designer-backend:80x-api-key: <DESIGNER_BACKEND_KEY>
workbench-backendrunnerhttp://runner:80Authorization: Bearer <RUNNER_KEY>
runnerredisredis://redis:6379-
designer-backendmongodb-designermongodb://mongodb-designer:27017Mongo credentials
workbench-backendmongodb-workbenchmongodb://mongodb-workbench:27017Mongo credentials
info

The keys RUNNER_KEY and DESIGNER_BACKEND_KEY must match their counterparts in the callee's environment (RUNNER_KEY in the Runner, API_KEY in the Designer Backend). See the Environment Variables section.

Prerequisites​

  • Docker and Docker Compose installed.
  • A valid OpenAI API key (required by the Runner service).
  • Docker images for all 5 LEIA services published to GHCR (happens automatically via GitHub Actions on each service repo).

Project Structure​

leia-infrastructure-docker/
├── docker-compose.yaml          # Full stack (all 5 services + databases)
├── docker-compose-public.yaml   # Designer-only (backend, frontend, runner, MongoDB, Redis)
├── docker-compose-private.yaml  # Workbench-only (backend, frontend, runner, MongoDB, Redis)
├── .env.example                 # Environment variable template
└── .gitignore

Environment Variables​

Copy the example file and fill in all values before starting any services:

cp .env.example .env

Database​

VariableDefaultDescription
MONGO_USERNAMEadminMongoDB root username
MONGO_PASSWORDpassword123MongoDB root password
MONGO_PORT_DESIGNER27017Host port for the Designer MongoDB
MONGO_PORT_WORKBENCH27018Host port for the Workbench MongoDB
REDIS_PORT6379Host port for Redis

Service Ports​

VariableDefaultDescription
PORT_DESIGNER_BACKEND3001Host port for the Designer Backend
PORT_WORKBENCH_BACKEND3002Host port for the Workbench Backend
PORT_RUNNER3003Host port for the Runner
PORT_DESIGNER_FRONTEND3004Host port for the Designer Frontend
PORT_WORKBENCH_FRONTEND3005Host port for the Workbench Frontend

Internal Service URLs​

These are used for inter-service communication inside the Docker network. Do not change them unless you rename a service.

VariableDefaultDescription
DESIGNER_BACKEND_URLhttp://designer-backend:80Designer Backend URL seen by other services
WORKBENCH_BACKEND_URLhttp://workbench-backend:80Workbench Backend URL seen by other services
RUNNER_URLhttp://runner:80Runner URL seen by backend services

External Frontend URLs​

Used by backend services to configure CORS. Set these to the URL users will access in their browser.

VariableDefaultDescription
DESIGNER_FRONTEND_URL_EXTERNALhttp://localhost:3004Public URL of the Designer Frontend
WORKBENCH_FRONTEND_URL_EXTERNALhttp://localhost:3005Public URL of the Workbench Frontend

Authentication and Security​

warning

All secrets below have insecure defaults. Change every one of them before deploying to any non-local environment.

VariableDescription
JWT_SECRETSecret used to sign and verify JWT tokens
API_KEYKey for internal API authentication
RUNNER_KEYAuthentication key shared between backends and the Runner
DESIGNER_BACKEND_KEYKey used by the Workbench Backend to call the Designer Backend
ADMIN_SECRETAdmin-level secret for privileged Workbench operations

Default Admin Account​

VariableDefaultDescription
DEFAULT_ADMIN_EMAILadmin@leia.orgEmail of the auto-created admin user
DEFAULT_ADMIN_PASSWORDadmin123Password of the auto-created admin user

AI / LLM Configuration​

VariableDefaultDescription
OPENAI_API_KEY(required)OpenAI API key used by the Runner
OPENAI_EVALUATION_MODELgpt-4Model used for LEIA evaluation
DEFAULT_MODELgpt-3.5-turboDefault LLM model for AI sessions

Environment​

VariableDefaultDescription
NODE_ENVproductionRuntime environment for all services

Deployment Options​

The repository provides three Compose files for different deployment scenarios:

FileUse caseServices included
docker-compose.yamlFull LEIA stackAll 5 services + 2 MongoDB + Redis
docker-compose-public.yamlDesigner onlydesigner-backend, designer-frontend, runner, mongodb-designer, redis
docker-compose-private.yamlWorkbench onlyworkbench-backend, workbench-frontend, runner, mongodb-workbench, redis

Quick Start: Full Stack​

Launch the complete LEIA system:

  1. Clone the repository and enter the directory:

    git clone https://github.com/leia-org/leia-infrastructure-docker.git
    cd leia-infrastructure-docker

  2. Copy and configure the environment file:

    cp .env.example .env

    At minimum, set your OPENAI_API_KEY and change all default secrets.

  3. Start all services:

    docker-compose -f docker-compose.yaml up -d

  4. Verify all containers are running:

    docker-compose -f docker-compose.yaml ps

Once running, the services are accessible at:

ServiceURL
Designer Frontendhttp://localhost:3004
Workbench Frontendhttp://localhost:3005
Designer Backend APIhttp://localhost:3001
Workbench Backend APIhttp://localhost:3002
Runner APIhttp://localhost:3003

Partial Deployments​

Designer Only​

Runs only the Designer microservices (backend, frontend, runner, MongoDB, Redis):

docker-compose -f docker-compose-public.yaml up -d

Use this profile to work on the LEIA configuration workflow without spinning up the Workbench.

Workbench Only​

Runs only the Workbench microservices (backend, frontend, runner, MongoDB, Redis):

docker-compose -f docker-compose-private.yaml up -d

Use this profile when working on the experiment execution and student session flow.

Stopping Services​

# Stop and remove containers (data volumes are preserved)
docker-compose -f docker-compose.yaml down

# Stop and also remove data volumes (full reset)
docker-compose -f docker-compose.yaml down -v
warning

Using down -v will permanently delete all MongoDB and Redis data. Use only when you want a clean reset.

Contributing​

  1. Fork the repository and create a branch off main:

    git checkout -b feat/my-change

  2. Copy .env.example to .env and configure it for local testing.

  3. Make your changes to the relevant Compose file (docker-compose.yaml, docker-compose-public.yaml, or docker-compose-private.yaml).

  4. Test your changes locally before opening a PR:

    docker-compose -f docker-compose.yaml up -d
    docker-compose -f docker-compose.yaml ps

  5. Use Conventional Commits for your commit messages (feat:, fix:, docs:, etc.).

  6. Open a Pull Request with a clear description of the infrastructure changes and their impact on service connectivity or environment variables.