Raspberry Pi with Docker
NonoDB has a published linux/arm64 container image, so a 64-bit Raspberry Pi
can run it without a separate ARM binary. This is the supported path for
Raspberry Pi 4 and Raspberry Pi 5.
This page is a practical deployment note, not a promise that every Pi model is suitable. For real data, use a 64-bit OS and an SSD.
What works
Section titled “What works”| Setup | Status |
|---|---|
| Raspberry Pi 4 / 5, 64-bit Raspberry Pi OS | Recommended |
| Raspberry Pi 4 / 5, 4 GB RAM or more | Recommended |
| Raspberry Pi 3, 64-bit OS, small data set | Possible, but slow |
| 32-bit Raspberry Pi OS | Not supported by the image |
| Raspberry Pi Zero / 1 | Not recommended |
| SD card as the only data disk | Not recommended for writes |
Check the architecture first:
uname -mExpected:
aarch64If it prints armv7l or armv6l, you are on a 32-bit system. The published
container is linux/arm64; reinstall with the 64-bit Raspberry Pi OS.
Prerequisites
Section titled “Prerequisites”- Raspberry Pi 4 or 5 with 4 GB RAM or more;
- 64-bit Raspberry Pi OS Bookworm;
- Docker Engine with the Compose plugin;
- an SSD or USB SSD for the database directory;
- a reliable power supply.
Install Docker using the official Docker instructions for Debian/Raspberry Pi OS. Verify both pieces:
docker versiondocker compose versionAdd your user to the docker group if needed:
sudo usermod -aG docker "$USER"newgrp dockerGet the Compose file
Section titled “Get the Compose file”Clone the repository or download the quickstart file:
git clone --depth 1 https://github.com/essmos/nonodb.gitcd nonodbThe stack is:
deploy/docker-compose.quickstart.ymlPin the image explicitly in production. The file defaults to 0.26.0; you can
override it:
export NONODB_IMAGE=ghcr.io/essmos/nonodb:0.26.0Initialize auth once
Section titled “Initialize auth once”The quickstart stack creates the auth registry and first admin token in a Docker
volume. You do not need nonodb-cli on the Pi:
docker compose -f deploy/docker-compose.quickstart.yml \ --profile init run --rm auth-initCopy the printed bearer token and keep it secret.
Start NonoDB
Section titled “Start NonoDB”docker compose -f deploy/docker-compose.quickstart.yml up -dCheck it:
curl -s http://127.0.0.1:7878/healthzdocker compose -f deploy/docker-compose.quickstart.yml logs -f nonodbThe default port mapping binds only to loopback:
127.0.0.1:7878:7878That is intentional. To use the API from another machine, use an SSH tunnel:
ssh -L 7878:127.0.0.1:7878 pi@raspberrypi.localThen use http://127.0.0.1:7878 on your workstation. Do not expose port 7878
directly to the internet without TLS and a reverse proxy.
Optional GUI
Section titled “Optional GUI”docker compose -f deploy/docker-compose.quickstart.yml --profile gui up -dThe GUI also binds to loopback on port 8787. Use an SSH tunnel:
ssh -L 8787:127.0.0.1:8787 -L 7878:127.0.0.1:7878 pi@raspberrypi.localThen open http://127.0.0.1:8787.
Put the database on an SSD
Section titled “Put the database on an SSD”The quickstart file uses a Docker named volume, which normally lives under
/var/lib/docker. On a Pi, that is often the SD card.
For production, replace the data volume in
deploy/docker-compose.quickstart.yml with a bind mount on the SSD:
services: nonodb: volumes: - /mnt/ssd/nonodb:/var/lib/nonodb - nonodb-auth:/etc/nonodb:roCreate the directory and set ownership to the user inside the image. Get the numeric IDs with:
docker run --rm --entrypoint sh \ ghcr.io/essmos/nonodb:0.26.0 \ -c 'id -u; id -g'Then:
sudo mkdir -p /mnt/ssd/nonodbsudo chown -R UID:GID /mnt/ssd/nonodbUse the values printed by the command above. Keep nonodb-auth as a separate
volume.
Do not put the live LMDB files on NFS or SMB. A local SSD is required for reliable locking, mmap, and fsync behavior.
Updates
Section titled “Updates”docker compose -f deploy/docker-compose.quickstart.yml pulldocker compose -f deploy/docker-compose.quickstart.yml up -dUse a fixed image tag, not latest, so an unexpected pull cannot change the
version under you.
Backups
Section titled “Backups”Do not rely on the SD card or a single SSD. Configure backups to an external destination and test a restore. See Backup and restore and Docker Compose quick start.
Performance expectations
Section titled “Performance expectations”A Raspberry Pi is useful for small, local workloads:
- tenant settings, feature flags, small catalogs;
- background jobs and event queues;
- local edge caches;
- low-to-moderate indexed reads and writes.
Avoid using a Pi as the primary host for:
- large full-collection scans;
- heavy aggregation;
- very large BM25 or vector indexes;
- high write throughput on an SD card;
- workloads that need low p99 latency under sustained load.
Measure with your own data. A Pi 5 with an SSD is in a different class from a Pi 3 with an SD card.
Troubleshooting
Section titled “Troubleshooting”exec format error
Section titled “exec format error”You are probably running 32-bit Raspberry Pi OS. Check:
uname -mIt must be aarch64. Reinstall the 64-bit OS.
no matching manifest for linux/arm/v7
Section titled “no matching manifest for linux/arm/v7”The image is published for linux/arm64, not 32-bit ARM. Use a 64-bit OS or run
NonoDB on another host.
Container starts, then restarts
Section titled “Container starts, then restarts”Check logs:
docker compose -f deploy/docker-compose.quickstart.yml logs nonodbThe most common causes are a missing auth file, wrong ownership on a bind mount, or a port already in use.
Auth init says the file already exists
Section titled “Auth init says the file already exists”The auth volume is already initialized. Skip the init step and start the stack. If you intentionally want to reset all credentials, remove only the auth volume:
docker compose -f deploy/docker-compose.quickstart.yml downdocker volume rm deploy_nonodb-authThe volume name depends on the Compose project name. Check it with:
docker volume lsRemoving the auth volume invalidates all existing bearer tokens.