Getting started

Requirements

Use Go 1.26 or newer, Node.js 22 or newer, npm, Git, and a reachable Docker-compatible daemon. The server also requires PostgreSQL. A stock local CLI build does not require PostgreSQL; selecting catalog modules does.

Allow several gigabytes for the engine mirror plus additional space for workspaces, compiler caches, and artifacts. Compilation and linking require substantial memory; the example configuration allocates 8 GiB per build.

Run all commands below from the repository root.

Compile locally

cp configs/config.example.yaml configs/config.yaml
make cli
make images

Edit configs/config.yaml before building:

build:
  workspace_mount: "bind"
  image_prefix: "gbb/"

Change these keys in the existing build section, rather than adding a second section. Bind mounts require the daemon to see the same absolute workspace path as the CLI. The example file's volume setting does not transfer an assembled workspace into a remote Docker volume.

./bin/gbb build --local --godot 4.4-stable \
  --platform linuxbsd --arch x86_64 --target editor --out ./out

The first build clones the engine; later builds reuse the mirror and configured ccache volume. Local artifacts are written beneath ./out regardless of the configured server artifact backend. Ctrl-C propagates cancellation to the runner.

For rootless Podman:

systemctl --user enable --now podman.socket
export DOCKER_HOST="unix://$XDG_RUNTIME_DIR/podman/podman.sock"
make images DOCKER=podman IMAGE_PREFIX=localhost/gbb/

Set build.image_prefix: "localhost/gbb/", build.workspace_mount: "bind", and build.container_user: "0:0". Rootless user mapping otherwise prevents the image's builder user from writing the workspace.

Start a development server

Create a development-only PostgreSQL instance:

docker run -d --name gbb-pg -p 127.0.0.1:5432:5432 \
  -e POSTGRES_USER=gbb -e POSTGRES_PASSWORD=gbb \
  -e POSTGRES_DB=gbb postgres:16
export GBB_DATABASE_DSN='postgres://gbb:gbb@localhost:5432/gbb?sslmode=disable'
export GBB_ADMIN_BOOTSTRAP_TOKEN="$(openssl rand -hex 32)"
export GBB_ARTIFACT_BACKEND=fs
export GBB_WORKSPACE_MOUNT=bind
export GBB_COOKIE_SECURE=false
make dev

Copy the example configuration first if you did not do so above. The database password and HTTP cookie override here are for local development. Keep secure cookies enabled on HTTPS deployments.

Open http://localhost:5173. Vite proxies /api and /healthz to the Go server on port 8080. Startup connects to PostgreSQL, applies migrations, and checks required services, including Docker and the selected artifact backend. Fix dependency errors before retrying.

A fresh database has no selectable engine versions. In this legacy development mode, seed one with the bootstrap credential:

curl --fail-with-body http://localhost:8080/api/v1/admin/godot-versions \
  -H "Authorization: Bearer $GBB_ADMIN_BOOTSTRAP_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"name":"Godot 4.4 stable","ref":"4.4-stable","major":4,"minor":4,"is_default":true}'

Use Modules and administration to issue a regular token and register modules. Bootstrap seeding only occurs while the token table is empty.

Run the embedded frontend

make build
./bin/gbb-server -config configs/config.yaml

This builds all three binaries into bin/ and embeds the frontend in the server, which serves it on port 8080. make server alone uses the assets already present in the embed directory.