Configuration File

ApertureDB reads server settings from a JSON configuration file. The -cfg flag specifies its path:

./aperturedb -cfg config.json

Without -cfg, ApertureDB reads config.json from the working directory. The server does not start if the file is missing.

Parameters

All configuration keys are optional. Omitted settings use environment variables or built-in defaults according to the precedence below.

For settings read by the server, the first available value is used:

1. A nonempty environment variable with prefix ADB_ and the key in upper case, such as ADB_PORT or ADB_SESSION_TOKEN_MAX_AGE_SEC.

2. The value in the JSON configuration file.

3. The server’s built-in default.

An empty environment variable falls through to JSON or the default. Use true/false for boolean environment values, decimal numbers for numeric values, and raw text for strings. Do not add JSON quotes around string values in the environment. Shell or deployment-file quoting is separate.

The JSON file is parsed and validated before environment overrides are read. Unknown keys, wrong JSON types, and out-of-range JSON values prevent startup even when an environment variable would override them. Environment values are parsed when the consuming setting is read; the JSON validator does not validate the final merged configuration. Follow the documented ranges for both sources. Restart the consuming process after configuration changes.

These defaults describe the database binary. Deployment packages supply additional values and configure separate processes; see Deployment settings and process boundaries.

The following table describes commonly used parameters:

Parameter	Explanation	Default
master_key	The master key that initializes admin password on the first run.	"" (Range: any string)
port	TCP port for incoming connections	55555 (Range: 1-65535)
enable_health_port	Enable/disable the health check port	false (Range: true/false)
health_port	TCP port for health checks	55563 (Range: 1-65535)
timeout_receive	Enable/disable connection receive timeouts	true (Range: true/false)
max_simultaneous_clients	Number of max simultaneous connections open	500 (Range: >= 1)
max_connection_message_size_mb	Maximum native query/response message size in MiB (1,048,576 bytes). A value of 0 uses the libcomm default. This does not set HTTP proxy limits.	0 (Range: >= 0)
force_ssl	Flag that indicates whether or not SSL-based communication will be enforced by the server	true (Range: true/false)
db_root_path	Path to the root folder where all files/objects will be stored	db (Range: any valid path)
storage_type	Storage backend: ext4 for local files, s3 for S3, or gs for Google Cloud Storage.	"ext4"
storage_bucket_name	Bucket name for S3 or Google Cloud Storage.	""
storage_credentials	Storage credential JSON encoded as a string. See Deploying ApertureDB for credential examples.	"{}"
log_path	Directory where logs will be placed.	"/tmp" (Range: any valid path)
log_level	Levels INFO, WARNING, ERROR, and FATAL are 0, 1, 2, and 3, respectively	1 (WARNING) (Range: 0-3)
verbose_log_level	Verbosity level beyond INFO, for debugging. Will set log_level = 0. Check Google glog documentation for details	-1 (no verbosity beyond INFO) (Range: >= -1)
log_cerr_threshold	Specify level of logging which will also be sent to stderr	3 (FATAL) (Range: 0-3)
enable_audit_logs	Enable/disable audit logs	false (Range: true/false)
include_audit_logs	When true, audit logs will be included in ApertureDB logs	false (Range: true/false)
kvgd_db_size	Maximum size of the graph database in MB	10 (Range: > 0)
kvgd_db_sync	Enable/disable sync operation to disk on every transaction. When disabled, latency will decrease but data loss may occur in case of crash	true (Range: true/false)
locale_name	Locale used for string comparison	en_US (Range: any valid locale)
zk_servers	Comma-separated list of Zookeeper server:port	"" (Range: any string)
zk_prefix	Same instance of Zookeeper can be used by multiple aperturedb clusters. Each cluster uses a different prefix to provide isolation between clusters. The config parameter zk_prefix specifies the path for the instance.	"testing" (Range: any string)
checkpoints_to_keep	Number of checkpoints that will be kept for recovery	4 (Range: > 0)
seconds_between_checkpoints	Interval in seconds between scheduled checkpoints. At least one new changelog is required; commit count does not trigger an earlier checkpoint.	7200 (2 hours) (Range: > 0)
resources_check_mem_limit	Limit on percentage of memory utilization after which queries are stopped	93 (Range: 1-100)
resources_check_sleep	Number of seconds between resource utilization checks	2 (Range: > 0)
batch_time_to_live	Number of seconds that a batch is kept in memory before being cleaned up	60 (Range: >= 0)
batch_cleaner_interval	Number of seconds between batch cleanup operations	10 (Range: >= 0)
descriptorset_flusher_interval	Number of seconds between descriptor set cleanup operations	1800 (Range: >= 0)

Security and connection limits

These settings apply per server. All values must be positive integers.

Setting	Default	Behavior
session_token_max_age_sec	36000	Session token lifetime in seconds (10 hours).
refresh_token_max_age_sec	360000	Refresh token lifetime in seconds (100 hours).
max_sessions_per_user	1024	Maximum sessions per user. Signing in or refreshing revokes the oldest sessions as needed to stay within the limit.
max_sessions_in_cache	1024	Successful session checks kept for reuse. Lower limits reduce retained authentication data and may require more checks; session lifetime and revocation rules stay the same.
max_remote_connections	32	Connections kept for reuse with external origins. Lower limits may require more connection setup; ongoing requests are unaffected. This does not limit concurrent requests or connections to the database’s own storage.

See Access Control and Remote credentials for session limits and the effects of changing permissions or credentials. The obsolete session_cache_max_age_sec and sessions_file_refresh_rate_sec settings are no longer accepted.

HTTPS origin limits

These optional integer settings control reads from registered HTTPS origins. They do not configure inbound HTTPS or change the HTTP proxy’s request limit. See HTTPS keys and transport for authentication, URL restrictions, and recovery.

HTTPS fetch controls

JSON key / environment suffix	Default	Range	Scope
https_max_object_size_mb / HTTPS_MAX_OBJECT_SIZE_MB	16 MiB	1–64 MiB	Maximum bytes in one remote object.
https_timeout_ms / HTTPS_TIMEOUT_MS	10000 ms	1–30000 ms	Maximum time for one fetch, also bounded by the query deadline.
https_operations_limit / HTTPS_OPERATIONS_LIMIT	4	1–32	Concurrent HTTPS operations/readers per server process.

Prefix the environment suffix with ADB_. Independently, one query has a 64 MiB total download budget, at most 32 HTTPS requests, a 60-second deadline, and at most two active fetches. These per-query limits are not increased by the three settings above. A size check can make a HEAD request in addition to a GET. Split large workloads into smaller queries and reduce concurrency when limits are reached; retries also consume resources.

Advanced settings

These settings control resource limits and background work. Their appropriate values depend on the deployment layout and workload; changes require coordination with the deployment administrator or ApertureData support. The table lists server defaults before package overrides.

Advanced settings

Key	Default	Purpose and JSON range
storage_operations_limit	100	Concurrent object-store operations; integer ≥ 1.
storage_part_size_mb	8	Multipart/cache part size in MiB; integer 5–512.
storage_read_cache_parts	4	Cached parts per reader; integer 1–64. Memory depends on part size.
storage_retry_limit / storage_retry_delay_ms	5 / 200	Retry count (integer ≥ 0) and initial backoff in ms (integer ≥ 1).
objects_partition_count / objects_directory_count	4 / 4096	Object-store layout; integers ≥ 1. Do not change an existing layout casually.
resources_max_mem_limit	0	Memory reference limit in bytes; 0 selects detected system memory.
resources_max_storage / resources_check_storage_limit	0 / 99	Storage reference limit in GiB (0 disables this limit) and percentage threshold (number 0–100).
resources_check_kill_timer	2	Time queries remain aborted after exceeding the memory threshold, in seconds; integer ≥ 1.
task_executor_threads	100	Executor thread count; integer ≥ 1.
enable_blacklist	0	Connection blacklist switch; JSON integer 0 or 1, not a JSON boolean.
max_failed_connections / blacklist_time_minutes	10 / 5	Blacklist failure threshold and duration in minutes; integers ≥ 1.
kvgd_db_inc_size	0	Graph mapping growth increment in MB; integer ≥ 0.
kvgd_readahead / validate_write_txn	false / false	Graph read-ahead and additional write validation; booleans.
merge_write_request_upto	0	Internal write-merging control; integer ≥ 0.
enable_debug / disable_add_image	false / false	Debug behavior and disabling AddImage; booleans.
refresh_dset_on_startup / prevent_telemetry_user_deletion	false / false	Descriptor startup refresh and protection of the telemetry user; booleans.

more-info is a string annotation accepted in the JSON file; it changes no server behavior and has no environment override.

ADB_HOST_IP is an environment-only server setting for the advertised host identity; its default is the machine hostname. host_ip is not an accepted JSON key. ADB_CHECKPOINT_NOW is an internal checkpointer control, not a normal server configuration key.

Deployment settings and process boundaries

A client first reaches Lenz for the native protocol, or the web proxy and Lenz for REST. The database is a separate backend. Each process reads its own configuration; changing a database variable does not configure the gateway.

Where to configure a setting

Consumer / purpose	Compose	Helm	OpenTofu
Database bootstrap password	ADB_MASTER_KEY	masterKey.password or masterKey.existingSecret	master_key.password or master_key.existing_secret
Database storage	ADB_STORAGE_TYPE, ADB_STORAGE_BUCKET_NAME, ADB_STORAGE_CREDENTIALS in distributed-cloud	storage.type, storage.bucket, storage.credentials / existingSecret	storage.type, storage.bucket, storage.credentials / existing_secret
Database HTTPS fetch controls	Custom Compose override for each database service’s environment; the published environment template does not forward these keys.	aperturedb.extraEnv.ADB_HTTPS_*	aperturedb.extra_env map with ADB_HTTPS_* keys
Lenz native TLS	LNZ_FORCE_SSL; default false	Enabled by the chart’s Lenz template	Enabled by the module’s Lenz configuration
Web HTTPS certificates	TLS_CERT_DIR and certificate filenames	tls settings	tls settings
Maximum HTTP request body size	HTTP_BODY_LIMIT; default 268435456 bytes	http.bodyLimit in bytes	http.body_limit in bytes
HTTP upstream inactivity timeout	HTTP_TIMEOUT_SECONDS; default 300 seconds	http.timeoutSeconds	http.timeout_seconds
Web redirect and application URL port	HTTPS_PORT; default 443	http.publicPort; set to the public port, normally 443	http.public_port; set to the public port, normally 443
Workflow HTTP routes	Mount an HTTP route configuration with a Compose override	http.routes	http.routes
Published native port	ADB_TCP_PORT; default 55555	lenz-external service, port 55555	lenz-external service, port 55555

All three packages set backend ADB_FORCE_SSL=false and use Lenz for native client TLS. In Helm and OpenTofu, native TLS is enabled by default; Compose requires LNZ_FORCE_SSL=true to enforce it. HTTP TLS is configured separately. A certificate alone does not enable Compose’s native TLS requirement.

The web port settings control redirects and application URLs. In Kubernetes, set the public port explicitly when a load balancer forwards to backend NodePorts. Workflow routes and Grafana allow one hour between response reads for interactive sessions.

Compose substitutes only variables named by its template. Exporting an arbitrary ADB_* variable on the host does not inject it into a container. Helm’s aperturedb.extraEnv and OpenTofu’s aperturedb.extra_env add variables to database containers; use the separate Lenz and checkpointer maps for those processes. Prefer named package values when available, and inspect rendered configuration before introducing a duplicate environment key. For examples and lifecycle commands, see Deploying ApertureDB.

Config File Example

This example sets common parameters to their default values. Omitted parameters use their defaults. For a new database, also set ADB_MASTER_KEY to a strong password before starting the server.

{
    "port": 55555,
    "max_simultaneous_clients": 500,
    "max_connection_message_size_mb": 0,
    "force_ssl": true,
    "db_root_path": "db",
    "storage_type": "ext4",
    "log_path": "/tmp",
    "log_level": 1,
    "verbose_log_level": -1,
    "log_cerr_threshold": 3,
    "batch_cleaner_interval": 10,
    "batch_time_to_live": 60,
    "resources_check_sleep": 2,
    "resources_check_mem_limit": 93
}

Default Directories Structure

ApertureDB creates the following directories under its default data path:

db
├── acl
├── binlogs
├── descriptors
├── graph
├── objects
└── tmp