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:
A nonempty environment variable with prefix
ADB_and the key in upper case, such asADB_PORTorADB_SESSION_TOKEN_MAX_AGE_SEC.The value in the JSON configuration file.
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. |
|
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) |
network_threads |
Threads servicing asynchronous connections; idle clients do not occupy query workers. |
Up to 4, based on available CPU cores (Range: 1–1024) |
query_threads |
Workers executing queries. Separate from the number of accepted connections. |
Up to 16, based on available CPU cores (Range: 1–65536) |
query_queue_bytes_mb |
MiB budget shared by all connections for retained request/response bytes, including streamed blob chunks. Also bounds bytes admitted to the query worker pool and the largest request. Allow headroom above the largest encoded request for metadata and worker bookkeeping; concurrent requests and responses compete for this budget. Exhaustion closes the connection. |
256 (Range: > 0) |
max_read_transactions |
Maximum simultaneous database read transactions, independent of socket count. |
Greater of 126 or five times query_threads (Range: 1–1048576) |
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. Set |
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: |
|
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. |
|
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 |
Initial graph database mapping size in MiB. The mapping can grow; this is not a RAM reservation or a physical disk capacity limit. |
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 |
|
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. |
|
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) |
descriptorset_flusher_interval |
Number of seconds between descriptor set cleanup operations |
1800 (Range: >= 0) |
descriptor_index_cache_size_mb |
RAM budget in MiB for immutable descriptor index snapshots, their background copies, and private arrays for eligible HNSW appends. Synchronous and lazy indexing share this cache. Zero disables it. Queries use the transactional LMDB index while a matching snapshot is unavailable. |
512 (Range: >= 0, must fit the platform byte count) |
The descriptor cache budget includes snapshots still held by queries or construction after cache eviction. HNSW native construction scratch and dirty records remain bounded by the mutation workspace, separately from cache-charged arrays. Eligible owned-array construction accounts for native scratch per worker before admission; it can reduce the worker count or use the serial record path when the available budgets do not fit. Explicit mutation limits remain strict. The cache budget excludes query scratch, graph transaction buffers, and the operating system’s LMDB page cache. The lazily allocated admission observation table is also separate (at most 32 namespaces, about 18 KiB on supported 64-bit platforms). A snapshot whose construction estimate exceeds the budget remains searchable directly from LMDB. Cache construction uses one background worker and never blocks a query waiting for completion.
Automatic admission requires reuse evidence for the same index revision: 32 eligible absent observations, or a later observation at least one second after the current observation window began. A new revision starts a new window; idle time alone does not start a build. When the bounded observation table is full, new namespaces replace its least recently observed entry and qualify immediately. These fixed heuristics are not query-latency or cache-readiness guarantees.
To verify warmup on an otherwise idle server, issue representative queries and
observe an increase in descriptor_index_cache_hits_total. These global
counters cannot attribute individual requests on a server with other traffic. A nonzero budget, a resident entry, elapsed
wall time or a completed build alone does not prove that the current query
revision used the cache. reason="deferred" in the rejected-by-reason metric
indicates that automatic admission is waiting for reuse evidence. Measure warmup
and post-write behavior separately from steady-state resident queries.
Security and connection limits
These settings apply per server. All values must be positive integers.
Setting |
Default |
Behavior |
|---|---|---|
|
36000 |
Session token lifetime in seconds (10 hours). |
|
360000 |
Refresh token lifetime in seconds (100 hours). |
|
1024 |
Maximum sessions per user. Signing in or refreshing revokes the oldest sessions as needed to stay within the limit. |
|
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. |
|
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.
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.
JSON key / environment suffix |
Default |
Range |
Scope |
|---|---|---|---|
|
16 MiB |
1–64 MiB |
Maximum bytes in one remote object. |
|
10000 ms |
1–30000 ms |
Maximum time for one fetch, also bounded by its remaining active fetch budget. |
|
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, 60 seconds of cumulative
active fetch time, and at most two active fetches. Waiting for the client to
consume a lazy blob response does not consume the fetch-time budget. 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.
Key |
Default |
Purpose and JSON range |
|---|---|---|
|
100 |
Concurrent object-store operations; integer ≥ 1. |
|
8 |
Multipart/cache part size in MiB; integer 5–512. |
|
4 |
Cached parts per reader; integer 1–64. Memory depends on part size. |
|
5 / 200 |
Retry count (integer ≥ 0) and initial backoff in ms (integer ≥ 1). |
|
4 / 4096 |
Object-store layout; integers ≥ 1. Do not change an existing layout casually. |
|
0 / 99 |
Storage reference limit in GiB (0 disables this limit) and percentage threshold (number 0–100). |
|
100 |
Executor thread count; integer ≥ 1. |
|
0 |
Connection blacklist switch; JSON integer 0 or 1, not a JSON boolean. |
|
10 / 5 |
Blacklist failure threshold and duration in minutes; integers ≥ 1. |
|
0 |
Graph mapping growth increment in MB; integer ≥ 0. |
|
false / false |
Graph read-ahead and additional write validation; booleans. |
|
0 |
Internal write-merging control; integer ≥ 0. |
|
false |
Accepted with no effect. Descriptor indexes are maintained transactionally. |
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.
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.
Consumer / purpose |
Compose |
Helm |
OpenTofu |
|---|---|---|---|
Database bootstrap password |
|
|
|
Database storage |
|
|
|
Database HTTPS fetch controls |
Custom Compose override for each database service’s |
|
|
Lenz native TLS |
|
Enabled by the chart’s Lenz template |
Enabled by the module’s Lenz configuration |
Web HTTPS certificates |
|
|
|
Maximum HTTP request body size |
|
|
|
HTTP upstream inactivity timeout |
|
|
|
Web redirect and application URL port |
|
|
|
Workflow HTTP routes |
Mount an HTTP route configuration with a Compose override |
|
|
Published native port |
|
|
|
Published Lenz health port |
|
Not configurable; published on an assigned node port when |
Not configurable; published on an assigned node port when |
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,
"network_threads": 4,
"query_threads": 16,
"query_queue_bytes_mb": 256,
"max_read_transactions": 126,
"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
}
Default Directories Structure
ApertureDB creates the following directories under its default data path:
db
├── acl
├── binlogs
├── descriptors
├── graph
├── objects
└── tmp