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:
- Docker Compose — recommended for a first run;
- prebuilt binary — no Docker;
- build from source — for development.
For the full feature inventory, see the documentation index.
Docker Compose (recommended)
Section titled “Docker Compose (recommended)”You need Docker Engine and the Compose plugin.
docker versiondocker compose versionClone the repository:
git clone --depth 1 https://github.com/essmos/nonodb.gitcd nonodbCreate the auth registry and first admin token:
docker compose -f deploy/docker-compose.quickstart.yml \ --profile init run --rm auth-initThe command prints a bearer token. Copy it and keep it secret.
Start the daemon:
docker compose -f deploy/docker-compose.quickstart.yml up -dCheck health and logs:
curl -s http://127.0.0.1:7878/healthzdocker compose -f deploy/docker-compose.quickstart.yml logs -f nonodbInsert and query a document:
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:
docker compose -f deploy/docker-compose.quickstart.yml downdown keeps the volumes. Use down -v only when you want to delete the
database and credentials.
Optional GUI:
docker compose -f deploy/docker-compose.quickstart.yml --profile gui up -dOpen http://127.0.0.1:8787.
Full Docker guide: Docker Compose quick start.
Prebuilt binary
Section titled “Prebuilt binary”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:
TAG=v0.26.0curl -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:
mkdir -p /tmp/nonodb-data /tmp/nonodb-run
NONODB_DATA=/tmp/nonodb-data \NONODB_SOCK=/tmp/nonodb-run/nonodb.sock \RUST_LOG=info \./nonodb-daemonLeave that terminal running. In a second terminal:
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:
- Linux: Run on Linux
- macOS: Run on macOS
- Windows: Run on Windows
Build from source
Section titled “Build from source”Requirements:
- Rust stable with Cargo;
- a C compiler for LMDB;
- Node.js only if you need to rebuild the embedded GUI.
git clone https://github.com/essmos/nonodb.gitcd nonodbcargo build --releaseStart the daemon:
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-daemonUse the CLI from another terminal:
NONODB_SOCK=/tmp/nonodb-run/nonodb.sock \ ./target/release/nonodb-cli count users '{}'First concepts
Section titled “First concepts”- Daemon: one
nonodb-daemonowns 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.
_idis 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.
Next steps
Section titled “Next steps”- HTTP API — operations, filters, updates, aggregation, errors.
- SQL queries — SQL alongside the document API.
- Indexes and search — secondary, text, fuzzy, vector.
- MongoDB compatibility — official drivers and the supported subset.
- Authentication — principals, tokens, certificates, lockout.
- Backup and restore — backups, encryption, verification, drills.
- Operations — deployment, monitoring, capacity, troubleshooting.
- Docker Compose — self-contained stack and GUI.
- Raspberry Pi — 64-bit Pi 4/5 with Docker.