# Scribe 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](/docs/tutorials/01-minimal-server.md) | One plaintext storage server and a two-client round trip | `setup --variant storage`, `up`, `down` |
| [2. Add authentication](/docs/tutorials/02-add-auth.md) | TLS, auth, users, and repository roles | `add auth`, `access` |
| [3. Scale with a gateway](/docs/tutorials/03-add-gateway.md) | Two stores behind one client endpoint | `add gateway`, `setup` for a second store, `repo list` |
| [4. Operate the cluster](/docs/tutorials/04-use-ctl.md) | 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](/docs/tutorials/05-start-web-interface.md) | 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](/docs/manual/bare-metal.md) 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](/docs/manual.md)
grow the same deployment with the executables themselves, on [bare
metal](/docs/manual/bare-metal.md) or with [Docker Compose](/docs/manual/docker-compose.md),
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):

```sh
./scripts/install.sh            # macOS and Linux
```

```powershell
./scripts/install.ps1           # Windows
```

Put the destination on your PATH; see [build and install](https://github.com/Flying-Rat/scribe/blob/main/README.md#build).
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](/docs/scribe-git-perforce.md) for concepts,
command equivalents, and a Game/Engine example.

| Guide | What you will learn | Prerequisite |
| --- | --- | --- |
| [Work offline](/docs/tutorials/work-offline.md) | Edit without connectivity, reconcile locks and revisions, and submit safely | A synced workspace; the demo continues stage 1 |
| [Work with repository mounts](/docs/tutorials/work-with-mounts.md) | 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](https://github.com/Flying-Rat/scribe/blob/main/README.md#cli-references): every command, flag, and default.
- [Cluster guide](/docs/cluster-usage.md): the definition file, setup, add, upgrade, renew, Docker, and remote operation.
- [Run Scribe by hand](/docs/manual.md): the same stages without `scribe-ctl`, on bare metal or with Docker Compose, and the web interface.
- [Client workflows](/docs/client-usage.md): local changes, recovery, locking, and compression.
- [Authentication](/docs/auth.md): the complete role model, trust, credentials, and revocation.
- [Gateway guide](/docs/gateway-usage.md): placement rules and scaling limits.
- [Operations](/docs/operations.md): health, shutdown, capacity, and backups.
- [Troubleshooting](/docs/troubleshooting.md): diagnose failures without discarding state.
- [Certificates and credentials](/docs/manual/certificates.md): renew credentials and certificates, rotate CAs.
- [Upgrades by hand](/docs/manual/upgrades.md): explicit migrations without `scribe-ctl`.
- [Production deployment](/docs/production-deployment.md): prepare for team access and automatic startup.

Start with [1. Minimal server](/docs/tutorials/01-minimal-server.md).

For branch integration after setup, follow the [backport example](/docs/cherry-pick.md)
and [partial-view merge walkthrough](/docs/partial-view-merging.md). The latter
explains how a source-only workspace handles changes and conflicts in excluded
assets. [Proposals](/docs/proposals.md) covers the optional web review workflow.