Skip to content

Help wiki Running a server

Server configuration and operations

Storage, HTTPS, authentication, rule reloads and recovery for operators.

Storage and configuration

The container reads /etc/kabacus/server.toml and uses /data/books.kabacus by default, creating it on first start. Mount persistent data outside the image. Choose SQLite with database or PostgreSQL with database_url; KABACUS_DATABASE can override the database location. Both backends use shared accounting rules.

Connect clients

Configure [remote] for the HTTPS listener, certificates and trust. Clients use Connect to a Server… and can supply a private CA. The same API and /mcp operations are available over the remote listener. If serving the web app, configure web_dir and use /app/. The web application requires an appropriate provider redirect URI and CORS configuration; never put a client secret into browser code.

Authentication and authorization

For shared or remote books, configure an OIDC issuer and role mapping. Local authentication-off mode is explicit and restricted to a unix socket or loopback; never use it as a fallback when OAuth fails. ledger-read, ledger-write and ledger-rewrite distinguish visibility, normal bookkeeping and gated rewrites. Configure the claim and role_map for the provider’s actual token shape.

MCP clients authenticate independently with bearer tokens and protected-resource metadata. Behind a reverse proxy, configure [mcp] resource_url and required scopes for the externally reachable endpoint. Test both ordinary app access and MCP role enforcement.

Account-kind configuration

Account kinds come from ordered account_kinds rules: the first match wins. * matches a segment or part of one, ** matches one or more. Supplying any custom table replaces the defaults, so include every rule the books need. SIGHUP reloads the configuration. card_reserve_account supplies the reserve path pattern, normally assets:bank:checking:card-{card}.

Operate and recover

  • Keep the data volume writable and the rest of the container read-only where practical. An isolated unix-socket deployment can use --network none; a remote HTTPS deployment needs its listener reachable.
  • Collect request logs from stderr, or the systemd journal when its socket is mounted. Keep credentials and book contents out of public logs.
  • Back up consistently using the database’s backup tooling and verify restoration in isolation. A running SQLite database can have a WAL; a plain file copy is not sufficient.
  • After restoration or migration, make clients refresh and preview again against the restored revision.
  • Use the container README for the exact supported configuration keys, volumes, migration and launch commands in the installed version.