opschain server configure

Included from Basic tier

Write the server's configuration and key material to $OPSCHAIN_HOME/server/config.yaml and server/keys.env (0600). A bare invocation bootstraps a complete runnable configuration: listen, store and blob-root defaults plus generated token-secret and column-encryption keys — so opschain server configure && opschain server start is a working server.

The command is idempotent:

• Existing keys are never regenerated. A key already in keys.env is kept even when the same-named environment variable now differs (the report says so explicitly).
• A missing key is adopted from the environment when the same-named variable is set, and generated otherwise.
• An existing config value is only replaced by an explicitly passed flag; otherwise it is kept. Empty fields fall to their defaults.

Each value is reported with its provenance — flag, kept, default, generated or adopted from the environment:

opschain server configure
writing /home/op/.local/share/opschain/server/config.yaml:
  listen:    127.0.0.1:8443 (default)
  store:     /home/op/.local/share/opschain/opschain.db (default)
  blob_root: /home/op/.local/share/opschain/blobs (default)
  note: the store is the embedded SQLite file — a development harness (loopback bind by default, no sign-in, no web GUI).
        To evaluate the full server (PostgreSQL, the server and the web GUI in one command) run the go-opschain Docker Compose:
        ./configure && docker compose up. To point this binary at that database instead, persist its DSN:
        opschain server configure --store postgres://opschain@localhost:5432/opschain
        with PGPASSWORD=<the value ./configure wrote to the compose's .env> in server/keys.env. See opschain docs storage.
writing /home/op/.local/share/opschain/server/keys.env (0600):
  OPSCHAIN_TOKEN_SECRET_KEY: generated
  OPSCHAIN_PRIMARY_KEY: generated
  OPSCHAIN_DETERMINISTIC_KEY: generated
  OPSCHAIN_KEY_DERIVATION_SALT: generated

New key material was generated. Back up /home/op/.local/share/opschain/server/keys.env now:
losing the column-encryption keys makes encrypted database values unrecoverable.

When the config file carries deploy-authoritative blocks this command does not manage (enable_basic_auth, the ldap: block), the report lists them as kept and names the environment variables that win over them per key.

Whenever the store it persists is the embedded SQLite file (the default), the report carries the note: above: that server is a development harness — loopback-bound, no sign-in, no GUI — and the one-command way to evaluate the full server is the go-opschain Docker Compose, whose PostgreSQL answers postgres://opschain@localhost:5432/opschain with the PGPASSWORD its ./configure wrote to the compose's .env. The hint names the DSN only; the password belongs in server/keys.env, from where every parameter missing from the DSN resolves. A postgres:// store prints no note. See opschain docs storage ("Evaluating the full server").

Flags

Flag	Meaning
--listen <host:port>	Listen (bind) address to persist. Default 127.0.0.1:8443 — loopback; on the embedded SQLite store a non-loopback address is honoured at start-up but called out in the startup notice.
--store <path or DSN>	Store to persist: a SQLite database path, or a postgres:// DSN. Parameters absent from the DSN fall back to the standard PG* environment variables, so postgres:// with credentials in keys.env is the recommended form. Default: <opschain home>/opschain.db.
--blob-root <dir>	Blobstore root to persist. Default: <opschain home>/blobs.
--tls-cert <file>	TLS certificate file to persist (the server's own HTTPS; set both TLS values).
--tls-key <file>	TLS private key file to persist.
--dry-run	Print the full provenance report without writing anything.
--template	Print an annotated config.yaml template covering every supported key to stdout, then exit — writes nothing. This is the config catalog: opschain server configure --template > config.yaml.

--template short-circuits everything else: no home resolution, no reads, no writes. The template documents the full key set — listen, store, blob_root, tls_cert/tls_key, enable_basic_auth, the ldap: block, logging: (file mode with rotation), retention:, agents:, metrics:, vault: (AGE file store, OpenBao or HashiCorp Vault), security: (the identity-security posture), auth:, database: maintenance and eula: — with placeholder values only. The running server serves the same catalog at GET /api/admin/config.

What this command does NOT manage

• enable_basic_auth, ldap:, logging:, retention:, agents:, metrics:, vault:, security:, auth:, database: and eula: are edited in config.yaml by hand (start from --template). Existing values are preserved by this command.
• Secrets beyond the four generated keys: the LDAP bind password lives in the ldap: block or OPSCHAIN_LDAP_PASSWORD; vault credentials live in the vault: block.
• OS-service registration — server install is reserved for that.

Exit codes

Code	Meaning
0	Configuration written (or --dry-run / --template printed).
1	The home, config or keys file could not be read or written, or key generation failed.
2	Usage error — unknown flag or stray argument.

See also

• opschain docs cli/server-start — the precedence the written file takes at runtime (file < environment < flags).
• opschain docs cli/server-backup — keys.env is NOT in a backup; back it up separately.