Deploy with Docker Compose

ApertureDB publishes each Compose layout as a versioned OCI package. Select a release and configure it with environment variables; the package provides the service definitions, default images, and connections between services.

Run ApertureDB using Docker with Linux container support and Docker Compose 2.39.4 or later. Authenticate with docker login if your supplied images require registry access. The commands below use a POSIX shell.

Choose a layout

Choose a published release from Deploying ApertureDB and one of these layouts:

Layouts

Layout	Storage	Use
single-node	Local database files and logs	One database without distributed checkpointing.
distributed-local	Local objects and binlogs shared by the databases and checkpointer	Exercise distributed features on one host.
distributed-cloud	S3 or Google Cloud Storage for database content; local logs and coordination data	Use an existing object-storage bucket.

All layouts run on one Docker host and include the Web UI and HTTP/TCP gateways. Multiple database containers on one host do not protect against host failure. Local persistence uses Docker named volumes unless you set DATA_DIR.

Configure and start

Create a local file named deployment.env with the settings for your deployment:

ADB_MASTER_KEY='<strong-database-password>'
MONITORING_PASSWORD='<separate-monitoring-password>'
GF_SECURITY_ADMIN_PASSWORD='<strong-grafana-password>'
GATEWAY=127.0.0.1

GATEWAY selects the host interface for published ports. Loopback restricts access to the Docker host; use a reachable interface for remote clients. Leaving it unset binds all interfaces. The initial database login is admin with ADB_MASTER_KEY as its password.

For distributed-cloud, also add the following settings:

ADB_STORAGE_TYPE=s3
ADB_STORAGE_BUCKET_NAME=<your-bucket-name>
ADB_STORAGE_CREDENTIALS='{"access_key":"<access-key>","secret_access_key":"<secret-access-key>","region":"us-west-2"}'

All three storage settings are required for that layout. For Google Cloud Storage, use ADB_STORAGE_TYPE=gs and supply the service account credential JSON on one line. See Deploying ApertureDB for bucket permissions. Use a dedicated bucket for each independent database deployment.

Set ADB_COMPOSE to your chosen release and layout. Replace <package-version> with a published release, such as X.Y.Z or X.Y.Z-rc.N, and replace single-node if using a distributed layout:

ADB_COMPOSE='oci://aperturedata/aperturedb-compose:<package-version>-single-node'
chmod 600 deployment.env
docker compose -p aperturedb --env-file ./deployment.env -f "$ADB_COMPOSE" config --quiet
docker compose -p aperturedb --env-file ./deployment.env -f "$ADB_COMPOSE" up -d
docker compose -p aperturedb --env-file ./deployment.env -f "$ADB_COMPOSE" ps

Docker Compose fetches the configuration directly from the registry. You do not need to download YAML files, extract a package, or check out a repository. Keep deployment.env, the project name (-p aperturedb), and the selected reference for subsequent commands. Use a different project name for each independent deployment.

The explicit project name is optional. If you omit it, keep the working directory fixed so later commands use the same project and persistent volumes. When settings are exported in the shell, --env-file is also optional:

docker compose -f 'oci://aperturedata/aperturedb-compose:<package-version>-distributed-cloud' up

All optional settings below use the same single Compose reference. Set variables in deployment.env or the shell; shell values take precedence. Omitted settings use the release defaults. Choose a release that supports the settings you need; previously published tags do not acquire new settings automatically.

Connect

With the default ports and loopback interface:

Access points

Service	Address
Web UI	http://localhost/ or https://localhost/
REST API	http://localhost/api/ or https://localhost/api/
Native database protocol	localhost:55555
Grafana, with telemetry enabled	http://localhost/grafana/ or https://localhost/grafana/

Log into the Web UI as admin using ADB_MASTER_KEY. Run GetStatus to confirm that the database accepts queries. For remote clients, replace localhost with the Docker host’s address.

Automate with CI/CD or infrastructure as code

Use the same published package for manual and automated deployments. Your pipeline or infrastructure-as-code (IaC) configuration only needs to maintain the release reference, project name, and deployment variables. You do not need to copy, template, or maintain Compose YAML files for the settings documented below.

Keep non-secret settings in your environment configuration and supply passwords and credentials from your secret store. Automation can generate deployment.env or export variables directly. With ADB_COMPOSE set to a specific release and layout, and deployment variables exported, run:

docker compose -p aperturedb -f "$ADB_COMPOSE" config --quiet
docker compose -p aperturedb -f "$ADB_COMPOSE" up -d

Promote the same release reference through your environments, changing only their variables. For an upgrade, update that reference after reviewing the release’s upgrade requirements. Keep each deployment’s project name and storage locations stable so subsequent runs reuse its data. Automation must also prepare the Docker host, registry access, and any supplied certificates or storage.

Published ports and request limits

Add only the settings you want to change to deployment.env:

Network settings

Variable	Default	Purpose
HTTP_PORT	80	Published HTTP port.
HTTPS_PORT	443	Published HTTPS port.
ADB_TCP_PORT	55555	Published native database port.
HTTP_MAX_BODY_SIZE	256m	Maximum HTTP request body size.
HTTP_PROXY_READ_TIMEOUT	60s	Timeout between successive reads from an upstream service.
LNZ_FORCE_SSL	false	Require encrypted native TCP connections when set to true.

Only one deployment can bind a given port on the same host interface. For example, use HTTP_PORT=8080 and HTTPS_PORT=8443 if the default ports are already occupied. Internal container ports remain unchanged.

For a host reverse proxy that terminates HTTPS, bind to loopback and forward to the configured HTTP port. Preserve the /api/ and /grafana/ paths, and set GF_SERVER_ROOT_URL to the public URL ending in /grafana/. Configure native TCP TLS separately from the web proxy.

Use your own certificates

By default, the deployment generates a self-signed certificate for localhost and retains it in a named volume. To use your own certificate, add these settings to deployment.env:

TLS_CERT_DIR=/etc/aperturedb/tls
TLS_CERT_FILENAME=fullchain.pem
TLS_KEY_FILENAME=privkey.pem
LNZ_FORCE_SSL=true

TLS_CERT_DIR must be an absolute directory on the Docker host containing a PEM certificate chain and a matching unencrypted RSA private key. ECDSA keys are not supported. The filenames default to tls.crt and tls.key; use different bare filenames containing only letters, digits, dots, underscores, or hyphens. The names . and .. are invalid. Keep symlink targets inside the mounted directory, and make the files readable by the container users.

Start with the same command as above. The directory is mounted read-only and the supplied pair is validated before the gateways start. Missing or invalid files prevent gateway startup; supplied files are never generated or overwritten. Providing certificates alone does not require encrypted native TCP connections; set LNZ_FORCE_SSL=true to enforce them.

After replacing certificates, revalidate the pair and recreate the gateways:

docker compose -p aperturedb --env-file ./deployment.env -f "$ADB_COMPOSE" \
  up -d --force-recreate ca nginx lenz

Leave TLS_CERT_DIR and the filename variables unset to use the generated certificate. The generated pair is reused on subsequent starts. If only one of the two files is present, restore the complete pair before starting again.

Image repositories

To use a registry mirror, set a prefix including its trailing slash:

IMAGE_REPOSITORY_PREFIX=registry.example.com/mirror/

This applies to every image, including third-party images. For example, aperturedata/aperturedb:<tag> becomes registry.example.com/mirror/aperturedata/aperturedb:<tag> and nginx:<tag> becomes registry.example.com/mirror/nginx:<tag>. Mirror the images required by your selected layout and profiles, and authenticate to that registry before starting.

Use a complete image reference when a mirror changes a repository name or when you need a digest-pinned image:

APERTUREDB_IMAGE=registry.example.com/database/aperturedb:custom-release
NGINX_IMAGE=registry.example.com/proxy/nginx@sha256:<digest>

Complete image overrides take precedence over IMAGE_REPOSITORY_PREFIX. Supported variables are APERTUREDB_IMAGE, CHECKPOINTER_IMAGE, LENZ_IMAGE, WEBUI_IMAGE, GRAFANA_IMAGE, PROMTAIL_IMAGE, NGINX_IMAGE, ZOOKEEPER_IMAGE, PROMETHEUS_IMAGE, LOKI_IMAGE, and OPENSSL_IMAGE. Checkpointer and ZooKeeper apply only to distributed layouts. Keep the bundled image versions unless you need a compatible override.

Host storage

To use host directories instead of Docker named volumes, set an absolute parent path in deployment.env:

DATA_DIR=/srv/aperturedb

Each data or log location uses DATA_DIR/<name>. Prepare the following subdirectories for your layout, with suitable ownership and permissions for the container users:

Host subdirectories

Layout	Subdirectories
single-node	aperturedb_db, aperturedb_logs
distributed-local	aperturedb_objects, aperturedb_binlogs, aperturedb_acl, aperturedb_0_logs, aperturedb_1_logs, checkpointer_checkpointer_logs, zookeeper_zoo1_data, zookeeper_zoo2_data, zookeeper_zoo3_data
distributed-cloud	aperturedb_0_logs, aperturedb_1_logs, checkpointer_checkpointer_logs, zookeeper_zoo1_data, zookeeper_zoo2_data, zookeeper_zoo3_data
Any layout with telemetry	Also create grafana, loki, and prometheus.

Compose may create missing directories, but host mounts do not initialize ownership from image directories. Use a separate DATA_DIR for each independent deployment. Run the same startup command after setting it; no additional Compose file is needed.

Changing DATA_DIR does not migrate existing data. Stop the deployment and copy its data with the required ownership and permissions before switching locations. Generated certificates remain in their named volume independently of DATA_DIR; use TLS_CERT_DIR for your own certificates.

Monitoring

To enable Prometheus, Grafana, Loki, and log collection:

docker compose -p aperturedb --env-file ./deployment.env -f "$ADB_COMPOSE" \
  --profile telemetry up -d

MONITORING_PASSWORD authenticates metrics collection; it is separate from the Grafana login. GF_SECURITY_ADMIN_USER defaults to admin. Set GF_SECURITY_ADMIN_PASSWORD before initializing Grafana. Change an existing administrator password through Grafana when retaining its data volume.

Set GF_SERVER_ROOT_URL to the public Grafana URL if needed, for example https://database.example.com/grafana/. Its default is %(protocol)s://%(domain)s:%(http_port)s/grafana/.

PROMETHEUS_RETENTION_TIME defaults to 28d and LOKI_RETENTION_PERIOD to 672h. Adjust them to control how long metrics and logs are retained. Scraping and service discovery stay fixed at five seconds, with a four-second scrape timeout; monitoring calculations depend on that interval.

Capacity and logging

Use these settings when tuning a deployment for your host and workload:

Capacity and logging settings

Variable	Default	Purpose
ADB_KVGD_DB_SIZE	204800	Graph-store size setting.
ADB_MAX_SIMULTANEOUS_CLIENTS	24 single-node; 52 distributed	Client limit per database process.
LNZ_ADB_MAX_CONCURRENCY	16 single-node; 48 distributed	Database concurrency per gateway process.
ADB_CPUS, ADB_MEMORY_LIMIT	0, 0	Limits per database container.
LNZ_CPUS, LNZ_MEMORY_LIMIT	0, 0	Limits for the gateway container.
CHECKPOINTER_CPUS, CHECKPOINTER_MEMORY_LIMIT	0, 0	Limits for the checkpointer in distributed layouts.
ADB_ENABLE_DEBUG	1 single-node; 0 distributed	Database debug mode.
ADB_LOG_LEVEL	1	Database log level.
CHECKPOINTER_LOG_LEVEL	0	Checkpointer log level in distributed layouts.

CPU limits accept fractional cores, such as ADB_CPUS=2.5. Memory limits accept sizes such as ADB_MEMORY_LIMIT=8g. A limit of 0 means unlimited. These settings do not change the number of containers. Leave database client capacity above gateway concurrency to allow for internal clients and all gateway processes. See Configuration File for database configuration details.

Stop, restart, and upgrade

Use the same project name, environment file, and Compose reference for lifecycle commands. To stop all services, including telemetry, and start them again:

docker compose -p aperturedb --env-file ./deployment.env -f "$ADB_COMPOSE" \
  --profile telemetry down
docker compose -p aperturedb --env-file ./deployment.env -f "$ADB_COMPOSE" \
  --profile telemetry up -d

Omit --profile telemetry on startup if you do not want monitoring. down retains named volumes, host directories, and cloud bucket contents. down -v deletes managed named volumes, including generated certificates; it does not delete data in host directories or object storage.

Before upgrading, back up your data and configuration and check the target release’s upgrade requirements. Set ADB_COMPOSE to the new release tag for the same layout, keep the project name and storage locations fixed, then run:

docker compose -p aperturedb --env-file ./deployment.env -f "$ADB_COMPOSE" \
  --profile telemetry pull
docker compose -p aperturedb --env-file ./deployment.env -f "$ADB_COMPOSE" \
  --profile telemetry up -d

If startup fails, inspect status and logs:

docker compose -p aperturedb --env-file ./deployment.env -f "$ADB_COMPOSE" ps -a
docker compose -p aperturedb --env-file ./deployment.env -f "$ADB_COMPOSE" logs --tail=100

An exited ca container with exit code 0 is expected. For failures, check registry access, host port conflicts, certificate paths and permissions, write access to storage directories, and cloud credentials where applicable.