proof-stack.compose.yml

# Three disposable ROM library servers, for `scripts/proof_matrix.py`.
#
#     docker compose -p proofmatrix -f scripts/proof-stack.compose.yml up -d
#     ... run the matrix ...
#     docker compose -p proofmatrix -f scripts/proof-stack.compose.yml down -v
#
# Nothing here is meant to survive. Every credential below is a literal
# throwaway, every volume is anonymous and `down -v` removes all of it.
# **Do not point this at a library you care about**: the matrix uploads a
# ROM, writes metadata over it and leaves it there.
#
# Ports are deliberately not the defaults. RomM's is 8080 and Retrom's is
# 5101, and a matrix run that silently attached to somebody's real server
# would be both a data hazard and a fake result. If any of these collide
# on your host, change them here and pass the matching --*-url flags.
#
# Retrom floats on :latest because it publishes no usable version tags;
# the matrix records the digest and the server-reported version it
# actually ran against, so a PROOF.md is still pinned to something
# specific after the fact. Gaseous used to float too and no longer does --
# see the comment on that service, which is the longest one in this file
# for a reason.

name: proofmatrix

services:
  # -- RomM ---------------------------------------------------------------
  romm:
    image: rommapp/romm:4.9.2
    container_name: proofromm
    depends_on:
      romm-db:
        condition: service_healthy
      romm-redis:
        condition: service_started
    environment:
      - DB_HOST=proofromm-db
      - DB_NAME=romm
      - DB_USER=proof
      - DB_PASSWD=proof
      - REDIS_HOST=proofromm-redis
      # Throwaway. Regenerated by `down -v`, never reused.
      - ROMM_AUTH_SECRET_KEY=proofmatrixproofmatrixproofmatrix
      # No IGDB/SteamGridDB/ScreenScraper credentials on purpose. The
      # matrix proves the Hub's own writes land; a third-party metadata
      # provider would make the result depend on somebody else's uptime.
      - DISABLE_DOWNLOAD_ENDPOINT_AUTH=false
      - WEB_SERVER_CONCURRENCY=2
    ports: ["8085:8080"]
    volumes:
      - romm_library:/romm/library
      - romm_resources:/romm/resources
      - romm_assets:/romm/assets
      - romm_config:/romm/config

  romm-db:
    image: mariadb:11
    container_name: proofromm-db
    environment:
      - MARIADB_ROOT_PASSWORD=proofroot
      - MARIADB_DATABASE=romm
      - MARIADB_USER=proof
      - MARIADB_PASSWORD=proof
    volumes:
      - romm_db:/var/lib/mysql
    healthcheck:
      test: ["CMD", "healthcheck.sh", "--connect", "--innodb_initialized"]
      start_period: 30s
      interval: 5s
      timeout: 5s
      retries: 20

  romm-redis:
    image: redis:alpine
    container_name: proofromm-redis

  # -- Gaseous ------------------------------------------------------------
  #
  # Pinned, not `:latest`, and the pin is the load-bearing part.
  #
  # `:latest` is still the **1.7.x** line. 2.0.0-rc.x is pre-release, so
  # the tag has not moved to it -- and the two are not the same API even
  # though both answer `/api/v1.1`. `POST /Games` requires a different set
  # of fields, a game is addressed by a `MetadataMapId` on 2.0 and by an
  # IGDB `Id` on 1.7.x, `POST /Roms` takes a different multipart field
  # name and only queues the import on 2.0, and `POST /Roms/Imports` does
  # not exist before 2.0 at all. `backends/gaseous/` is written against
  # 2.0 and says so.
  #
  # Floating on `:latest` therefore pointed the Gaseous column at a server
  # generation this project does not claim to support, and the first
  # symptom was the `POST /Games` 400 that the matrix caught. That request
  # is now sent in a form **both** generations accept, and the 400 itself
  # is pinned by a live recording in `tests/fixtures/gaseous/` -- which is
  # the right place for it, because a matrix run proves one server and a
  # recording proves the contract.
  #
  # The second reason is reproducibility, and it is the one that decides
  # this. Gaseous 1.7.x holds no platform metadata of its own: it ingests
  # it from IGDB, and without credentials it knows of no platforms and
  # registers no ROMs at all. Measured on a fresh 1.7.14.0 with these
  # variables empty: `GET /Platforms` answers `[]` and `Games_Roms` stays
  # at 0 rows however long the import queue is given, so `platform_id()`
  # has nothing to resolve and every row below it is NOT-RUN. A Gaseous
  # column that only works for whoever has a Twitch developer account is
  # not a proof anybody else can reproduce. 2.0 adds a `None` metadata
  # source and ships the platform list locally -- 139 platforms on a fresh
  # container, no credentials -- which is what makes this stack runnable
  # by anyone.
  #
  # If you re-pin this: the matrix records the server-reported version, so
  # docs/PROOF.md will say which generation it actually measured. Do not
  # move it to `:latest` expecting the Gaseous column to stay green.
  gaseous:
    image: ghcr.io/gaseous-project/gaseousserver:v2.0.0-rc.3
    container_name: proofgaseous
    depends_on: [gaseous-db]
    ports: ["8086:80"]
    environment:
      - TZ=UTC
      - dbhost=proofgaseous-db
      - dbuser=root
      - dbpass=proof
      # Optional on 2.0, and left empty on purpose: the matrix proves the
      # Hub's own writes land, and a third-party metadata provider would
      # make the result depend on somebody else's uptime. Supply your own
      # (free, from https://dev.twitch.tv) in a `.env` beside this file if
      # you want real metadata; ingestion takes a few minutes on first
      # boot. On 1.7.x these were not optional -- see above.
      - igdbclientid=${PROOF_IGDB_CLIENT_ID:-}
      - igdbclientsecret=${PROOF_IGDB_CLIENT_SECRET:-}
    volumes:
      # Where the data lives moved between the two generations, and a
      # volume on the wrong one persists *nothing* while looking mounted:
      # 1.7.x runs as root and keeps everything under `/root`, 2.0 uses
      # `/home/gaseous` (both directories exist in the 2.0 image, and the
      # `/root` one is empty, which is why this has to be checked rather
      # than assumed). Matches the pinned image above.
      - gaseous_data:/home/gaseous/.gaseous-server

  gaseous-db:
    image: mariadb:11
    container_name: proofgaseous-db
    environment:
      - MARIADB_ROOT_PASSWORD=proof
    volumes:
      - gaseous_db:/var/lib/mysql

  # -- Retrom -------------------------------------------------------------
  #
  # Retrom has no accounts, so there is nothing to log in as.
  #
  # Two things about the library path are load-bearing, and getting either
  # wrong looks like a Hub bug when it is a deployment one:
  #
  # 1. The volume has to be where Retrom's *configured content directory*
  #    points. The stock config says `/app/library`; a volume anywhere else
  #    is simply not looked at, and `UpdateLibrary` answers INTERNAL "No
  #    library content found".
  # 2. Retrom has no upload API at all -- rom-hub files a ROM in over
  #    WebDAV, and Retrom's DAV handler is rooted at its *data* directory
  #    (`/app/data`). A content directory outside that tree is unreachable
  #    over `/dav`, which is precisely what `retrom/upload.py` refuses on
  #    rather than guessing.
  #
  # 3. The content directory's `storageType` decides where a ROM goes.
  #    `MULTI_FILE_GAME` (1), which is what Retrom writes into a fresh
  #    config.json, makes a *directory* the game -- so a `foo.zip` upload
  #    becomes a game whose `fs_name` is `foo`, and the import's
  #    post-condition (find our own filename or digest in the listing)
  #    cannot see it. `SINGLE_FILE_GAME` (0) is the layout the Retrom
  #    tests are written against and the one a ROM library actually wants.
  #
  # `RETROM_CONFIG__CONTENT_DIRECTORIES__*` does not override any of this
  # -- the service writes its own config.json at boot -- so
  # proof-stack-bootstrap.sh installs the file and restarts the container.
  # The volume goes straight to `/app/data/library`, which satisfies (1)
  # and (2) at once.
  #
  # Retrom derives a platform from a *directory* inside the content
  # directory and has no RPC that creates one, so proof-stack-bootstrap.sh
  # makes the directory and seeds one file before the first scan.
  retrom:
    image: ghcr.io/jmberesford/retrom-service:latest
    container_name: proofretrom
    depends_on: [retrom-db]
    ports: ["5102:5101"]
    environment:
      - RETROM_CONFIG__CONNECTION__DB_URL=postgres://retrom:retrom@proofretrom-db:5432/retrom
    volumes:
      - retrom_library:/app/data/library

  retrom-db:
    image: postgres:16-alpine
    container_name: proofretrom-db
    environment:
      - POSTGRES_USER=retrom
      - POSTGRES_PASSWORD=retrom
      - POSTGRES_DB=retrom
    volumes:
      - retrom_db:/var/lib/postgresql/data

volumes:
  romm_library:
  romm_resources:
  romm_assets:
  romm_config:
  romm_db:
  gaseous_data:
  gaseous_db:
  retrom_library:
  retrom_db: