docker-compose.yml

services:
  app:
    build:
      context: .
      # Match the container user to the host user so files written into the
      # bind mount below are not root-owned. Set UID/GID in .env -- see
      # .env.example. Changing these needs a rebuild AND `docker compose down
      # -v`, because the anonymous node_modules volume keeps the ownership it
      # was first created with.
      args:
        UID: ${UID:-1000}
        GID: ${GID:-1000}
    ports:
      - '4200:4200'
      - '4001:4001'
    volumes:
      - .:/app
      - /app/node_modules
      # This ensures the nested tina folder is visible to the watcher
      - ./projects/website-angular/tina:/app/projects/website-angular/tina
    # localhost inside a container is the container. The Reactome backend
    # (Tomcat, and behind it Neo4j and Solr) runs on the host, so reach it
    # through the docker bridge gateway. proxy.conf.js reads this and otherwise
    # defaults to localhost:8080, which is correct when running on the host.
    extra_hosts:
      - 'host.docker.internal:host-gateway'
    environment:
      - NG_CLI_ANALYTICS=false
      - NODE_ENV=development
      - REACTOME_BACKEND=http://host.docker.internal:8080
      # The render service is a sibling container, not loopback. proxy.conf.js
      # reads this and otherwise defaults to 127.0.0.1:4310, which is correct
      # when both run on the host.
      - RENDER_TARGET=http://render:4310
    stdin_open: true
    tty: true

  # Diagram figures for documents -- GIF, PPTX, PDF, PNG, SVG -- rendered by
  # driving the app's own render page, so an exported figure cannot drift from
  # what a curator sees. Replaces the Java exporters, which reimplement the
  # drawing.
  render:
    build:
      context: .
      dockerfile: deploy/render-service/Dockerfile
    # A render is a browser holding a large canvas, and this box also runs the
    # site, Tomcat and Neo4j. If it wedges or runs out of memory, restarting is
    # the right response -- there is no state to lose but the cache, which is on
    # a volume.
    restart: unless-stopped
    # Loopback only, never 0.0.0.0. The site's own origin proxies /RenderService
    # to this, so a render can only be commissioned through whatever fronts the
    # site -- crawlers on the old /ContentService/exporter/* URLs are what
    # exhausted Tomcat's heap and took the origin down. Publishing it here rather
    # than relying on the compose network because on the dev box the site itself
    # runs on the host, not in compose; a deployment where both are containers can
    # drop this line and reach it by service name.
    ports:
      - '127.0.0.1:4310:4310'
    environment:
      # What it renders. The service name when the site is a container here, the
      # host when it is not -- which is the case on the dev box.
      - RENDER_BASE=${RENDER_BASE:-http://host.docker.internal:4200}
      - RENDER_CACHE=/cache
      - RENDER_CONCURRENCY=2
      - RENDER_QUEUE=8
    volumes:
      - render-cache:/cache
    # No depends_on: the site it renders may be the app service or may be on the
    # host, and starting a second app container would fight the first for :4200.
    extra_hosts:
      - 'host.docker.internal:host-gateway'
    # Chromium's default 64 MB /dev/shm is not enough for a 6000px canvas; a
    # renderer that fails only on large diagrams is the usual symptom.
    shm_size: '1gb'

  # The MCP server (reactome-mcp), which lets an AI assistant read Reactome
  # through its own tools rather than through a browser.
  #
  # Here because until now it had no definition anywhere: it was a `docker run`
  # somebody typed once, bind-mounting a git checkout at /srv and running the
  # `dist/` inside it. `dist/` is gitignored, so what that served was whatever
  # branch happened to be checked out, compiled whenever anyone last ran a
  # build -- and a test run rebuilding it from an unmerged branch had already
  # put code into the running container that no longer existed on disk.
  #
  # Built from a git ref instead, so the deployed revision is something someone
  # chose. MCP_REF is a branch or tag; the container records the commit it was
  # built from in /srv/REVISION.
  mcp:
    build:
      context: .
      dockerfile: deploy/mcp/Dockerfile
      args:
        MCP_REF: ${MCP_REF:-main}
    restart: unless-stopped
    # Loopback only, and emphatically not 0.0.0.0. Same reason as `render`
    # above, and worse per request: a tool call here can submit a real job to
    # the Analysis Service, so the only way in is through whatever fronts the
    # site, which rate-limits it. The container this replaces set
    # MCP_HTTP_HOST=0.0.0.0 safely because it was on a private compose network
    # with nothing published; that is not safe under `network_mode: host`, so
    # the binding is pinned here rather than inherited.
    # Probes a real MCP session, not /health.
    #
    # /health reports that the process is up, which is a different question from
    # whether it can serve anything: a server that binds and then fails every
    # session answers it `ok`. That is not hypothetical -- a bad
    # MCP_TOOL_GROUPS produced exactly that shape until the server started
    # validating before binding, and the general case survives that fix.
    #
    # So this does what a client does: initialize, require a session id back,
    # and then DELETE the session. The delete is not tidiness. Each session gets
    # its own server instance and idle ones are only reaped after thirty
    # minutes, so a check that opened one every minute and walked away would
    # hold about thirty instances for ever, purely to watch. Measured before
    # adding it: three initialize calls took the count from 2 to 5 and it stayed
    # there; with the delete, three runs left it unchanged.
    #
    # It also keeps /health's `sessions` honest, which matters because that
    # number is the thing anyone would reach for to see whether the server is
    # being used.
    #
    # Node rather than curl or wget, because the image is node:22-slim and has
    # neither -- a healthcheck that silently always fails is worse than none,
    # since it reports unhealthy for a service that is fine and trains people to
    # ignore it.
    healthcheck:
      test:
        [
          'CMD',
          'node',
          '-e',
          "const u='http://127.0.0.1:4320/mcp',h={'Content-Type':'application/json','Accept':'application/json, text/event-stream'};fetch(u,{method:'POST',headers:h,body:JSON.stringify({jsonrpc:'2.0',id:1,method:'initialize',params:{protocolVersion:'2024-11-05',capabilities:{},clientInfo:{name:'healthcheck',version:'1'}}})}).then(r=>{const s=r.headers.get('mcp-session-id');if(!r.ok||!s)process.exit(1);return fetch(u,{method:'DELETE',headers:{...h,'mcp-session-id':s}})}).then(()=>process.exit(0)).catch(()=>process.exit(1));",
        ]
      interval: 60s
      timeout: 10s
      # Generous, because the first session builds a server instance and this
      # box is busy. A healthcheck that flaps under load is noise.
      retries: 3
      start_period: 20s
    ports:
      - '127.0.0.1:4320:4320'
    # Two ways in, for two callers that cannot share one.
    #
    # nginx runs in host networking, so it reaches the published port above on
    # 127.0.0.1. The chatbot is a container on its own private network and
    # addresses this by name -- `REACTOME_MCP_URL=http://reactome_mcp:4320` --
    # so the alias is what lets it keep doing that. Without it the chatbot would
    # need reconfiguring to point at a host gateway, which is a change to
    # somebody else's deployment to solve a problem on this side.
    #
    # The alias is the name of the hand-run container this replaces, on purpose:
    # the swap is then invisible to the thing depending on it.
    networks:
      default: {}
      reactome_beta:
        aliases:
          - reactome_mcp
    environment:
      # 0.0.0.0 *inside* the container, which the port mapping above then
      # exposes on loopback only. A container binding its own loopback would be
      # unreachable even from the host.
      - MCP_HTTP_HOST=0.0.0.0
      - MCP_HTTP_PORT=4320
      # Which Reactome it answers from: this deployment's own, never another's.
      # An MCP on beta that answered from production would describe a release
      # nobody here is running.
      - REACTOME_BASE_URL=${MCP_REACTOME_BASE_URL:-https://beta.reactome.org}
      # NEO4J_URI and MCP_ALLOW_CYPHER are both deliberately absent, and it
      # takes both to register the Cypher tools, the graph-schema resource and
      # the instructions that advertise them. Arbitrary graph queries used to
      # arrive as a side effect of setting a connection string -- the startup
      # schema warm-up wants the same variable -- so an instance could acquire
      # them without anyone deciding to. Neither belongs on an instance the
      # public can reach.

  # Reactome's graph database, as the project publishes it for each release
  # (developer docs: documentation/dev/graph-database). Replaces the Neo4j
  # installed on the host, so the database is a pinned image like everything
  # else here rather than a system package nobody upgrades in step with a
  # release. To move to a new release, change the tag and `up -d graphdb`, then
  # RESTART content-node (`docker compose restart content-node`): it holds the
  # release number and the cached lists in memory, and the release number keys
  # every diagram, figure and icon URL, so a missed restart sends them all to the
  # previous release's files without an error. Check with `curl
  # 127.0.0.1:4400/health`: its "release" must be the new one.
  graphdb:
    image: public.ecr.aws/reactome/graphdb:Release97
    restart: unless-stopped
    # Bolt on loopback only, on the port the host database used, so everything
    # that reads it -- content-node, the Java ContentService, the analysis
    # service -- keeps the address it has. Never 0.0.0.0: arbitrary queries are
    # the cheapest way to make every page on the site slow. Not the HTTP port
    # (7474): nothing here uses it.
    ports:
      - '127.0.0.1:7687:7687'
    # A network of its own. On the default one, every other container in this
    # file could reach it by name, which the host install never allowed; its
    # readers all come in through the loopback port.
    networks:
      - graphdb
    # The image is built with authentication off. The wrapper turns it on with
    # the credentials the services already hold, read from the same file
    # content-node mounts (see there for why it is read literally), and refuses
    # to start if they are missing rather than starting open.
    entrypoint: ['/bin/bash', '/graphdb-entrypoint.sh']
    command: ['neo4j']
    volumes:
      - ./deploy/graphdb/entrypoint.sh:/graphdb-entrypoint.sh:ro
      - ${CONTENT_NODE_ENV_FILE:-~/.content-node.env}:/run/secrets/graphdb.env:ro
      # The store, in a volume named for its release. Docker fills an empty
      # volume from the image once; after that a restart or a recreate reuses
      # it. Left in the container's own layer, every start copied all 3.2GB
      # there, because the image's entrypoint changes the owner of every file.
      #
      # Named for the release so that changing the image tag alone cannot keep
      # serving the previous release's data: the tag and this name move
      # together (deploy/graphdb/compose.spec.ts checks it), and the old
      # volume is removed once the new release is live.
      #
      # The password is set when the volume is first filled. Changing it later
      # needs the volume recreated, or ALTER USER in the database.
      - graphdb-release97:/var/lib/neo4j/data
      # The image declares both as volumes; named, so a recreate does not leave
      # another anonymous pair behind each time.
      - graphdb-logs:/logs
      - graphdb-unused:/data
    environment:
      # The size the host database ran with.
      - NEO4J_dbms_memory_heap_max__size=3g
      - NEO4J_dbms_memory_pagecache_size=2g
      - NEO4J_dbms_default__database=graph.db

  # A bounded queue in front of the AnalysisService's computations (spec 010
  # Story 6): a few analyses at once, the rest waiting their turn for at most
  # a minute, then "busy, try again" -- instead of every analysis slowing down
  # together until all of them pass the edge's 100 s. Everything else passes
  # through unchanged. Host networking, as content-node: Tomcat's
  # AnalysisService is on the host's loopback, and nginx reaches this on
  # 127.0.0.1:4350. Stateless, so a restart costs only the requests in flight.
  analysis-gateway:
    build:
      context: .
      dockerfile: deploy/analysis-gateway/Dockerfile
    restart: unless-stopped
    network_mode: host
    environment:
      - ANALYSIS_UPSTREAM=${ANALYSIS_UPSTREAM:-http://127.0.0.1:8080}
      - ANALYSIS_LIMIT=${ANALYSIS_LIMIT:-4}
      - REPORT_LIMIT=${REPORT_LIMIT:-1}
      - QUEUE_LENGTH=${QUEUE_LENGTH:-40}
      - PER_CLIENT=${PER_CLIENT:-8}
      - MAX_WAIT_MS=${MAX_WAIT_MS:-60000}
      - RETRY_AFTER=${RETRY_AFTER:-10}
      - UPSTREAM_TIMEOUT_MS=${UPSTREAM_TIMEOUT_MS:-300000}

  content-node:
    build:
      context: .
      dockerfile: deploy/content-node/Dockerfile
    # It holds two lists in memory and nothing else, so a restart costs one
    # rebuild of the caches -- about four seconds -- and never any data. Left
    # unsupervised it runs only because somebody started it by hand, and the
    # contents page goes blank the first time this box reboots, with nothing to
    # connect the outage to a restart hours earlier.
    restart: unless-stopped
    # Host networking, for as long as the graph is on the host.
    #
    # Neo4j listens on 127.0.0.1:7687 and should keep doing so. A bridged
    # container cannot reach that, and the usual workaround -- binding Neo4j to
    # the docker bridge -- widens who can reach the database to fit a container
    # in. Sharing the host's namespace keeps the database exactly as reachable
    # as it is today and the service on loopback where nginx expects it.
    #
    # **This is the line to delete when the graph becomes a container**, which
    # is the plan: a Neo4j image built per release. Then this joins the compose
    # network, `NEO4J_URI` names that service instead of loopback, and it
    # publishes 127.0.0.1:4400 like `render` does. `graph.ts` already reads
    # NEO4J_URI from the environment, so that is configuration rather than a
    # change here. Recorded in specs/006 D13 so the reason is findable when the
    # line looks arbitrary.
    network_mode: host
    # The credentials file is **mounted, not parsed**. graph.ts reads it
    # literally for a documented reason: a generated secret contains characters
    # a shell eats, and sourcing one silently produced an empty password once.
    #
    # compose's own `env_file` parser does the same thing. Tried first, and it
    # read `NEO4J_DATABASE=graph.db` correctly while handing the service
    # `NEO4J_PASSWORD=""` -- the service then reported "graph credentials:
    # MISSING" and every request 500'd. Exactly the fault the literal reader was
    # written to avoid, reintroduced by the layer underneath it.
    volumes:
      - ${CONTENT_NODE_ENV_FILE:-~/.content-node.env}:/run/secrets/content-node.env:ro
    environment:
      - CONTENT_NODE_ENV_FILE=/run/secrets/content-node.env
    # Runs as the owner of that file, which is 0600 and should stay that way.
    # The image's own `node` user is uid 1000 and cannot read it, so the service
    # started, reported "graph credentials: MISSING", and answered 500 -- a
    # container that is up and useless, which is the state monitoring is worst
    # at noticing.
    #
    # Defaults to this host's operator; override where the file has a different
    # owner. `id -u`, `id -g`.
    user: '${CONTENT_NODE_UID:-1020}:${CONTENT_NODE_GID:-1001}'
    # No depends_on graphdb, deliberately: if the graph is down this starts,
    # fails to build its lists, and rebuilds on the next request -- which is
    # the behaviour specs/006 D10 asks for -- rather than refusing to start.

  # The front door. Replaces the hand-created `reactome-nginx` container, which
  # mounted its config from /etc/nginx-reactome -- a *copy* of deploy/nginx that
  # had to be installed with sudo and could drift from the repository without
  # anything saying so. The only reason it was known to match today is that
  # somebody diffed it.
  #
  # Mounting the repository instead makes this the single source: edit
  # deploy/nginx, `docker compose exec nginx nginx -t`, reload. No sudo, no
  # OS-specific install path, and it works the same on a laptop.
  #
  # To take over from the hand-created container:
  #   docker stop reactome-nginx
  #   docker compose up -d nginx
  # To go back: `docker compose stop nginx && docker start reactome-nginx`.
  # Both bind the host's ports, so only one can run at a time.
  nginx:
    build:
      context: .
      dockerfile: deploy/nginx/Dockerfile
      args:
        # Which deployment this host is. See deploy/nginx/README.md -- getting
        # this wrong on the indexed host would deindex reactome.org.
        NGINX_ENV: ${NGINX_ENV:-dev}
    restart: unless-stopped
    # Host networking, as the container it replaces used: the services it
    # proxies -- the site on 4200, content-node on 4400, render on 4310, the
    # chatbot on 8000 -- are reached on loopback, and several of them bind there
    # deliberately so nothing else can.
    network_mode: host
    volumes:
      # Only the certificates are mounted. The configuration is baked into the
      # image above, so a checkout cannot change what this serves.
      # The one part that cannot live in the repository. Paths are variables so
      # a laptop can point somewhere else, or at an empty directory when it is
      # serving plain HTTP and has no certificates at all.
      - ${LETSENCRYPT_DIR:-/etc/letsencrypt}:/etc/letsencrypt:ro
      - ${CLOUDFLARE_CERT_DIR:-/etc/ssl/cloudflare}:/etc/ssl/cloudflare:ro

networks:
  # Created by the chatbot's own stack, not by this one -- declared external so
  # compose joins it rather than trying to own it, and never removes it.
  reactome_beta:
    external: true
  graphdb: {}

volumes:
  # Survives a container replacement, which is the point: a cached figure is a
  # file read, and rebuilding the cache means paying for every render again.
  render-cache:
  graphdb-release97:
  graphdb-logs:
  graphdb-unused: