Docker Compose quick start
This page uses the self-contained
deploy/docker-compose.quickstart.yml
stack. It needs only Docker and Docker Compose; you do not need to install
nonodb-cli on the host.
The stack:
- runs the daemon as the unprivileged
nonodbuser; - stores database files in the
nonodb-datavolume; - stores the auth registry in the separate
nonodb-authvolume; - initializes the auth registry and first admin token with a one-shot
auth-initservice; - exposes the HTTP API on
127.0.0.1:7878; - offers an optional GUI profile on
127.0.0.1:8787.
TCP always requires authentication. NonoDB has no default password, so the first run must create the registry and a token.
1. Create auth and the first token
Section titled “1. Create auth and the first token”From the repository root:
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:
created /etc/nonodb/auth.json; now run: nonodb-cli auth token create admin<token>The auth-init service runs as root only for this one-shot setup. It writes the
registry into the nonodb-auth volume and then changes ownership to the
unprivileged nonodb user. The daemon itself never runs as root.
Run this command only once per auth volume. If it reports that the file already exists, the registry is already initialized.
2. Start the daemon
Section titled “2. 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 nonodb3. Use the API
Section titled “3. Use the API”Set the token printed by auth-init:
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":{}}'Python client:
from nonodb import NonoDB
db = NonoDB(base_url="http://127.0.0.1:7878", token="paste-token-here")print(db.collection("users").find({}))db.close()Optional GUI
Section titled “Optional GUI”Start the GUI profile:
docker compose -f deploy/docker-compose.quickstart.yml --profile gui up -dOpen http://127.0.0.1:8787. The GUI talks to the daemon over the shared Unix
socket and does not need the bearer token.
Stop, update, and remove
Section titled “Stop, update, and remove”Stop containers but keep data and auth:
docker compose -f deploy/docker-compose.quickstart.yml downUpdate the image:
docker compose -f deploy/docker-compose.quickstart.yml pulldocker compose -f deploy/docker-compose.quickstart.yml up -dPin a version in production. The default example uses 0.26.0; override the
image explicitly if needed:
NONODB_IMAGE=ghcr.io/essmos/nonodb:0.26.0 \ docker compose -f deploy/docker-compose.quickstart.yml up -dRemove containers and volumes only when you intend to delete the database and all credentials:
docker compose -f deploy/docker-compose.quickstart.yml down -vBackups and auth
Section titled “Backups and auth”Back up the database with the normal backup API, scheduled backup jobs, or
nonodb-cli backup. See Backup and restore.
The auth registry is in the separate nonodb-auth volume. Back it up if you
want to preserve existing tokens and principals. If it is lost, the database is
still intact, but you must initialize a new registry and issue new tokens.
For filesystem compression, put nonodb-data on a ZFS/Btrfs bind mount instead
of a named volume; see Volume compression.
Troubleshooting
Section titled “Troubleshooting”auth-init says the file already exists
Section titled “auth-init says the file already exists”The nonodb-auth volume already has a registry. Skip the init step and start
the daemon. If you intentionally want to reset all credentials, stop the stack
and remove only the auth volume:
docker compose -f deploy/docker-compose.quickstart.yml downdocker volume rm nonodb-authThis invalidates all existing bearer tokens.
Port already in use
Section titled “Port already in use”Change the host side of the port mapping, for example:
ports: - "127.0.0.1:7879:7878"Then use http://127.0.0.1:7879 in clients.
Permission denied in the auth volume
Section titled “Permission denied in the auth volume”Use the provided auth-init service rather than writing auth.json by hand.
It sets ownership to the user the daemon runs as. Do not mount the auth volume
read-write into the daemon.
I want a host auth file instead of a volume
Section titled “I want a host auth file instead of a volume”The repository also includes deploy/docker-compose.yml,
which uses a Compose secret from a host file. That variant is useful when the
auth registry is managed by the host or another secret manager.