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 :doc:`ResourceCalculator` to size database replicas, memory and disk from your node and edge inventory and expected command traffic. .. list-table:: Deployment packages :header-rows: 1 :widths: 20 40 40 * - Method - Docker Hub package - Deployment * - :doc:`deployment/DockerCompose` - ``aperturedata/aperturedb-compose-single-node``, ``aperturedata/aperturedb-compose-distributed-local``, or ``aperturedata/aperturedb-compose-distributed-cloud`` - Running on one host, with local or cloud storage. * - :doc:`deployment/Helm` - ``aperturedata/aperturedb-helm`` - Managing a distributed Kubernetes deployment with Helm. * - :doc:`deployment/OpenTofu` - ``aperturedata/aperturedb-terraform`` - 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. .. _choosing-a-version: Selecting a package ------------------- Replace ```` in the guides with a published release tag from the corresponding Docker Hub repository: * `Compose single-node releases `_ * `Compose distributed-local releases `_ * `Compose distributed-cloud releases `_ * `Helm releases `_ * `OpenTofu releases `_ 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: .. code-block:: json { "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. .. _deployment-verify: 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: .. code-block:: bash python3 -m pip install aperturedb .. This connection snippet is illustrative, not generated by a test. .. TESTED_EXAMPLE: Deployment_1 .. code-block:: python 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 :doc:`commands/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. .. _deployment-upgrades: .. _plan-and-verify-an-upgrade: Changing a deployment --------------------- Changes to a running deployment can interrupt service. Before applying changes: 1. Record the package reference, configuration, storage locations, and client settings. Save OpenTofu state when applicable. 2. 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. 3. Rehearse the changes and representative reads and writes on an isolated restore. Preserve the deployment identity and storage locations when applying the configuration. 4. Run :ref:`deployment-verify`, 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. :doc:`deployment/DockerCompose`, :doc:`deployment/Helm`, and :doc:`deployment/OpenTofu` describe the commands for applying configuration. Administrative commands in the tools image ------------------------------------------ Use ``aperturedata/tools:`` 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. .. code-block:: bash kubectl -n aperturedb exec -it deployment/tools -- sh .. _deployment-bootstrap: 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. 1. Stop client writes and the destination database and checkpointer instances. Keep ZooKeeper running. On Kubernetes, scale the ``aperturedb`` and ``checkpointer`` Deployments to zero and wait for their pods to terminate. 2. 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, prefix ``team/db`` appears in filenames as ``team-db``. 3. 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. 4. In a tools container matching the database release, set ``ADB_ZK_SERVERS`` and ``ADB_ZK_PREFIX`` to 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. .. code-block:: bash checkpoint=team-db-123-checkpointer_adb-0_0-1700000000-checkpoint.lmdb bootstrap "$ADB_ZK_SERVERS" "$ADB_ZK_PREFIX" "$checkpoint" 5. 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 :ref:`deployment-verify` 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 `` and exits when ZooKeeper acknowledges the request. A running checkpointer for that prefix processes it and publishes a checkpoint when there are new commits. .. code-block:: bash 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. .. code-block:: bash 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. .. code-block:: bash zk-reset "$ADB_ZK_SERVERS" "$ADB_ZK_PREFIX" Deployment guides ----------------- .. toctree:: :maxdepth: 1 deployment/DockerCompose deployment/Helm Terraform