# Environment variables

> The configuration variables an operator sets in production.

_Updated: 2026-06-10_

Railbase is configured by flags, environment variables, and built-in defaults, in
that precedence order (**flag > env > default**). This page lists the variables an
operator typically sets; for the matching flags see the [CLI reference](cli).

## Core server

| Variable | Default | Purpose |
|---|---|---|
| `RAILBASE_HTTP_ADDR` | `:8095` | HTTP listen address |
| `RAILBASE_DATA_DIR` | `./pb_data` | Data directory |
| `RAILBASE_HOOKS_DIR` | `./pb_hooks` | Where `*.pb.js` [hooks](hooks) load from |
| `RAILBASE_PROD` | `false` | Production mode (disables dev conveniences) |
| `RAILBASE_LOG_LEVEL` | `info` | `debug` · `info` · `warn` · `error` |
| `RAILBASE_LOG_FORMAT` | `text` | `text` or `json` |
| `RAILBASE_SHUTDOWN_GRACE` | `15s` | Graceful-shutdown timeout |

## Vault (data & encryption)

| Variable | Default | Purpose |
|---|---|---|
| `RAILBASE_VAULT_PATH` | `<data-dir>/railbase.vault` | Vault file location |
| `RAILBASE_VAULT_PASSWORD` | — | Unlock password (**required in production**) |
| `RAILBASE_VAULT_PASSWORD_FILE` | — | File holding the password (preferred for systemd / secrets) |
| `RAILBASE_VAULT_CACHE_MB` | `1024` | Vault page-cache size, MB |
| `RAILBASE_BACKUPS_DIR` | `<data-dir>/backups` | Where snapshots are written |
| `RAILBASE_ENCRYPT_STORAGE` | `false` | Encrypt uploaded files at rest |

> [!IMPORTANT]
> In production (`RAILBASE_PROD=true`) Railbase refuses to start without a vault
> password — it will not fall back to the development key. Prefer
> `RAILBASE_VAULT_PASSWORD_FILE` over the plain variable.

## Marketplace & static assets

| Variable | Default | Purpose |
|---|---|---|
| `RAILBASE_PLUGIN_MANAGER` | _(on)_ | The marketplace / plugin manager is built in and enabled by default. Set to `0` to disable it. |
| `RAILBASE_PUBLIC_DIR` | _(empty)_ | Directory of static assets to serve at `/` (empty disables) |

## Networking & access

| Variable | Purpose |
|---|---|
| `RAILBASE_TRUSTED_PROXIES` | CIDR list whose `X-Forwarded-For` is trusted (set this behind a proxy) |
| `RAILBASE_ALLOW_IPS` / `RAILBASE_DENY_IPS` | CIDR allow / deny filters |
| `RAILBASE_CORS_ALLOWED_ORIGINS` | Permitted browser origins |
| `RAILBASE_ADMIN_URL` | Base URL used in admin/bootstrap emails |

## A production starting point

```ini
RAILBASE_PROD=true
RAILBASE_HTTP_ADDR=:8095
RAILBASE_DATA_DIR=/var/lib/railbase
RAILBASE_VAULT_PASSWORD_FILE=/run/secrets/railbase-vault
RAILBASE_TRUSTED_PROXIES=127.0.0.1/32
RAILBASE_LOG_FORMAT=json
```

> [!NOTE]
> Older material may mention `RAILBASE_DSN`, `RAILBASE_EMBED_POSTGRES`, or
> `RAILBASE_EMBED_PG_PORT`. Railbase has **no external/embedded database** — those
> variables are not read by the current runtime. Data lives in the vault file; see
> [Data & multi-tenancy](data-and-tenancy).

Subsystems (mailer, OAuth, storage, metrics, …) have their own `RAILBASE_*`
variables; run `railbase config list` to see what's active on your instance.