Deployment

Supported shape

Deploy one nyxdb all-in-one process per database. The process owns the listener, SQL engine, PSI routing, WAL, parts, compaction, and system telemetry. The current release has no standby coordination or automatic failover.

Pin the artifact

Use an immutable image digest or an archived binary plus checksum:

docker pull ghcr.io/nyxl-io/db@sha256:<approved-digest>
docker image inspect ghcr.io/nyxl-io/db@sha256:<approved-digest>

Record the digest and the build revision emitted on startup. A moving tag such as edge can discover a candidate; it must not be the production deployment identity.

Container example

The published container profile listens on port 7777 and persists beneath /var/lib/nyxdb:

docker run -d \
  --name nyxdb \
  --restart unless-stopped \
  --stop-signal SIGTERM \
  --stop-timeout 120 \
  --memory 16g \
  -p 127.0.0.1:7777:7777 \
  -v /srv/nyxdb/data:/var/lib/nyxdb \
  ghcr.io/nyxl-io/db@sha256:<approved-digest> \
  --host=0.0.0.0 \
  --port=7777 \
  --data-dir=/var/lib/nyxdb \
  --memory-limit-bytes=15032385536

Adjust the host binding to the intended closed-network interface. The process must bind 0.0.0.0 inside a container for Docker port publication to reach it; the host-side publication determines which host interface is exposed.

Use a dedicated host path or volume with sufficient inode and byte capacity. Do not mount the backup repository inside the live data directory.

Native binary defaults

The executable's defaults differ from the container profile:

Starting a native binary without --data-dir is an in-memory run: catalog and data do not survive restart.

Filesystem and resource envelope

• The data-directory owner must be able to create, rename, fsync, and remove files and directories.
• Reserve disk headroom for WAL growth, part flush, compaction rewrite, and recovery work.
• Set an external memory limit and an engine memory limit that leave room for the runtime and filesystem behavior.
• Keep the governor enabled; disabling it is a benchmark/development posture.
• Keep process and container file-descriptor limits above connection and retained part-file requirements.
• Synchronize the host clock through infrastructure; temporal queries and operational timestamps assume a sane clock.

Clean shutdown

Send SIGTERM and allow the process to finish its shutdown sequence:

docker stop --time 120 nyxdb

Do not routinely use SIGKILL. Crash recovery is tested, but clean shutdown reduces recovery work and ensures the configured final sync behavior runs.

After any unclean stop, wait for startup recovery to finish, run a live ping and representative consistency checks, and inspect events before reopening traffic.

Deployment evidence

Store these together:

• immutable artifact identity and checksum;
• nyxdb --capabilities, --readiness, and --help output;
• full startup arguments and relevant container limits;
• volume/mount identity and capacity;
• backup repository and retention configuration;
• smoke-test output; and
• the last successful restore-drill result.