Deployment

Deployment

Requirements

• Server: Docker and Docker Compose (for the path below), or Rust + PostgreSQL for Development.
• Agent: Windows 10/11 (64-bit). Build on Windows, or cross-compile from Linux with cargo-xwin.

Docker Compose (repository default)

The main repository ships one Compose file, docker-compose.yml, plus .env.example for the minimum variables. It runs Postgres and pulls the published server image from GHCR.

1. Environment (minimal)

From the repository root:

cp .env.example .env

Edit .env. The minimum for a working stack:

Variable	Purpose
POSTGRES_PASSWORD	Database password (required by Compose).
ADMIN_PASSWORD	Bootstrap password for the first dashboard admin (then users live in Postgres).
AGENT_SECRET	Same secret every Windows agent must use (see Usage).

Defaults you usually keep for LAN / testing:

• PUBLISH_PORT=9000 — dashboard at http://localhost:9000
• ENFORCE_HTTPS=false — required for plain HTTP without a TLS reverse proxy (otherwise expect HTTP 426).

Every server and Compose variable (including optional and advanced) is listed on Configuration. A long copy-paste block lives on Environment template.

2. Start

docker compose up -d

Sign in with ADMIN_PASSWORD (or legacy UI_PASSWORD if you still use that name in .env).

3. Build the server image from this repository

Save the following next to docker-compose.yml as e.g. docker-compose.build.yml (any filename you like), then merge it when you run Compose:

# Merge: docker compose -f docker-compose.yml -f docker-compose.build.yml up -d --build
services:
  server:
    build:
      context: .
      dockerfile: server/Dockerfile
    image: sentinel-server:dev

docker compose -f docker-compose.yml -f docker-compose.build.yml up -d --build

To build only:

docker compose -f docker-compose.yml -f docker-compose.build.yml build

Alternatively, from the repo root:

docker build -f server/Dockerfile -t sentinel-server:dev .

4. Traefik (TLS router labels)

Create the external network Traefik expects (often named traefik), then save this merge file as e.g. docker-compose.traefik.yml:

# Merge: docker compose -f docker-compose.yml -f docker-compose.traefik.yml up -d
services:
  server:
    networks:
      - default
      - traefik
    labels:
      - traefik.enable=${TRAEFIK_ENABLE:-true}
      - traefik.docker.network=${TRAEFIK_NETWORK:-traefik}
      - traefik.http.routers.sentinel.rule=Host(`${TRAEFIK_HOST:-sentinel.example.com}`)
      - traefik.http.routers.sentinel.entrypoints=${TRAEFIK_ENTRYPOINT:-websecure}
      - traefik.http.routers.sentinel.tls=true
      - traefik.http.routers.sentinel.tls.certresolver=${TRAEFIK_CERTRESOLVER:-cloudflare}
      - traefik.http.services.sentinel.loadbalancer.server.port=9000

networks:
  traefik:
    external: true

docker network create traefik
docker compose -f docker-compose.yml -f docker-compose.traefik.yml up -d

In .env, set e.g. TRAEFIK_HOST=your.domain.example and align TRAEFIK_ENTRYPOINT / TRAEFIK_CERTRESOLVER with your Traefik static config. You can clear or change PUBLISH_PORT if you only expose the app through Traefik (see section Docker Compose on Configuration).

Keep ENFORCE_HTTPS=true (default in full reference) so the server trusts X-Forwarded-Proto: https from the proxy.

Point agents at wss://your.domain.example/ws/agent when the public URL is HTTPS.

Note: sentinel-agent expects a wss:// WebSocket URL when using TLS in front.

5. Health check

curl -sS -o /dev/null -w "%{http_code}" http://127.0.0.1:9000/healthz

Expect 200. The server image defines a Docker HEALTHCHECK on /healthz.

Docker image

The image is built from server/Dockerfile (multi-stage: frontend build, Rust build, slim runtime). See Build the server image from this repository above for docker build / Compose merge.