Configuration

The book-keeper service is configured using environment variables. The following sections detail the available variables, their purpose, and their default values.

Core Service Configuration

Variable	Description	Default
LEDGER_STORAGE_BACKEND	The primary storage backend for the ledger. Can be postgres or tigerbeetle.	postgres
EVENT_STORE_BACKEND	The backend for storing domain events.	postgres
EVENTING_BACKEND	The backend for publishing external events. Can be logging, nats, or kafka.	logging
JOURNAL_NAMESPACE_UUID	A stable UUID used to generate deterministic IDs for idempotency keys. Should not be changed in production.	a7a7f8b4-3b7d-4b1e-8b0a-9b7e9b9d8e1a
ENABLE_IN_APP_PROJECTORS	If true, runs read-model projectors within the application process.	true

---

Event Store

These settings configure the backend for the Event Store, which is the source of truth for all domain events.

Variable	Description	Default
EVENT_STORE_BACKEND	The backend for storing domain events. Can be postgres or kurrentdb.	postgres
WRITE_DB_URL	The connection URL for the write-side database. Used when EVENT_STORE_BACKEND is postgres.	postgresql+asyncpg://bookkeeper:changeit@localhost/bookdb
KURRENTDB_URL	The connection URL for the KurrentDB (EventStoreDB) instance. Used when EVENT_STORE_BACKEND is kurrentdb.	esdb://localhost:2113?tls=false

---

Database & Cache

PostgreSQL

Variable	Description	Default
WRITE_DB_URL	The connection URL for the write-side database (event store).	postgresql+asyncpg://bookkeeper:changeit@localhost/bookdb
READ_DB_URL	The connection URL for the read-side database (projection store).	postgresql+asyncpg://bookkeeper:changeit@localhost/bookdb
DB_POOL_SIZE	The number of connections to keep in the connection pool.	10
DB_MAX_OVERFLOW	The number of connections that can be opened beyond DB_POOL_SIZE.	20
DB_POOL_RECYCLE	The number of seconds after which a connection is recycled.	3600

TigerBeetle

Variable	Description	Default
TIGERBEETLE_CLUSTER_ID	The cluster ID of the TigerBeetle cluster.	0
TIGERBEETLE_REPLICA_ADDRESSES	A comma-separated list of TigerBeetle replica addresses.	127.0.0.1:3000
TIGERBEETLE_NAMESPACE_UUID	A UUID used to namespace accounts and transfers within TigerBeetle.	a7a6c1f0-252a-4359-8309-107e7a2ebd4f
TIGERBEETLE_MAX_BALANCE_SUSPENSE_ACCOUNT_CODE	The reserved account code for the suspense account used to enforce max_balance.	sys_max_balance_suspense
TIGERBEETLE_SYSTEM_CODE_MAX_BALANCE	The system code for transfers related to setting up max_balance.	99

Redis (Cache)

Variable	Description	Default
REDIS_URI	The connection URI for the Redis instance.	redis://localhost:6379
BALANCE_CACHE_ENABLED	If true, enables caching for account balance queries.	false
BALANCE_CACHE_TTL_SECONDS	The time-to-live for cached balance entries.	2
IS_SENTINEL_ENABLED	Set to true if using Redis Sentinel for high availability.	false
SENTINELS_URI	Comma-separated list of Sentinel URIs (e.g., redis://host:port,redis://host2:port2).	None
SENTINEL_MASTER_SERVICE	The name of the Sentinel master service.	None

---

Security & Authorization

Authentication (OIDC)

Variable	Description	Default
OIDC_AUTHORITY	The URL of the OIDC provider (e.g., Keycloak, Auth0).	None
OIDC_SCOPE	The OIDC scopes to request during token validation.	openid profile email
CLIENT_ID	The OIDC client ID for this application.	None
OIDC_USERINFO_SUBJECT_CLAIM_NAME	The JWT claim containing the user's unique subject ID.	sub
OIDC_USERINFO_ROLES_CLAIM_NAME	The JWT claim containing the user's roles or permissions.	roles

Authorization

Variable	Description	Default
AUTHORIZATION_ENGINE	The authorization engine to use. Can be casbin, allow_all, or deny_all.	deny_all
CASBIN_MODEL_PATH	The path to the Casbin model configuration file.	book_keeper/infrastructure/authorization/model.conf
CASBIN_POLICY_PATH	The path to the Casbin policy CSV file.	book_keeper/infrastructure/authorization/policy.csv

Multi-Tenancy

Variable	Description	Default
TENANTS_CLAIM_NAME	The JWT claim containing a list of tenants the user can access.	tenants
TENANT_ID_CLAIM_NAME	A fallback claim for tokens with a single tenant ID.	tenant_id
DEFAULT_TENANTS	A comma-separated list of tenants to use if no tenant claims are found in the JWT.	None

---

Eventing

NATS

Variable	Description	Default
NATS_URL	The connection URL for the NATS server.	nats://localhost:4222
NATS_USER	The username for NATS authentication.	None
NATS_PASSWORD	The password for NATS authentication.	None
NATS_STREAM_NAME	The name of the NATS stream to use.	book_keeper_stream
NATS_STREAM_SUBJECT	A list of subjects to subscribe to on the stream.	[]

Kafka

Variable	Description	Default
KAFKA_BOOTSTRAP_SERVERS	A comma-separated list of Kafka broker addresses.	localhost:9092
KAFKA_SECURITY_PROTOCOL	The security protocol to use (e.g., SASL_PLAINTEXT, SSL).	SASL_PLAINTEXT
KAFKA_SASL_MECHANISM	The SASL mechanism for authentication.	None
KAFKA_SASL_USERNAME	The SASL username.	None
KAFKA_SASL_PASSWORD	The SASL password.	None
KAFKA_TOPICS	A list of Kafka topics to publish events to.	["bk.events.JournalEntryPosted"]

---

Feature Flags & System Accounts

Rate Limiting

Variable	Description	Default
RATE_LIMITING_ENABLED	A global flag to enable or disable ledger-based rate limiting.	true
SYSTEM_RATE_LIMITER_DEBIT_ACCOUNT_CODE	The account code for the system's rate limiter debit account.	sys_rate_limiter_debit
SYSTEM_RATE_LIMITER_CREDIT_ACCOUNT_CODE	The account code for the system's rate limiter credit/source account.	sys_rate_limiter_credit
SYSTEM_RATE_LIMITER_AMOUNT	The amount to debit from the limiter account for each action.	1
SYSTEM_RATE_LIMITER_CURRENCY	The currency for the rate-limiter transfer.	USD

General System Accounts

Variable	Description	Default
SYSTEM_COMPOUND_TRANSFER_CONTROL_ACCOUNT_CODE	The account code used as a pass-through control account in atomic many-to-many transfers.	sys_ctrl_compound
SOURCE_OF_ALL_MONEY_ACCOUNT_CODE	The ultimate source of funds for system-level operations (e.g., funding suspense accounts). Configured to allow unlimited debits.	source_of_all_money