Configuring Docker Compose

The STELLA App is primarily configured via Docker Compose and a set of environment variables.

Both configuration and runtime behavior are controlled through the docker-compose.yml files provided in the repository.

---

Important

Two Docker Compose files are provided:

• docker-compose.yml — standard deployment
• docker-compose-dev.yml — development deployment with hot reloading

The same environment variables are used by both files.
The choice of file only affects developer ergonomics (e.g. local code reloads), not system behavior or configuration semantics.

---

System Configuration (SYSTEMS_CONFIG)

Each experimental system must be declared explicitly in the SYSTEMS_CONFIG environment variable within the Docker Compose configuration.

SYSTEMS_CONFIG: |
{
    "gesis_rec_pyserini": {"type": "recommender"},
    "gesis_rec_pyterrier": {"type": "recommender", "base": true},
    "gesis_rank_pyserini": {"type": "ranker"},
    "gesis_rank_pyserini_base": {"type": "ranker", "base": true}
}

Configuration rules:

• each system runs as an independent service
• exactly one system per task should be marked as the "base" system
• supported system types are ranker and recommender

Full Docker Compose Reference

The complete Docker Compose configuration is included directly from the repository:

name: stella

networks:
  stella-shared:
    external: true
    name: stella-shared

services:
  app:
    build: ./web
    volumes:
      - ./data:/data
    expose:
      - "8000"
    ports:
      - "8080:8000"
    networks:
      stella-shared:
        aliases:
          - stella-app
    environment:
      # Config
      FLASK_APP: app/app
      FLASK_CONFIG: postgres
      INTERLEAVE: "True"
      BULK_INDEX: "False"
      DELETE_SENT_SESSION: "True"
      INTERVAL_DB_CHECK: 3
      SESSION_EXPIRATION: 6
      SESSION_KILL: 120

      # Systems
      SYSTEMS_CONFIG: |
        {
          "gesis_rec_pyserini": {"type": "recommender"},
          "gesis_rec_pyterrier": {"type": "recommender", "base": true},
          "gesis_rank_pyserini": {"type": "ranker"},
          "gesis_rank_pyserini_base": {"type": "ranker", "base": true}
        }
      # Stella Server
      STELLA_SERVER_ADDRESS: http://stella-server:8000
      STELLA_SERVER_USER: site@stella-project.org
      STELLA_SERVER_PASS: pass
      STELLA_SERVER_USERNAME: site

      # Database
      POSTGRES_USER: postgres
      POSTGRES_PW: change-me
      POSTGRES_DB: postgres
      POSTGRES_URL: db-app:5430

    command: gunicorn -w 2 --timeout 60 -b :8000 'app.app:create_app()'
    depends_on:
      - db-app
      - gesis_rec_pyterrier
      - gesis_rec_pyserini
      - gesis_rank_pyserini_base
      - gesis_rank_pyserini

  db-app:
    image: postgres:16
    expose:
      - "5430"
    ports:
      - "5430:5430"
    networks:
      - stella-shared
    environment:
      - POSTGRES_USER=postgres
      - POSTGRES_PASSWORD=change-me
      - POSTGRES_DB=postgres
    command: -p 5430

  gesis_rank_pyserini_base:
    build: https://github.com/stella-project/gesis_rank_pyserini_base.git#main
    container_name: gesis_rank_pyserini_base
    volumes:
      - ./data/:/data/
    networks:
      - stella-shared

  gesis_rank_pyserini:
    build: https://github.com/stella-project/gesis_rank_pyserini.git#main
    container_name: gesis_rank_pyserini
    volumes:
      - ./data/:/data/
    networks:
      - stella-shared

  gesis_rec_pyterrier:
    build: https://github.com/stella-project/gesis_rec_pyterrier.git#main
    container_name: gesis_rec_pyterrier
    volumes:
      - ./data/:/data/
    networks:
      - stella-shared

  gesis_rec_pyserini:
    build: https://github.com/stella-project/gesis_rec_pyserini.git#main
    container_name: gesis_rec_pyserini
    volumes:
      - ./data/:/data/
    networks:
      - stella-shared