Staging Guide

This staging setup is fully Dockerized. The backend, frontend, database, and observability services all run under docker-compose.staging.yml.

Why this staging shape

one command starts the full stack
no per-worktree systemd unit is required
the running services match the current checkout more closely
SSH port forwarding stays simple and predictable

Default ports

Frontend: 3002
Backend API: 8000
PostgreSQL: 5433
Prometheus: 9091
Grafana: 3001
pgAdmin: 5051 when the admin profile is enabled

First-time server bootstrap

Run this once on a fresh staging server:

cd /home/to/dir/scripts/staging
chmod +x *.sh
./bootstrap_server.sh
newgrp docker

Required env for a typical staging run

In .env, set at least:

DB_NAME=freeinference_db
DB_USER=postgres
DB_PASSWORD=...
JWT_SECRET_KEY=...
API_KEY_SECRET=...

NEXT_PUBLIC_DEPLOY_TARGET=staging
NEXT_PUBLIC_API_BASE=http://localhost:8000
BACKEND_PORT=8000
FRONTEND_PORT=3002
CORS_ALLOWED_ORIGINS=http://localhost:3002,http://localhost:3001,http://localhost:3000

USER_AUTH_ENABLED=1
SIGNUP_ENABLED=1
SIGNUP_REQUIRE_APPROVAL=0
SIGNUP_REQUIRE_EMAIL_VERIFICATION=0

If you want admin bootstrap on login, also set:

ADMIN_EMAILS=you@example.com

Start staging

cd /path/to/dir
make staging-up

This command:

pulls prebuilt infra images
builds the current backend and frontend from the worktree
starts the full staging stack with Docker Compose

You can still use start_staging.sh directly, but make staging-up is the recommended day-to-day entry point.

SSH forwarding

From your laptop:

ssh -L 3002:127.0.0.1:3002 -L 8000:127.0.0.1:8000 <user>@staging-internal

If using VScode-family IDE, setting forwarded ports in IDE GUI is more convenient.

Then open:

http://localhost:3002

The staged frontend is built to talk to:

http://localhost:8000

Common operations

Restart the full staging stack:

make staging-build

Tail backend logs:

make staging-logs s=backend

Show staging container status:

make staging-ps

Restart a single staging service:

make staging-restart s=frontend

Reset the staging database completely:

docker compose -f infrastructure/docker/docker-compose.staging.yml --env-file .env down -v
make staging-up

Notes for model monitor

the monitor UI requires an internal or admin user
llm-prober is not part of the staging compose file today, so direct-baseline panels may show an unavailable state
routed traffic panels still work without llm-prober