Accounts and day-to-day operations

Manage accounts

Accounts are administered with oxysdb-server subcommands, run where the server’s store is reachable (in compose: docker compose -f FILE exec -T server-1 oxysdb-server …; in Kubernetes: kubectl exec deploy/<release> -- oxysdb-server …). They use the same store options as serve.

Open sign-up (--allow-sign-up, OXYSDB_SERVER_ALLOW_SIGN_UP, Helm server.allowSignUp) lets anyone who reaches the URL create an account. Such accounts receive nothing addressed to them until you run verify-account, because someone else could have registered the address first. Use --trust-sign-up only where addresses are controlled elsewhere (single sign-on in front, internal network).

Health checks

Logs

--log-format json (OXYSDB_SERVER_LOG_FORMAT=json, OXYSDB_RUNNER_LOG_FORMAT; Helm default json) writes one JSON object per line to standard error (ts, level, msg, fields). Logs never contain passwords, tokens or connection strings.

Metrics

Off by default and never sent anywhere. --metrics-listen 0.0.0.0:9464 (server) or :9465 (runner) serves Prometheus text on GET /metrics, on its own plain-HTTP listener: expose it to your scraper only (the chart’s NetworkPolicy does).

Graceful stop

On SIGTERM, readiness fails at once and no new connection is accepted. Requests in flight get OXYSDB_SERVER_SHUTDOWN_GRACE_SECS (default 20), then store work under way up to 30 s more. The runner lets the run in progress finish within OXYSDB_RUNNER_SHUTDOWN_GRACE_SECS (default 20), releases its leader lease and leaves; a run still going is recorded interrupted.

Abuse limits

Post-quantum TLS

--tls-pq prefer (default) or require, on both programs (OXYSDB_SERVER_TLS_PQ, OXYSDB_RUNNER_TLS_PQ): require accepts only the post-quantum key exchange X25519MLKEM768, so switch to it once every desktop is upgraded (TLS). The option needs --tls-cert and --tls-key: a program serving plain HTTP behind a TLS proxy refuses to start with it (set the key exchange on the proxy instead).

Runner settings worth knowing

oxysdb-runner init creates a new access token, prints it once and keeps only its SHA-256; running it again replaces the previous token.

Diagnostics for a bug report

oxysdb-server diagnose and oxysdb-runner diagnose print a redacted bundle on standard output: the version, the platform, the configuration without secrets (the database URL keeps its hosts, its user name and password read ****; the master password, token and TLS files appear only as a path or a variable name), the store read read-only (counts, quotas, locks; for the runner its manifest, leases and latest runs), the database server’s version and the readiness probe. They take the same options and variables as serve, plus --format text|json. Nothing is sent: read the output, then paste what you choose into the issue.

kubectl -n oxysdb exec deploy/oxysdb -- oxysdb-server diagnose
kubectl -n oxysdb exec statefulset/oxysdb-oxysdb-runner -- oxysdb-runner diagnose --format json
docker compose -f compose.single.yaml exec server oxysdb-server diagnose

Both services log to standard error only: add the last lines of kubectl logs or docker compose logs yourself.

Troubleshooting