Getting started

Requirements

A Linux host (Ubuntu-based recommended) with Docker and the Compose plugin
git, curl, jq, and htpasswd (the bootstrap installs them when missing)
A GitHub token that can manage runners for every organization in orgs.conf — see GitHub token for how to create one (classic PAT with admin:org, or a fine-grained token for a single organization)

One-command install

On a fresh Ubuntu host:

bash

curl -fsSL https://raw.githubusercontent.com/blendsdk/build-server/main/bootstrap.sh | bash -s --

The installer installs prerequisites, fetches the repository into a temporary clone, installs only the runtime files into $HOME/build-server, asks for the GitHub token and a registry password (or reads them from the environment), writes .env, generates a deploy SSH key, creates empty credential placeholders, writes the registry htpasswd, builds the runner image, and starts the fleet. Development files (tests, docs, git metadata) never reach the install directory.

Useful flags and variables:

Flag / variable	Effect
`--no-start`	Configure everything but do not build or start
`--non-interactive`	Never prompt; all values must come from the environment
`--token`	Fetch over HTTPS using `ACCESS_TOKEN` (default)
`--ssh`	Fetch over SSH using an existing key (`SSH_KEY`, default `~/.ssh/id_rsa`)
`--generate-ssh-key`	Generate the key when missing, install the public key on GitHub, then fetch over SSH
`--orgs "A B"`	Organizations to serve; each is verified against GitHub. Interactive installs are prompted
`--keep-orgs`	Keep the existing `orgs.conf` and skip the prompt
`--slim`	Remove `.git` and development files from a legacy full checkout
`ACCESS_TOKEN`	GitHub token (required — also used for runner registration)
`ORGS`	Space- or comma-separated organization names (unattended equivalent of `--orgs`)
`REGISTRY_USER`, `REGISTRY_PASS`	Registry credentials (`ci` and a generated password by default)
`REGISTRY_HTTP_SECRET`	Registry signing secret (generated when absent)
`REGISTRY_PORT`	Host port for the registry (default 5000; the installer picks a free port when 5000 is taken)
`INSTALL_DIR`	Install location (default `$HOME/build-server`)
`GIT_AUTH`	`token` (default) or `ssh`; flags win over the variable
`SSH_KEY`	Key used for the fetch (default `~/.ssh/id_rsa`)
`REPO_SSH_URL`	Explicit SSH URL when it differs from the `REPO_URL` derivation

Re-run the same command any time to update the runtime files and fleet. The install records its revision in .build-server-version (shown by ./fleet.sh status) and keeps a manifest of the installed files, so files renamed upstream are cleaned up on update. Your data — .env, orgs.conf, registry/, ssh/, credentials, and context directories — is never touched.

The installer asks which organizations to serve and verifies each by minting a runner registration token — the same permission the fleet needs. It then writes orgs.conf, builds the default image and every custom-context image, and starts the fleet. If host port 5000 is already taken, it selects the next free port for the registry and records it as REGISTRY_PORT in .env.

Re-running the installer is safe and self-healing: it reuses values already in .env, regenerates registry/auth/registry.password whenever the credentials no longer match, and records any missing registry keys. Existing installs that predate the registry-credential support are repaired by a single re-run.

Repository access

The repository can be fetched with the token or with SSH:

bash

# HTTPS + token (default)
curl -fsSL https://raw.githubusercontent.com/blendsdk/build-server/main/bootstrap.sh | bash -s --

# SSH with your existing key
curl -fsSL https://raw.githubusercontent.com/blendsdk/build-server/main/bootstrap.sh | bash -s -- --ssh

# SSH with a new key that the installer registers on GitHub
curl -fsSL https://raw.githubusercontent.com/blendsdk/build-server/main/bootstrap.sh | bash -s -- \
  --generate-ssh-key

Notes:

--ssh uses SSH_KEY (default ~/.ssh/id_rsa) and adds the host to known_hosts.
--generate-ssh-key requires a token with the classic write:public_key scope (fine-grained: Git SSH keys: Read and write); without it the installer prints the public key and the manual step instead.
The key lives in ~/.ssh, which ./fleet.sh build stages into the runner image so jobs can clone private repositories over SSH.
ACCESS_TOKEN is required in every mode: it mints runner registration tokens.

Manual setup

bash

git clone https://github.com/blendsdk/build-server.git
cd build-server

cp .env.example .env          # set ACCESS_TOKEN and REGISTRY_HTTP_SECRET
cp ~/.npmrc .npmrc            # credentials your builds need (optional)
cp ~/.yarnrc .yarnrc
cp ~/.bunfig.toml .bunfig.toml
cp ~/.docker/config.json config.json

mkdir -p registry/auth registry/data
docker run --rm --entrypoint htpasswd httpd:2 -Bbn "$REGISTRY_USER" "$REGISTRY_PASS" \
  > registry/auth/registry.password

./fleet.sh build
./fleet.sh up
./fleet.sh status

Try it without a server

bash

bash examples/playground.sh              # sandbox with stub docker/curl
bash examples/playground.sh run generate
bash examples/playground.sh run status

Getting started ​

Requirements ​

One-command install ​

Repository access ​

Manual setup ​

Try it without a server ​

Next steps ​

Getting started

Requirements

One-command install

Repository access

Manual setup

Try it without a server

Next steps