Docker
Run the standalone QilbeeDB platform in the local Docker engine for integration
testing. The repository supplies a multi-stage Dockerfile, compose.yaml, and
optional network configuration. No additional application services are required by
the default deployment.
Build from source#
git clone https://github.com/aicubetechnology/qilbeeDB.git
cd qilbeeDB
QILBEE_REVISION="$(git rev-parse HEAD)" docker compose build
The image uses a digest-pinned Rust 1.93.1 Bookworm build stage and Debian Trixie runtime, the committed Cargo lockfile, and a release build with thin LTO. Build concurrency is two jobs to fit local development machines. Dependency/target caches belong to BuildKit; the build context excludes local data, credentials, Git state and host targets. The runtime upgrades base packages before installing its required libraries. The first production qualification found security fixes available in Trixie that were absent from the Bookworm runtime; see the container security qualification.
The runtime includes the server, required native libraries, CA certificates, a built-in loopback health probe, and the license. It runs as UID/GID 10001.
The resulting default image is qilbeedb:local. This builds locally; it does not
publish an image to a registry. Use an explicit image tag and Git revision when
recording a validated deployment.
One-time local provisioning#
Provision before starting the service, using the same named volume:
umask 077
mkdir -p "$HOME/.config/qilbeedb/local"
chmod 700 "$HOME/.config/qilbeedb/local"
(set -C; docker compose run --rm --no-deps qilbeedb \
bootstrap-tenant /data qilbee-qmn-local platform-operator \
> "$HOME/.config/qilbeedb/local/admin.json")
chmod 600 "$HOME/.config/qilbeedb/local/admin.json"
The JSON file contains the one-time operator secret. Keep it outside Git and do
not paste it into logs or documentation. Bootstrap creates the tenant once; it
will not reset an existing tenant. The subshell uses set -C to refuse
overwriting an existing credential file. Do not rerun the command over an existing
credential file, because shell redirection would truncate that file before the
command fails. For an existing installation, use its saved credential and volume.
The local operator command needs exclusive access to the volume's RocksDB files. Stop the service before using that command. Routine key issuance, rotation and revocation use the authenticated HTTP API while the service is running.
Start the standalone service#
docker compose up -d
docker compose ps
curl --fail http://localhost:7474/health
curl --fail http://localhost:7474/openapi.json
# Browser reference: http://localhost:7474/docs
Compose publishes HTTP on 127.0.0.1:7474 by default. The root filesystem is
read-only, /data uses the persistent named volume, /tmp is temporary, Linux
capabilities are dropped, and privilege escalation is disabled. The server has
no learned-code executor in this container.
The health check reports process availability. Successful scoped writes and reads are separate integration checks. Only HTTP is exposed; this deployment does not advertise an implemented Bolt listener.
Connect application containers#
Use a Docker network shared by the application and database containers. Docker
service names resolve inside that network; a browser on the host should use the
published host address, such as http://localhost:7474.
Network access does not grant API permissions. Applications still need an API key with the appropriate capabilities and scope. Configure the network according to your application's deployment, without recreating unrelated services.
Configure the Compose deployment#
| Variable | Default | Meaning |
|---|---|---|
QILBEE_IMAGE |
qilbeedb:local |
Local image tag to build/run |
QILBEE_REVISION |
unknown |
OCI image revision label during build |
QILBEE_HTTP_PORT |
7474 |
Host loopback port mapped to container port 7474 |
RUST_LOG |
info |
Server tracing filter |
These are actual Compose controls. The server does not currently read the older
illustrative QILBEE_DATA_PATH, QILBEE_BOLT_PORT or mounted config.toml examples.
Inside this image, the command explicitly selects /data.
Validate the API#
- Read
/healthand import/openapi.jsoninto your API client. - Use the operator key to issue a restricted integration credential with
memory_readandmemory_write, plus exact project/mission/agent grants. - Create a memory with a unique idempotency key; retry it and compare receipts.
- Read, conditionally update, query and delete through the versioned memory contract.
- Verify that another tenant and a read-only credential cannot mutate it.
- Restart the container and verify a retained test record and its original receipt. Remove the test record through an authorized delete command.
The HTTP reference and platform administration reference contain authentication, payloads, response shapes, error codes and migration details. Existing legacy SDKs require an adapter before they can use the versioned platform routes.
Persistence, update and rollback#
# Restart the same instance; the named volume is retained.
docker compose restart
# Inspect the image revision actually serving requests.
docker inspect qilbeedb-local \
--format '{{ index .Config.Labels "org.opencontainers.image.revision" }}'
# Stop the service while retaining its data.
docker compose down
Do not use down --volumes or delete the named volume when preserving memory and
credential state. This release does not include a validated backup/restore tool.
Take an appropriate offline volume backup before testing storage-format changes.
To update, build a new explicit image tag and recreate only the QilbeeDB service with that tag. Keep the prior image for rollback. A prior binary must understand the stored schema versions before it can safely serve the volume; unsupported versions fail closed. Do not prune unrelated images, containers or volumes.
Scope of the local deployment#
The local stack supports durable identity, scoped memory, model-bound semantic retrieval, procedural learning and learned-tool development receipts. Generation workers, isolated invocation transport and tool publication gates remain subsequent features under the accepted architecture. This development deployment does not establish distributed availability, hardware power-loss behavior or comparative performance leadership.