Install with Docker Compose

Every Specbench release publishes versioned container images to GitHub Container Registry, plus a self-host docker-compose.yml that pins them. An install is: download the compose file, compose up, open the browser. No clone, no toolchains, no build.

1. Download and start

The defaults work as-is. To set your own database credentials or ports, write the .env before this first start — the annotated env.example attached to the same release is the starting point (see Data); passwords only take effect on a fresh data volume.

mkdir specbench && cd specbench
curl -LO https://github.com/specbench-io/specbench/releases/latest/download/docker-compose.yml
docker compose up -d

The stack is the whole product — web app, API, and MCP server — on top of Postgres and Redis. Containers and volumes are namespaced specbench-ce-…, so names never clash with other stacks; every host port is overridable if something already owns one (see Ports below).

This start publishes the app on every interface — right for a laptop or a trusted network. On an internet-reachable server, follow Installing on a server instead.

2. Open the app and claim the Instance

Browse to http://localhost:5173. The first person to arrive creates the first user account, which claims the Instance — sign-up closes behind them, and everyone after joins by invitation unless you open registration.

From there, the Quick start applies unchanged.

Versions

Each release ships the three app images under one version tag — ghcr.io/specbench-io/specbench-api:0.4.0 and siblings — and the compose file attached to that release pins those tags. What you download is what you run; nothing moves underneath you. The running version is shown on the Instance admin page. The pin is a default — set SPECBENCH_VERSION in the .env to run a different version than the compose file you downloaded (see Upgrading before rolling in either direction).

Specbench is pre-1.0: a minor version may include breaking changes, always called out in the release notes. Read them before upgrading.

Installing on a server

On a machine reachable from the internet, order matters: the first account created claims the Instance, so don't leave an unclaimed Instance exposed while you fetch your browser. Write the full .env first, make the first start the HTTPS one, and claim immediately:

# .env — before the first `up`
SPECBENCH_POSTGRES_PASSWORD=<generated>
SPECBENCH_REDIS_PASSWORD=<generated>
SPECBENCH_DOMAIN=specs.example.com
SPECBENCH_WEB_ORIGIN=https://specs.example.com
SPECBENCH_APP_BIND=127.0.0.1

If you started from env.example, mind that every line in it ships commented out — a value with its leading # still in place silently falls back to the default. Worth a check before the first start, because the passwords bake into the data volume:

docker compose --profile proxy config | grep specs.example.com

Your domain should appear in both the Caddy config and the API's CORS origin. If the grep comes back empty, the .env isn't reaching Compose — usually a # left in place.

docker compose --profile proxy up -d

Then open https://specs.example.com and create the first account. The proxy profile is the bundled Caddy — DNS and firewall prerequisites, and the bring-your-own-proxy alternative, are on HTTPS and domains. SPECBENCH_APP_BIND=127.0.0.1 keeps the direct app ports off the network; all traffic goes through the proxy.

Ports

Defaults, each overridable via the environment (or a .env next to the compose file) when something already owns a port:

# .env
SPECBENCH_POSTGRES_PORT=5433

Put overrides in the .env rather than inline — an inline variable applies to that one invocation only, and the next plain docker compose command would recreate the container on the default port.

Data

Postgres is the only durable store, on the postgres-data volume — back that volume up and you've backed up the Instance. Redis is deliberately wipeable: no volume, nothing durable ever lives there.

Both listen on localhost only, so they're reachable from the host (psql, backups) but never from the network. To set your own credentials, put SPECBENCH_POSTGRES_PASSWORD and SPECBENCH_REDIS_PASSWORD in a .env next to the compose file before the first start — Postgres sets its password when the volume is first initialised. Every release attaches an annotated env.example listing all the settings:

curl -LO https://github.com/specbench-io/specbench/releases/latest/download/env.example
cp env.example .env

Upgrading

Take a Postgres backup, then fetch the new release's compose file and pull:

curl -LO https://github.com/specbench-io/specbench/releases/latest/download/docker-compose.yml
docker compose pull
docker compose up -d

The API migrates the database on startup. Migrations are forward-only — rolling back a release means restoring the backup you took first.

Building from source

Prefer to build your own images? Clone the repository and run its compose file, which builds the same three images from source:

git clone https://github.com/specbench-io/specbench.git
cd specbench
docker compose --profile full up --build

That file doubles as the development stack (plain docker compose up starts only Postgres and Redis, for pnpm run dev); the published images are the supported install path.

Next

• HTTPS and domains — put the Instance on a real domain, with the bundled Caddy or your own proxy
• Configuration — identity, GitHub App, and the settings that matter beyond localhost