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)
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.

Flags

Flag	Meaning
--listen <host:port>	Listen address to persist. Default 127.0.0.1:8443.
--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.