Remember where everything lives.
Findus is a self-hosted inventory manager that organizes your physical world — rooms, shelves, boxes, and the items inside them — with a hierarchical structure that mirrors how real storage works.
Scan a QR code on any box and land directly on its page. No SaaS, no subscriptions, your data stays on your machine.
| Problem | Findus solution |
|---|---|
| "Where did I put the camping gear?" | Nested locations: Basement → Metal shelf → Box 3 |
| Printing labels for boxes | Built-in QR codes — stick, scan, done |
| Shared space with a partner or team | Multi-user accounts with role-based access |
| Afraid of cloud lock-in | SQLite on disk, ZIP backup from the admin panel |
| Complex self-hosted setup | Single binary, one Docker Compose file |
- Hierarchical locations — Model your actual storage: rooms contain shelves, shelves contain boxes, boxes contain items. No artificial depth limit.
- Item templates — Pre-defined field sets (electronics, clothing, tools…) so you only fill in what matters for each category.
- Photos — Attach images to locations and items; Findus auto-converts and compresses to WebP.
- QR codes — Every location and item gets a scannable code. Scanning redirects straight to its page using your configured base URL.
- Full-text search — Find anything by name, description, or custom field value (FTS5-powered, with a LIKE fallback).
- Command palette — Keyboard-driven search overlay for quick navigation.
- Role-based access — First registered user becomes admin. Admins manage users, templates, labels, and settings; regular users browse and edit inventory.
- Registration modes — Open, invite-only, or admin-only: you control who can sign up.
- One-click backup — Admins download a ZIP containing the SQLite snapshot and all images.
- No external dependencies — Single Go binary, SQLite, embedded Vue SPA. No Redis, no Postgres, no cloud services.
Requirements: Docker with the Compose plugin (v2).
cp .env.example .envdocker compose pull
docker compose up -dNavigate to http://localhost:8080.
The first account you register becomes the admin. Subsequent registrations follow the mode configured in admin settings (default: open).
GET http://localhost:8080/healthz → 200 ok
docker compose down # stop containers, keep data volume
docker compose down -v # stop containers AND delete all dataData is persisted in a Docker named volume (findus_data), mapped to /data inside the container.
All settings are environment variables. Copy .env.example as a starting point.
| Variable | Default | Required | Description |
|---|---|---|---|
FINDUS_PORT |
8080 |
No | TCP port the server listens on |
FINDUS_DATA_DIR |
./data (/data in Docker) |
No | Root directory for the SQLite database and images/ folder |
FINDUS_BASE_URL |
http://localhost:8080 |
No | Public URL users type in the browser — embedded in every QR code |
FINDUS_JWT_SECRET |
(auto-generated) | No | HS256 signing secret. If empty, Findus creates or loads $DATA_DIR/.jwt_secret |
FINDUS_COOKIE_SECURE |
false |
No | Set true when serving over HTTPS so session cookies are Secure |
FINDUS_LOG_LEVEL |
info |
No | debug · info · warn · error |
FINDUS_LOG_FORMAT |
text |
No | text (key=value) or json (structured — for log aggregators) |
- Terminate TLS at Caddy, nginx, Traefik, etc. and forward plain HTTP to Findus on its port.
- Set
FINDUS_BASE_URLto the https URL — e.g.https://findus.example.com. QR codes embed this URL. - Set
FINDUS_COOKIE_SECURE=trueso session cookies are only sent over HTTPS.
Common issue: scanning a QR code opens the wrong host or shows a browser error?
The most likely cause isFINDUS_BASE_URLpointing at the wrong scheme or hostname.
See Configuration for the full reference.
The docker-compose.yml in this repo pulls ghcr.io/bueckerlars/findus:latest from GitHub Container Registry.
git clone https://github.com/your-org/findus.git && cd findus
make build # builds frontend assets, then compiles ./bin/findus
./bin/findus # runs on :8080 with ./data as the data directoryFull development workflow: Development.
Admins can download a ZIP snapshot (SQLite database + all images) from the admin panel, or by visiting /admin/backup.zip.
The ZIP contains:
findus.db— consistent SQLite snapshotimages/— all uploaded photos
To restore: stop the container, extract the ZIP into your data directory, restart.
Full procedure: Backup & Restore.
| Page | What it covers |
|---|---|
| Architecture | Go layers, Vue SPA, SQLite, security model |
| Configuration | All environment variables, HTTPS setup, Docker Compose variants |
| Development | Local toolchain, Makefile targets, hot reload, tests |
| Routes | HTTP API surface (public, authenticated, admin) |
| Backup & Restore | Backup contents and step-by-step restore |
Contributions are welcome — bug reports, feature suggestions, and pull requests alike. See CONTRIBUTING.md for the full guide including setup, code style, and PR process.
MIT — see LICENSE.