Deploying ApertureDB
ApertureDB deployment packages run the database and its supporting services on a Docker host or Kubernetes cluster. Docker Compose, Helm, and OpenTofu packages are published on Docker Hub; each fits a different infrastructure workflow.
Use the Resource planner to size database replicas, memory and disk from your node and edge inventory and expected command traffic.
Method |
Docker Hub package |
Deployment |
|---|---|---|
|
Running on one host, with local or cloud storage. |
|
|
Managing a distributed Kubernetes deployment with Helm. |
|
|
Managing a distributed Kubernetes deployment as code with OpenTofu. |
The Compose layouts, Helm chart, and OpenTofu module are OCI artifacts consumed by their respective tools. Docker Compose loads its configuration directly from the registry. Each package deploys the database and supporting services, including the Lenz gateway and Web UI.
Selecting a package
Replace <package-version> in the guides with a published release tag from
the corresponding Docker Hub repository:
Each Compose layout has a separate repository. All deployment packages use the
same tag as the service images: X.Y.Z or X.Y.Z-rc.N.
A published release supplies matching ApertureData image defaults. Keep those
defaults unless you need a compatible override; each guide identifies the
available settings.
If your supplied images require registry access, use your authorized Docker Hub
account. Authenticate the package download with docker login for Compose
or helm registry login registry-1.docker.io for Helm. OpenTofu uses its
OCI registry authentication configuration. Kubernetes also needs an
image pull secret for any private workload images; authenticating a local
package download does not configure the cluster.
Storage and credentials
Compose offers a single-node layout with local storage, a distributed layout with local storage, and a distributed layout with object storage. All three run on one Docker host; running multiple database containers on that host does not protect against failure of the host itself.
The Kubernetes guides deploy distributed ApertureDB with an existing object storage bucket. They deploy resources into an existing cluster and do not provision the cluster or bucket. Use a dedicated bucket for each independent database deployment.
For AWS S3, select storage type s3 and supply credential JSON of this form:
{
"access_key": "<access-key>",
"secret_access_key": "<secret-access-key>",
"region": "us-west-2"
}
The credentials must permit the database to list the bucket and read, write, and delete its objects, including multipart uploads. Have your storage administrator provision the bucket and suitable permissions before starting. S3-compatible storage may require additional endpoint configuration.
For Google Cloud Storage, select gs and supply the service account’s JSON
credentials, with permission to list, read, create, and delete objects in the
bucket. Each guide shows where to supply the bucket name and credential JSON.
Set a strong database master key before starting. The initial database login
is admin with the master key as its password. Monitoring uses a separate
bearer password; Grafana also has its own administrator login. Keep credentials
out of source control.
Service roles
The database stores the graph and serves queries. Lenz accepts native client
connections and REST requests and forwards them to database instances. The web
proxy serves the UI and routes /api/ to Lenz. Distributed layouts add
ZooKeeper for coordination and a checkpointer for recovery checkpoints.
Prometheus discovers database instances and collects their metrics through Lenz. Promtail reads database logs and forwards them to Loki for storage and queries. Grafana displays metrics from Prometheus and logs from Loki in the bundled dashboards. The telemetry images include the collection configuration, log processing pipeline, data sources, and dashboards. Deployment packages supply credentials, persistent storage, and retention settings. Each deployment guide explains how to enable telemetry and access Grafana.
Connect and verify the deployment
Once ports, TLS, and credentials are configured, native clients connect to
the published Lenz endpoint, normally port 55555. Use the
TCP hostname covered by your certificate, which may differ from the Web UI’s
hostname. For the self-signed evaluation certificate, obtain the certificate
from your deployment administrator and set APERTUREDB_CA_CERT to its local
PEM path. A publicly trusted certificate uses the system trust store.
Install the Python SDK in your client environment, then run this check. It prompts for the hostname and password so credentials need not appear in source code or shell history:
python3 -m pip install aperturedb
import getpass
import os
from aperturedb.Connector import Connector
db = Connector(
host=input("Native TCP hostname: "),
port=int(input("Native TCP port [55555]: ") or "55555"),
user=input("Database user [admin]: ") or "admin",
password=getpass.getpass("Database password: "),
use_ssl=True,
ca_cert=os.environ.get("APERTUREDB_CA_CERT"),
)
response, blobs = db.query([{"GetStatus": {}}])
print(response)
assert isinstance(response, list), response
assert response[0]["GetStatus"]["status"] == 0, response
db.close()
For the initial admin login, use the configured master key. A successful
GetStatus response identifies system: ApertureDB,
status: 0, and the running version. Save the response with your deployment
configuration; successful container startup alone does not prove queries work.
Then test a representative application read before opening traffic.
For stored client profiles, see client configuration. For HTTP clients,
follow the REST setup and authentication guide: send the JSON query as the
query part of a multipart POST to /api/ with the session bearer token.
A plain JSON POST is not the REST request format.
Changing a deployment
Changes to a running deployment can interrupt service. Before applying changes:
Record the package reference, configuration, storage locations, and client settings. Save OpenTofu state when applicable.
Arrange a maintenance window and stop application writes. Take and verify a restorable backup using your deployment’s backup procedure, preserving database/object data and required coordination state, credentials, and configuration. Changing an image or chart does not restore database data.
Rehearse the changes and representative reads and writes on an isolated restore. Preserve the deployment identity and storage locations when applying the configuration.
Run Connect and verify the deployment, inspect logs, and validate application queries and schema consumers. Resume writes only after these checks pass.
If validation fails, keep writes stopped and preserve logs. Recovery requires restoring the backup with its matching software and configuration. Deploy with Docker Compose, Deploy with Helm, and Deploy with OpenTofu describe the commands for applying configuration.
Administrative commands in the tools image
Use aperturedata/tools:<package-version> with the same release tag as the
database. With Docker, pass the executable and its arguments after the image
name. Give the container network access to ZooKeeper and mount the changelog
list if bootstrap needs one. On Kubernetes, the Helm and OpenTofu packages
provide a tools Deployment with the ZooKeeper server list and prefix. With
a tools replica running, open a shell in your deployment namespace.
kubectl -n aperturedb exec -it deployment/tools -- sh
Bootstrapping from a checkpoint
On a fresh deployment with an empty ZooKeeper prefix and no local graph, the
first database or checkpointer to acquire the graph lock creates an empty graph
and publishes its initial checkpoint. To recover an existing database, run
bootstrap before starting those services. It replaces the checkpoint and
changelog registrations in the destination ZooKeeper prefix. The checkpoint
alone restores the graph to the transaction in its filename. To recover later
commits, include the changelogs through the desired transaction.
Stop client writes and the destination database and checkpointer instances. Keep ZooKeeper running. On Kubernetes, scale the
aperturedbandcheckpointerDeployments to zero and wait for their pods to terminate.Verify that the destination storage contains the checkpoint under
binlogs/checkpoints/and the objects referenced by the restored graph. Keep the original filenames. The checkpoint and changelog names must match the destination ZooKeeper prefix. For example, prefixteam/dbappears in filenames asteam-db.For recovery beyond the checkpoint, prepare a local text file with one changelog basename per line from
binlogs/changelogs/. The ranges must form an unbroken chain starting at the checkpoint transaction. Bootstrap skips entries ending at or before that transaction. Verify that the listed objects exist in storage before registering them.In a tools container matching the database release, set
ADB_ZK_SERVERSandADB_ZK_PREFIXto the destination’s ZooKeeper settings. The packaged Kubernetes tools pod already has these values. Substitute your checkpoint basename below. To register changelogs, append the local list path as the fourth argument. Bootstrap checks the names, takes the checkpoint lock, updates ZooKeeper, and prints the registered checkpoint basename on its last line.checkpoint=team-db-123-checkpointer_adb-0_0-1700000000-checkpoint.lmdb bootstrap "$ADB_ZK_SERVERS" "$ADB_ZK_PREFIX" "$checkpoint"
Start the database and checkpointer instances with fresh local graph directories and the restored storage. Each instance downloads the registered checkpoint and applies the registered changelogs. Follow Connect and verify the deployment and check a representative read at the chosen recovery point before resuming writes.
create-checkpoint
Request a checkpoint for the current transaction by passing the distributed
database’s ZooKeeper server list and prefix. The command prints
Requested checkpoint for transaction <txn> and exits when ZooKeeper
acknowledges the request. A running checkpointer for that prefix processes it
and publishes a checkpoint when there are new commits.
create-checkpoint "$ADB_ZK_SERVERS" "$ADB_ZK_PREFIX"
Before using the checkpoint, run zk-data and look under checkpoints for
a transaction ID at least as large as the one printed by create-checkpoint.
An existing checkpoint may already cover the requested transaction.
zk-data
Inspect the ZooKeeper tree for a deployment prefix. The command prints the current transaction and the registered checkpoint and changelog names as JSON.
zk-data "$ADB_ZK_SERVERS" "$ADB_ZK_PREFIX"
zk-reset
Stop the destination database and checkpointer instances and confirm the target prefix with zk-data before resetting it. The command erases the prefix’s checkpoint and changelog registrations, resets its transaction ID and lock prefix to zero, and prints the resulting ZooKeeper tree. Checkpoint and changelog files stay in storage.
zk-reset "$ADB_ZK_SERVERS" "$ADB_ZK_PREFIX"