Skip to content

Deployment

This page describes how the app is deployed to staging via GitLab CI/CD, Docker Compose, and Traefik.

Overview

  • Staging runs on push to master or develop. The pipeline builds the frontend and docs in CI, then deploys artifacts to the server and starts containers.
  • Routing is done by Traefik (external) using subdomains and HTTPS (Let’s Encrypt).
  • A more detailed, server-oriented guide lives in the repo root: DEPLOYMENT.md.

Pipeline

Build stage

Two jobs run in parallel:

  1. build
  2. Image: node:22-alpine
  3. Runs npm ci and npm run build.
  4. The frontend is built with VITE_API_BASE_URL from CI variables (default: https://api.simu-game.my-game.com/api).

  5. Artifact: dist/.

  6. build:docs

  7. Image: python:3-alpine
  8. Installs zensical and mkdocstrings, then runs zensical build.
  9. Artifact: site/ (Zensical’s default output).

Deploy stage

deploy:stage runs only after both build jobs succeed (needs: [build, build:docs]).

  1. SSH setup
    Uses SSH_PRIVATE_KEY (base64-decoded), DEPLOY_USER, and DEPLOY_HOST from GitLab CI/CD variables.

  2. Copy to server

  3. Target directory: /opt/game/
  4. dist/ → frontend static files
  5. site/ → built documentation
  6. docs/ (source), docker-compose.stage.yml, .docker/*, package*.json, tsconfig.json, zensical.toml

  7. src/server/ and src/sim/ for the API server build

  8. On the server

  9. docker compose -f docker-compose.stage.yml pull || true
  10. docker compose -f docker-compose.stage.yml up -d --build
    So web and api images are built on the server; docs uses the pre-built site/ via a volume.

Staging services

Service Role Traefik rule URL (example)
web Nginx serving dist/ Host(simu-game.my-game.com) https://simu-game.my-game.com
api Express API Host(api.simu-game.my-game.com) https://api.simu-game.my-game.com
docs Nginx serving site/ Host(docs.simu-game.my-game.com) https://docs.simu-game.my-game.com

All use the external Docker network traefik and TLS via Let’s Encrypt (certresolver=letsencrypt).

Required CI/CD variables

Configure in GitLab: Settings → CI/CD → Variables.

Variable Purpose
DEPLOY_HOST Staging server hostname or IP
DEPLOY_USER SSH user
SSH_PRIVATE_KEY Private key for deployment (base64-encoded; pipeline decodes it)
VITE_API_BASE_URL (Optional) API base URL for the frontend build; default is set in .gitlab-ci.yml

Changing domains or API URL

  • Traefik / domains: Edit the Host(...) labels in docker-compose.stage.yml and ensure DNS points to the server.
  • API URL for the frontend: Set the VITE_API_BASE_URL CI variable and/or the default in .gitlab-ci.yml variables (must include the path, e.g. https://api.simu-game.my-game.com/api).

Troubleshooting

  • Logs on server:
    docker compose -f docker-compose.stage.yml logs -f [web|api|docs]
  • Force rebuild:
    docker compose -f docker-compose.stage.yml up -d --build --force-recreate
  • API health:
    curl https://api.simu-game.my-game.com/health (or your API host)

For more detail (Traefik network, manual deploy, etc.) see DEPLOYMENT.md in the project root.