Documentation/Configuration and storage

Configuration and storage#

For a first local trial, follow Getting started. This guide covers persistent storage, configuration precedence and remote deployment.

Commands below assume a source checkout after make build. In an extracted native archive, replace ./bin/open-guardrail with ./open-guardrail.

Configuration#

Precedence: built-in defaults → explicit YAML file → environment → command flags. An explicitly empty environment value overrides the file and is validated.

Setting YAML Environment Default
HTTP address listen OPEN_GUARDRAIL_LISTEN 127.0.0.1:8080
External HTTPS origin public_url OPEN_GUARDRAIL_PUBLIC_URL empty (direct loopback mode)
SQLite directory data_dir OPEN_GUARDRAIL_DATA_DIR ./data
Database backend database.driver OPEN_GUARDRAIL_DATABASE_DRIVER sqlite
Database DSN (PostgreSQL) database.url DATABASE_URL empty
Database pool size database.max_connections — 10
Schema migration mode database.migrations OPEN_GUARDRAIL_DATABASE_MIGRATIONS auto

--listen and --data-dir override corresponding settings. DATABASE_URL requires explicitly selecting postgres. Unknown YAML fields fail validation. Configuration files must contain exactly one YAML document and be at most 1 MiB. Credentials and raw driver errors are excluded from logs and API errors. Non-loopback listening requires an explicit HTTPS public_url (or OPEN_GUARDRAIL_PUBLIC_URL) and a trusted TLS reverse proxy. Do not expose the unencrypted backend directly. The default loopback address needs no proxy.

public_url must be an HTTPS origin with no path, trailing slash, user information, query or fragment. Include a nonstandard port when clients use one, for example https://guardrail.example.com:8443. Configuring a public origin requires the remote bootstrap-token flow even when the backend listener is loopback.

Schema migration mode#

auto applies bundled schema migrations and maintains their execution history before opening the HTTP listener. external uses tables prepared through an external process; it does not run migrations or require migration-version records.

In both modes, opening storage automatically creates the default workspace and project if missing, independently of administrator setup. Existing IDs and names are preserved; no manual initialization SQL or workspace/project configuration is required. The database account needs permission to insert these records when absent.

Readiness checks database connectivity. In external mode, apply schema changes through your database change process. See the runtime storage design.

Docker behind HTTPS#

For a complete Docker Compose deployment with TLS, private backend networking, persistent SQLite storage and first-administrator setup, see Docker deployment. The image uses UID/GID 65532:65532, listens on 0.0.0.0:8080 inside its private network, and stores data in /data. Supply OPEN_GUARDRAIL_PUBLIC_URL; there is deliberately no built-in public origin.

Database choices#

The public distribution supports SQLite and PostgreSQL. SQLite targets local evaluation, personal use and a single service instance; PostgreSQL targets shared deployments. Released behavior must expose identical API, state-machine and error semantics on every supported driver and pass a shared conformance suite.

The current model defines identity, Policy, Run expiry, Snapshot Submission, Evidence and Decision semantics across the preview drivers. SQLite is exercised locally; PostgreSQL needs a disposable test instance for its backend suite.

The public capability response reports only the active adapter's support level and verified multi-instance guarantee. It does not reveal the driver name or connection details. All current adapters report multiInstance: false; shared storage is not advertised as multi-instance-ready until the future business invariants pass that conformance boundary.

PostgreSQL configuration#

Use an existing PostgreSQL database and configure the same server:

export OPEN_GUARDRAIL_DATABASE_DRIVER=postgres
export DATABASE_URL='postgres://USER:PASSWORD@HOST:5432/DATABASE?sslmode=verify-full'
./bin/open-guardrail serve

The DSN above is a placeholder. Supply actual credentials using your deployment's secret mechanism; never commit them. A YAML example is available at deploy/config.example.yaml:

./bin/open-guardrail serve --config /etc/open-guardrail/config.yaml

PostgreSQL does not require Docker. Direct installations and managed services work with the same API. Connection and migration failures stop startup; the server never falls back to SQLite. Switching configuration does not migrate existing data.

For remote PostgreSQL connections, configure TLS with certificate verification, as in the sslmode=verify-full example above. The service remains a development preview.