Configuration

Orisun reads environment variables with the ORISUN_ prefix.

Configuration is shared across release binaries, Docker images, and embedded deployments that call config.InitializeConfig(). If you run the binary directly, set these variables in your shell, process supervisor, service manager, or platform secret store. The compiled defaults come from config/config.yaml.

Bootstrap settings

Variable	Default	Description
ORISUN_ADMIN_BOUNDARY	orisun_admin	Boundary used for admin state.
ORISUN_ADMIN_PASSWORD	changeit	Bootstrap admin password. The default is for local development only; it does not reset an existing user password.

For PostgreSQL, also set:

Variable	Default	Description
ORISUN_PG_HOST	localhost	PostgreSQL host.
ORISUN_PG_PORT	5434	PostgreSQL port.
ORISUN_PG_USER	postgres	PostgreSQL user.
ORISUN_PG_PASSWORD	postgres	PostgreSQL password.
ORISUN_PG_NAME	orisun	PostgreSQL database.
ORISUN_PG_ADMIN_SCHEMA	admin	PostgreSQL schema containing the admin boundary. Application-boundary placements come from the catalog.
ORISUN_PG_SSLMODE	disable	PostgreSQL SSL mode passed to the driver.

For SQLite, set:

Variable	Default	Description
ORISUN_SQLITE_IN_MEMORY	false	Keep all SQLite databases in RAM for the store lifetime; ignore the database directory.
ORISUN_SQLITE_DIR	./data/orisun/sqlite	Directory for per-boundary SQLite database files.
ORISUN_SQLITE_SYNCHRONOUS	FULL	Recommended SQLite durability mode. Use NORMAL only when you explicitly accept the power-loss durability tradeoff.
ORISUN_NATS_CLUSTER_ENABLED	false	Must stay false for SQLite.

Boundary management

Boundaries are defined through the Admin CreateBoundary RPC and stored as lifecycle events in the admin boundary. They do not require a startup boundary list.

For PostgreSQL, ORISUN_PG_ADMIN_SCHEMA identifies the schema that contains the admin boundary:

ORISUN_PG_ADMIN_SCHEMA=admin

Application-boundary names and placements are replayed from the admin catalog. Create them with CreateBoundary; there is no startup application-boundary list. SQLite bootstraps only the admin boundary on a fresh installation. Boundary names must be valid PostgreSQL identifiers even when using SQLite: 1-63 characters, starting with a letter or underscore, then letters, digits, or underscores. This keeps boundary names portable across backends.

Existing storage

Fresh boundaries initialize the current schema directly. Existing storage must use the current or 0.13.0 storage format. Startup upgrades the 0.13.0 version and rejects older and unversioned event stores. No historical boundary discovery runs. To attach restored storage in the current format, call CreateBoundary with its placement.

Server settings

Variable	Default	Description
ORISUN_BACKEND	postgres	All-backends binary selector: postgres or sqlite. Backend-specific binaries fix their backend.
ORISUN_GRPC_PORT	5005	gRPC API port.
ORISUN_GRPC_ENABLE_REFLECTION	true	Enable gRPC reflection for tools such as grpcurl.
ORISUN_GRPC_CONNECTION_TIMEOUT	60s	Server connection timeout.
ORISUN_GRPC_KEEP_ALIVE_TIME	30s	Server keepalive ping interval.
ORISUN_GRPC_KEEP_ALIVE_TIMEOUT	5s	Keepalive ping timeout.
ORISUN_GRPC_MAX_CONCURRENT_STREAMS	10000	Maximum concurrent HTTP/2 streams per connection.
ORISUN_GRPC_MAX_RECEIVE_MESSAGE_SIZE	67108864	Maximum inbound gRPC message size, 64 MB by default.
ORISUN_GRPC_MAX_SEND_MESSAGE_SIZE	67108864	Maximum outbound gRPC message size, 64 MB by default.
ORISUN_GRPC_INITIAL_WINDOW_SIZE	1048576	Fixed HTTP/2 stream flow-control window, 1 MB by default. Automatic window sizing is disabled.
ORISUN_GRPC_INITIAL_CONN_WINDOW_SIZE	1048576	Fixed HTTP/2 connection flow-control window, 1 MB by default. Automatic window sizing is disabled.
ORISUN_GRPC_WRITE_BUFFER_SIZE	65536	gRPC write buffer size.
ORISUN_GRPC_READ_BUFFER_SIZE	65536	gRPC read buffer size.
ORISUN_GRPC_KEEPALIVE_MIN_TIME	5s	Minimum client keepalive interval accepted by the server.
ORISUN_GRPC_KEEPALIVE_PERMIT_WITHOUT_STREAM	true	Allow client keepalive pings without active streams.
ORISUN_ADMIN_PORT	8991	Admin HTTP port.
ORISUN_ADMIN_USERNAME	admin	Bootstrap admin username.
ORISUN_ADMIN_PASSWORD	changeit	Bootstrap admin password.
ORISUN_AUTH_SESSION_TTL	24h	Inactivity timeout for x-auth-token sessions. Successful token use renews the deadline. Must be greater than zero.
ORISUN_LOGGING_LEVEL	INFO	DEBUG, INFO, WARN, or ERROR.
ORISUN_SUBSCRIPTION_IDLE_THRESHOLD	10s	Positive silence threshold since a subscription last received a hint; its watchdog publishes a NATS hint at expiry. No periodic backend reads.

SQLite settings

Set ORISUN_BACKEND=sqlite and ORISUN_SQLITE_IN_MEMORY=true to keep all SQLite boundary databases in RAM, including the admin catalog, users, event data, and projector state. Embedded Go applications can set cfg.Sqlite.InMemory = true before calling embedded/sqlite.Start.

This mode is ephemeral: closing the store or restarting the process discards all SQLite state. Create application boundaries again after starting a fresh store. Each embedded store has independent databases, even when names and directories match. SQLite remains single-node only; NATS clustering is rejected.

Memory mode ignores ORISUN_SQLITE_DIR and creates no SQLite files. Each event or metadata database uses one connection shared by reads and writes, so reads and writes serialize within that database. ORISUN_SQLITE_READ_POOL_SIZE, ORISUN_SQLITE_MMAP_SIZE, and ORISUN_SQLITE_WAL_AUTO_CHECKPOINT do not apply; journals and temporary storage stay in memory regardless of TEMP_STORE. SYNCHRONOUS cannot provide restart or power-loss durability in this mode. The setting controls SQLite storage; embedded NATS still has its separately configured ORISUN_NATS_STORE_DIR.

Variable	Default	Description
ORISUN_SQLITE_IN_MEMORY	false	Keep all SQLite databases in RAM for the store lifetime; ignore the database directory.
ORISUN_SQLITE_DIR	./data/orisun/sqlite	Directory containing one {boundary}.db event-log file and one {boundary}_metadata.db file per boundary. Metadata files hold projector checkpoints, admin users, count caches.
ORISUN_SQLITE_SYNCHRONOUS	FULL	Recommended SQLite synchronous mode. FULL makes acknowledged WAL commits durable across OS crashes and power loss. NORMAL can improve write throughput, but acknowledged commits may be lost until a checkpoint reaches durable storage; use it only as an explicit, measured opt-out.
ORISUN_SQLITE_BUSY_TIMEOUT_MS	5000	Busy timeout for contended SQLite operations.
ORISUN_SQLITE_READ_POOL_SIZE	0	Read pool size. 0 lets Orisun choose a CPU-based default.
ORISUN_SQLITE_CACHE_SIZE	0	SQLite PRAGMA cache_size override: positive values are pages; negative values are KiB. 0 leaves the SQLite default unchanged.
ORISUN_SQLITE_MMAP_SIZE	0	SQLite PRAGMA mmap_size override in bytes. 0 leaves the SQLite default unchanged.
ORISUN_SQLITE_WAL_AUTO_CHECKPOINT	0	WAL auto-checkpoint threshold in pages. 0 leaves the SQLite default unchanged.
ORISUN_SQLITE_TEMP_STORE	MEMORY	SQLite temp-store mode.
ORISUN_SQLITE_PUBLISHER_WAKE_DELAY	5ms	Coalesce notification relay wake-ups after SQLite commits. Set 0s for immediate wake-ups; idle watchdog hints recover missed signals while NATS is healthy.
ORISUN_SQLITE_GC_MAX_BATCH_REQUESTS	128	Maximum save requests flushed by one SQLite group-commit batch. All SDK save methods use the same V2 RPC.
ORISUN_SQLITE_GC_MAX_BATCH_EVENTS	1024	Maximum events flushed by one SQLite group-commit batch. A request that would exceed the cap is carried to the next flush.
ORISUN_SQLITE_GC_MAX_DELAY	0s	Optional wait to fill a SQLite group-commit batch. 0s keeps batching opportunistic.
ORISUN_SQLITE_GC_MAX_PENDING	4096	Per-boundary queued save-request capacity before callers block.
ORISUN_SQLITE_GC_FLUSH_TIMEOUT	30s	Timeout for one SQLite group-commit flush.

PostgreSQL settings

Orisun uses per-boundary group commit plus separate PostgreSQL pools for writes, reads, and admin work. Size the pools' combined open connections below the database connection limit or the PgBouncer pool size.

Variable	Default	Description
ORISUN_PG_LISTEN_ENABLED	true	Use PostgreSQL LISTEN/NOTIFY wake-ups. When disabled, subscriptions rely on their idle watchdogs. Subscription idle watchdogs also publish hints after notification silence; healthy NATS is required.
ORISUN_PG_WRITE_MAX_OPEN_CONNS	25	Write pool open-connection cap.
ORISUN_PG_WRITE_MAX_IDLE_CONNS	10	Write pool idle-connection cap.
ORISUN_PG_WRITE_CONN_MAX_IDLE_TIME	5m	Write pool idle lifetime.
ORISUN_PG_WRITE_CONN_MAX_LIFETIME	30m	Write pool max connection lifetime.
ORISUN_PG_GC_MAX_BATCH_REQUESTS	512	Maximum save requests committed in one PostgreSQL group-commit transaction. All SDK save methods use the same V2 RPC.
ORISUN_PG_GC_MAX_BATCH_EVENTS	1024	Maximum events committed in one PostgreSQL group-commit transaction. A request that would exceed the cap is carried to the next flush.
ORISUN_PG_GC_MAX_DELAY	0s	Optional wait to fill a PostgreSQL group-commit batch. 0s keeps batching opportunistic.
ORISUN_PG_GC_MAX_PENDING	4096	Per-boundary queued save-request capacity before callers block.
ORISUN_PG_GC_FLUSH_TIMEOUT	30s	Timeout for one PostgreSQL group-commit flush.
ORISUN_PG_READ_MAX_OPEN_CONNS	50	Read pool open-connection cap.
ORISUN_PG_READ_MAX_IDLE_CONNS	25	Read pool idle-connection cap.
ORISUN_PG_READ_CONN_MAX_IDLE_TIME	5m	Read pool idle lifetime.
ORISUN_PG_READ_CONN_MAX_LIFETIME	30m	Read pool max connection lifetime.
ORISUN_PG_ADMIN_MAX_OPEN_CONNS	5	Admin pool open-connection cap.
ORISUN_PG_ADMIN_MAX_IDLE_CONNS	2	Admin pool idle-connection cap.
ORISUN_PG_ADMIN_CONN_MAX_IDLE_TIME	5m	Admin pool idle lifetime.
ORISUN_PG_ADMIN_CONN_MAX_LIFETIME	30m	Admin pool max connection lifetime.

NATS settings

Variable	Default	Description
ORISUN_NATS_URL	empty	External JetStream-enabled NATS URL. When set, Orisun connects to it instead of starting embedded NATS.
ORISUN_NATS_SERVER_NAME	orisun-nats-2	Embedded NATS server name. Use a unique value per clustered node.
ORISUN_NATS_PORT	4224	Embedded NATS client port.
ORISUN_NATS_MAX_PAYLOAD	1048576	NATS max payload.
ORISUN_NATS_STORE_DIR	./data/orisun/nats	NATS data directory.
ORISUN_NATS_PUBLISH_ASYNC_MAX_PENDING	8192	In-flight JetStream async publish acknowledgements for admin messaging; does not buffer subscription hints.

Core NATS carries empty transient hints without stream retention or replicas. NATS listeners use the client’s default bounded pending queue; each drain keeps one coalesced pending wake-up. JetStream remains required for leases and admin messaging. Idle watchdog hints trigger ordinary backend drains, so tune the threshold against notification and backend read load. Healthy NATS is required for ongoing subscription delivery.

TLS settings

Variable	Default
ORISUN_GRPC_TLS_ENABLED	false
ORISUN_GRPC_TLS_CERT_FILE	/etc/orisun/tls/server.crt
ORISUN_GRPC_TLS_KEY_FILE	/etc/orisun/tls/server.key
ORISUN_GRPC_TLS_CA_FILE	/etc/orisun/tls/ca.crt
ORISUN_GRPC_TLS_CLIENT_AUTH_REQUIRED	false

Telemetry and profiling

Variable	Default	Description
ORISUN_OTEL_ENABLED	true	Enable OpenTelemetry traces and metrics.
ORISUN_OTEL_ENDPOINT	localhost:4317	OTLP gRPC endpoint.
ORISUN_OTEL_SERVICE_NAME	orisun	Service name attached to exported telemetry.
ORISUN_PPROF_ENABLED	false	Enable pprof.
ORISUN_PPROF_PORT	6060	pprof port.

Cluster settings

Variable	Default
ORISUN_NATS_CLUSTER_ENABLED	false
ORISUN_NATS_CLUSTER_NAME	orisun-nats-cluster
ORISUN_NATS_CLUSTER_HOST	0.0.0.0
ORISUN_NATS_CLUSTER_PORT	6222
ORISUN_NATS_CLUSTER_ROUTES	nats://0.0.0.0:6223,nats://0.0.0.0:6224
ORISUN_NATS_CLUSTER_USERNAME	nats
ORISUN_NATS_CLUSTER_PASSWORD	password@1
ORISUN_NATS_CLUSTER_TIMEOUT	1800s

Clustered Orisun deployments require the PostgreSQL backend. SQLite startup fails when ORISUN_NATS_CLUSTER_ENABLED=true.