Installation

Platforms, the binary, flags, and the on-disk layout.

Updated 2026-07-15

Railbase ships as a single statically-linked executable — no runtime to provision and no database server to stand up. The macOS build is signed by Silkway Tech LLC and notarized by Apple, so it runs with no Gatekeeper prompt and no xattr step.

Install

Pick whichever fits — all deliver the same signed binary:

macOS installer (.pkg). Download it from the download page and double-click — a standard wizard installs railbase to /usr/local/bin, no Terminal needed.

Homebrew (macOS / Linux).

brew install railbase/tap/railbase

One-line script (macOS / Linux).

curl -fsSL https://railbase.app/install | sh

Raw binary (any platform). Download the build for your OS/architecture from the download page, then put it on your PATH:

The Railbase download page — Pick your platform, or use the macOS installer / Homebrew.

# macOS / Linux — make it executable, then check it runs
chmod +x ./railbase
./railbase version      # prints version tag, commit, build date, Go version

On Windows, run railbase.exe serve from a terminal.

Running the server

./railbase serve [flags]

The flags you'll use most (each also has an environment-variable equivalent; precedence is flag > env > default):

Flag	Env	Default	Purpose
`--addr`	`RAILBASE_HTTP_ADDR`	`:8095`	HTTP listen address
`--data-dir`	`RAILBASE_DATA_DIR`	`<binary-dir>/pb_data`	Data directory (falls back to `./pb_data` when the binary's own directory isn't writable)
`--vault-path`	`RAILBASE_VAULT_PATH`	`<data-dir>/railbase.vault`	Data file location
`--vault-password`	`RAILBASE_VAULT_PASSWORD`	—	Unlock password (required in production)
`--log-level`	`RAILBASE_LOG_LEVEL`	`warn`	`debug` · `info` · `warn` · `error`

Note

pb_data/ is created next to the executable by default — not in your current directory. When you brew install or use the .pkg, that's beside the installed binary (inside the Homebrew Cellar, or /usr/local/bin), so on a managed install pass --data-dir explicitly to keep your data somewhere stable across upgrades. It only falls back to a ./pb_data in the working directory when the binary's own directory can't be written to.

See the full list in Environment variables and the CLI reference.

On-disk layout

A fresh serve creates a pb_data/ directory (next to the binary — see the note above):

pb_data/
├── railbase.vault     # records/settings/metadata — encrypted MVCC document store
├── railbase.vault.lock# single-process lock (see the CLI note below)
├── .secret            # auto-generated master secret: signs tokens/cookies,
│                       #   seals the audit chain, keys field encryption (back up!)
├── .audit_seal_key    # signing keys for the tamper-evident audit chain
├── .authority_seal_key
├── storage/           # uploaded blobs for File()/Files() fields
├── logs/              # structured application logs
└── backups/           # local snapshots written by `railbase backup`

The lock file enforces one process per vault: CLI commands that open the data file can't run while the server is up — see the CLI reference.

There is no external database. Records, settings and metadata live in the vault file; uploaded blobs live under storage/ unless you point storage at a different directory. Read Data & multi-tenancy for the details.

Caution

The .secret file is the master secret that signs every session/API token, seals the tamper-evident audit chain, and keys field-level encryption. Lose it and all issued tokens are invalidated and field-encrypted values become undecryptable. It is not the vault's at-rest key — that is your vault password (see below); losing the password is what locks you out of the vault itself. Back up both, and keep them out of version control.

Development vs. production

Development — opt into the development key so you can iterate without managing secrets. The first time you run serve at a terminal with nothing configured, Railbase offers a one-time setup choice (use the built-in dev key, or set your own password) and remembers it in pb_data/.vault_password. To skip the prompt — or on a headless start, where there is nothing to prompt — enable the dev fallback explicitly with RAILBASE_DEV=true (or runtime.dev: true in railbase.yaml):
```
RAILBASE_DEV=true ./railbase serve
```
A headless serve/migrate with no password source configured and no dev fallback fails closed: "no vault password configured (set RAILBASE_VAULT_PASSWORD, RAILBASE_VAULT_PASSWORD_FILE, or RAILBASE_DEV=true)".
Production — set a real vault password and turn on production mode:
```
export RAILBASE_PROD=true
export RAILBASE_VAULT_PASSWORD_FILE=/run/secrets/railbase-vault
./railbase serve --addr :8095 --data-dir /var/lib/railbase
```
In production an empty vault password is a hard error — Railbase refuses to start with the dev key.
Important
Production mode will not mint a fresh .secret for you — that master secret must already exist in the data directory, so it is provisioned deliberately and backed up, never silently regenerated. Against a brand-new empty --data-dir the recipe above exits with ".secret missing". Initialize the data directory once without production mode first (this creates the vault and .secret under your real password), back up pb_data/.secret, then run with RAILBASE_PROD=true:
```
# one-time init: mint the vault + .secret under the real password
RAILBASE_VAULT_PASSWORD_FILE=/run/secrets/railbase-vault \
  ./railbase serve --data-dir /var/lib/railbase   # stop once it reports "listening"
cp /var/lib/railbase/.secret /secure/backup/    # keep this safe and out of VCS
```
A data directory restored from a backup already contains .secret, so it skips this step.
Full guidance is in Deployment and Security.

Upgrading the binary

To upgrade the core, replace the executable with a newer build and restart — your pb_data/ is forward-compatible and migrations apply automatically on boot. You can also upgrade in place from the admin; see Updating.

Was this page helpful?Thanks for your feedback!