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.
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.