Install with Docker Compose

Postgres, Redis and the console on one machine — the fastest real deployment.

git clone https://github.com/wccdev/starforge && cd starforge
./deploy/up-prod.sh

That script copies .env.example to .env, generates the passwords and the JWT secret that are still template values, and brings the stack up. It is idempotent — run it again after editing .env.

What comes up

Service	Image	Why
postgres	timescale/timescaledb:latest-pg18	The ledger. TimescaleDB because metric and hardware points are hypertables
redis	redis:latest	Shared cache, distributed locks, rate limiting, immediate token revocation
app	starforge-console:latest	FastAPI plus the built console, served from one image

Postgres must start with shared_preload_libraries=timescaledb, which the compose file sets. A data volume first initialised by plain postgres will not have it in postgresql.conf, and the hypertable migrations then fail. Start from a fresh volume, or add the setting by hand.

Before you start

1. Set the storage root

   FORGE_STORAGE_ROOT=/srv/starforge
   

   Compose bind-mounts it at the same path inside the container. That is not cosmetic: with the local executor the console drives the host Docker daemon, so the left side of a -v flag is a host path. If the two differ, the console cannot see what jobs write.

2. Give the container the docker group

   getent group docker | cut -d: -f3     # put the number in DOCKER_GID
   

   The console runs as uid/gid 10001 and needs to write /var/run/docker.sock.

3. Decide about GPUs

   The compose file requests gpus: all so the NVIDIA toolkit injects nvidia-smi and the driver libraries — the console can see the cards without holding them.

   On a machine with no NVIDIA runtime, delete gpus: all and the NVIDIA_DRIVER_CAPABILITIES line, then set FORGE_LOCAL_GPU_COUNT explicitly.

4. Start it

   docker compose up -d --build
   docker compose logs -f app
   

Internal DNS names

A container does not read the host’s /etc/hosts. If your OIDC provider or image mirror resolves only through it, add the mappings:

cp docker-compose.override.example.yml docker-compose.override.yml
# edit extra_hosts, taking IPs from `getent hosts <name>` on the host
docker compose up -d --force-recreate app

Recommended configuration

Everything else has a working default. These do not.

.env

FORGE_DEFAULT_FLEET_KIND=local
FORGE_STORAGE_ROOT=/srv/starforge
FORGE_PUBLIC_URL=https://starforge.your-company.com
FORGE_WEB_JWT_SECRET=<openssl rand -hex 32>
FORGE_DB_URL=postgresql+psycopg://forge:<password>@postgres:5432/forge
FORGE_REDIS_URL=redis://:<password>@redis:6379/0
FORGE_INGEST_URL=http://<host reachable from a training container>:8080

FORGE_INGEST_URL is the one people get wrong. Training containers POST their metrics back to it, and on the local executor they share the host network — so 127.0.0.1 works there but stops working the moment you add a second machine. Use the host’s real address from the start.

The database and Redis hostnames are compose service names, resolvable only inside the starforge-internal network. Bring the whole stack up with compose; a bare docker run of the app image fails with failed to resolve host 'postgres'.

Confirm it worked

curl -s http://localhost:8080/api/version
docker compose ps          # all three healthy

Then open the console. The first visit runs the onboarding that creates the first administrator.

Moving off one machine

Compose with the local backend tops out at one host. When you outgrow it, you register a second Fleet rather than migrating: a node Fleet for several bare-metal boxes, or move the console itself into Kubernetes. The jobs already on the first Fleet stay where they are.