Deployment tutorials

Build one deployment in five stages with scribe-ctl, the operations tool. Start with a single storage server and two working copies, add identity and access control, spread repositories across two stores behind a gateway, operate and upgrade the cluster, then run the web interface in Docker. Stages 1–4 grow one cluster: each keeps the repositories of the previous stage.

Stage	What you will build	`scribe-ctl` commands
1. Minimal server	One plaintext storage server and a two-client round trip	`setup --variant storage`, `up`, `down`
2. Add authentication	TLS, auth, users, and repository roles	`add auth`, `access`
3. Scale with a gateway	Two stores behind one client endpoint	`add gateway`, `setup` for a second store, `repo list`
4. Operate the cluster	Status, health, files, logs, inventory, renewal and CA rotation, an upgrade, other machines	`status`, `doctor`, `where`, `logs`, `df`, `renew`, `upgrade`, `--remote`, `adopt`
5. Start the web interface	A Docker cluster with the web interface; browser sign-in	`setup --runtime docker --web`, `up`

Why scribe-ctl from the first stage

Stage 1 could start scribe-server by hand, and the bare-metal guide shows how. The tutorials use scribe-ctl from the start because the cluster then grows in place: add auth and add gateway change the same definition file and keep every repository, the controller records the executables so upgrade can switch releases later, and every stage ends with one command to start and one to stop. Nothing is hidden: each stage has a What scribe-ctl did for you section that names the files and explains the concepts (the data root, the two certificate authorities, the auth pepper and revision witness, credentials, grants, the gateway's service account). To do a stage by hand instead, the manual guides grow the same deployment with the executables themselves, on bare metal or with Docker Compose, stage by stage, with the same files.

Install

From a source checkout, the installation script builds all six executables in release mode and installs them for your user (~/.local/bin, or %LOCALAPPDATA%\Scribe\bin on Windows):

./scripts/install.sh            # macOS and Linux

powershell

./scripts/install.ps1           # Windows

Put the destination on your PATH; see build and install. Keep the executables together: scribe-ctl finds the services beside itself.

The script can also hand over to scribe-ctl in the same line, which is stage 1's first step: ./scripts/install.sh --setup storage --config ~/scribe-demo/scribe-cluster.toml.

Working directory and ports

Use a fresh scribe-demo directory outside any Scribe workspace. Unless a step says otherwise, run commands from that directory; every new terminal must change to it. The examples use a Unix shell on macOS or Linux. Windows users need equivalent directory, environment, and file-editing steps; the tutorials do not establish Windows test coverage.

Use a shell without unrelated SCRIBE_* connection, credential, or configuration overrides. From stage 2, the examples use separate clients/alice and clients/bob configuration directories, so two demo users on one OS account do not replace each other's saved sessions.

scribe-ctl uses these default ports. If one is taken, add --port-offset N to stage 1's setup (every port moves by N; later stages follow) and adjust the client commands:

Service	Address
Auth, from stage 2	`127.0.0.1:7443`
Storage A	`127.0.0.1:7447`
Storage B, from stage 3	`127.0.0.1:7448`
Gateway, from stage 3	`127.0.0.1:7557`
Web interface, stage 5	`http://localhost:8080` (bound to `127.0.0.1`)

Keep the whole deployment folder private. Password, pepper, private-key, and credential-file contents never belong in shell arguments, logs, or version control. Each stage names the files a process reads; none asks you to print one.

Outputs in the tutorials are real, from a run on macOS, shown with the default ports and with paths under /home/you; ... marks lines left out.

Workspace tutorials

These guides cover daily work and do not require completing all deployment stages.

Coming from another version-control system? Start with the Scribe, Git, and Perforce comparison for concepts, command equivalents, and a Game/Engine example.

Guide	What you will learn	Prerequisite
Work offline	Edit without connectivity, reconcile locks and revisions, and submit safely	A synced workspace; the demo continues stage 1
Work with repository mounts	Edit parent files, publish engine/game changes together, adopt pins, select optional art, and recover interruptions	A parent repository with configured mounts and a programmer profile

Finding details after the walkthrough

CLI references: every command, flag, and default.
Cluster guide: the definition file, setup, add, upgrade, renew, Docker, and remote operation.
Run Scribe by hand: the same stages without scribe-ctl, on bare metal or with Docker Compose, and the web interface.
Client workflows: local changes, recovery, locking, and compression.
Authentication: the complete role model, trust, credentials, and revocation.
Gateway guide: placement rules and scaling limits.
Operations: health, shutdown, capacity, and backups.
Troubleshooting: diagnose failures without discarding state.
Certificates and credentials: renew credentials and certificates, rotate CAs.
Upgrades by hand: explicit migrations without scribe-ctl.
Production deployment: prepare for team access and automatic startup.

Start with 1. Minimal server.

For branch integration after setup, follow the backport example and partial-view merge walkthrough. The latter explains how a source-only workspace handles changes and conflicts in excluded assets. Proposals covers the optional web review workflow.