Skip to content

Getting started

This is the shortest path from zero to a running NonoDB with one document and one query. Choose the deployment that fits your environment:

For the full feature inventory, see the documentation index.

You need Docker Engine and the Compose plugin.

Terminal window
docker version
docker compose version

Clone the repository:

Terminal window
git clone --depth 1 https://github.com/essmos/nonodb.git
cd nonodb

Create the auth registry and first admin token:

Terminal window
docker compose -f deploy/docker-compose.quickstart.yml \
--profile init run --rm auth-init

The command prints a bearer token. Copy it and keep it secret.

Start the daemon:

Terminal window
docker compose -f deploy/docker-compose.quickstart.yml up -d

Check health and logs:

Terminal window
curl -s http://127.0.0.1:7878/healthz
docker compose -f deploy/docker-compose.quickstart.yml logs -f nonodb

Insert and query a document:

Terminal window
export TOKEN='paste-token-here'
curl -s -H "Authorization: Bearer $TOKEN" \
-H 'content-type: application/json' \
-X POST http://127.0.0.1:7878/v1/exec \
-d '{"op":"insert","coll":"users","doc":{"name":"Ada","age":36}}'
curl -s -H "Authorization: Bearer $TOKEN" \
-H 'content-type: application/json' \
-X POST http://127.0.0.1:7878/v1/exec \
-d '{"op":"find","coll":"users","filter":{"age":{"$gte":18}}}'

The database is stored in the nonodb-data Docker volume. Stop the stack with:

Terminal window
docker compose -f deploy/docker-compose.quickstart.yml down

down keeps the volumes. Use down -v only when you want to delete the database and credentials.

Optional GUI:

Terminal window
docker compose -f deploy/docker-compose.quickstart.yml --profile gui up -d

Open http://127.0.0.1:8787.

Full Docker guide: Docker Compose quick start.

Every release contains binaries for Linux, macOS, and Windows. Download the archive for your platform from the releases page, verify its .sha256, and extract it.

Linux example:

Terminal window
TAG=v0.26.0
curl -LO "https://github.com/essmos/nonodb/releases/download/$TAG/nonodb-$TAG-linux-x86_64.tar.gz"
curl -LO "https://github.com/essmos/nonodb/releases/download/$TAG/nonodb-$TAG-linux-x86_64.tar.gz.sha256"
sha256sum -c "nonodb-$TAG-linux-x86_64.tar.gz.sha256"
tar -xzf "nonodb-$TAG-linux-x86_64.tar.gz"
cd "nonodb-$TAG-linux-x86_64"

Start the daemon in the foreground:

Terminal window
mkdir -p /tmp/nonodb-data /tmp/nonodb-run
NONODB_DATA=/tmp/nonodb-data \
NONODB_SOCK=/tmp/nonodb-run/nonodb.sock \
RUST_LOG=info \
./nonodb-daemon

Leave that terminal running. In a second terminal:

Terminal window
export NONODB_SOCK=/tmp/nonodb-run/nonodb.sock
./nonodb-cli ping
./nonodb-cli insert users '{"name":"Ada","age":36}'
./nonodb-cli find users '{"age":{"$gte":18}}'

Platform notes:

Requirements:

  • Rust stable with Cargo;
  • a C compiler for LMDB;
  • Node.js only if you need to rebuild the embedded GUI.
Terminal window
git clone https://github.com/essmos/nonodb.git
cd nonodb
cargo build --release

Start the daemon:

Terminal window
mkdir -p /tmp/nonodb-data /tmp/nonodb-run
NONODB_DATA=/tmp/nonodb-data \
NONODB_SOCK=/tmp/nonodb-run/nonodb.sock \
RUST_LOG=info \
./target/release/nonodb-daemon

Use the CLI from another terminal:

Terminal window
NONODB_SOCK=/tmp/nonodb-run/nonodb.sock \
./target/release/nonodb-cli count users '{}'
  • Daemon: one nonodb-daemon owns the LMDB files. Do not start two daemons against the same data directory.
  • Database: one daemon can host multiple independent databases under NONODB_DATA.
  • Collection: a named group of JSON documents.
  • Document: a JSON object. _id is generated if omitted.
  • Index: optional secondary index for filters, sorting, unique constraints, text, fuzzy, vector, or geospatial queries.
  • Auth: TCP requires NONODB_AUTH_FILE. Unix sockets can use peer credentials instead.

Configuration essentials:

Variable Purpose
NONODB_DATA Instance root containing database directories
NONODB_SOCK Unix socket path
NONODB_TCP TCP listen address, e.g. 127.0.0.1:7878
NONODB_AUTH_FILE Auth registry; required for TCP
NONODB_MAP_SIZE LMDB address-space limit, not a RAM reservation

See Operations for all environment variables.