Installation Docker

Docker Installation & Configuration

Running Bindarr in a Docker container is the recommended deployment method. It packages the Node.js backend, SQLite database engine, image processing dependencies (sharp, onnxruntime-node), and the prebuilt React frontend into a single container image.

---

Quick Start: Docker Compose

Create a docker-compose.yml file in your preferred directory:

services:
  bindarr:
    image: ghcr.io/thenotoriousjeremy/bindarr:latest
    container_name: bindarr
    restart: unless-stopped
    ports:
      - "3001:3001"   # HTTP: Reverse proxy or localhost access
      - "3443:3443"   # HTTPS: Direct LAN access with self-signed certificate
    environment:
      # Optional: Public URL when behind a reverse proxy
      # - PUBLIC_BASE_URL=https://cards.example.com
      # - TRUST_PROXY=1
      # - DEFAULT_ADMIN_PASSWORD=change_this_password
      # - POKEMON_TCG_API_KEY=your_pokemontcg_io_api_key
      # - ALLOW_REGISTRATION=false
    volumes:
      - bindarr-data:/app/database

volumes:
  bindarr-data:

Launch Container

docker compose up -d

View Live Logs

docker compose logs -f

---

Docker Image Tags

The container image is published to GitHub Container Registry (ghcr.io):

Tag	Target	Recommended For
latest	Newest stable release	General production use
1.8, 1.8.1	Specific semantic release version	Strict version pinning & change control
edge	Latest commit on the main branch	Testing upcoming features & early fixes
sha-<commit>	Exact git commit hash	Immutable reproducible builds

---

Storage Volumes & Data Directory

Bindarr stores all persistent data inside /app/database inside the container:

/app/database/
├── bindarr.db              # Primary SQLite database
├── bindarr.db-wal          # SQLite Write-Ahead Log
├── bindarr.db-shm          # Shared memory index
├── backups/                # Automated rolling database snapshots
│   ├── bindarr-2026-08-20T00-00-00.db.bak
│   └── ...
├── models/                 # Computer vision ONNX models & built catalogs
│   ├── cornelius.onnx      # Corner detector
│   ├── milo.onnx           # Visual embedding model
│   ├── milo-pokemon-local.bin
│   └── milo-mtg-local.bin
└── ssl/                    # Auto-generated self-signed TLS cert & private key
    ├── server.crt
    └── server.key

Important: Always use a persistent named volume or bind mount for /app/database. If you mount only a single database file instead of the directory, catalog builds and automatic backups will not persist across container recreations.

---

Environment Variables Reference

All environment variables are optional with sensible defaults:

Variable	Default	Purpose
PORT	3001	HTTP listening port for standard traffic and reverse proxies.
HTTPS_PORT	3443	HTTPS listening port. If left blank (""), the HTTPS server is disabled.
SSL_CERT_PATH	auto-generated	Path to your custom TLS certificate file (.crt / .pem).
SSL_KEY_PATH	auto-generated	Path to your custom TLS private key file (.key).
DB_PATH	/app/database/bindarr.db	Filesystem path to the SQLite database file.
DEFAULT_ADMIN_PASSWORD	(empty)	Pre-sets the password for the auto-created admin account on first boot. Only evaluated when the users table is empty.
ALLOW_REGISTRATION	false	When set to true, permits self-registration from the login screen. When false (default), instance is invite-only via Admin Panel.
POKEMON_TCG_API_KEY	(empty)	API key from dev.pokemontcg.io. Increases rate limits from 1,000 to 20,000 requests/day.
PUBLIC_BASE_URL	(empty)	External base URL (e.g. https://cards.example.com). Used for generating public collection share links.
CORS_ORIGIN	(empty)	Comma-separated list of allowed CORS origins. Localhost and private LAN IP origins are permitted by default.
TRUST_PROXY	(empty)	Set to 1 (or true) when running behind a reverse proxy (Caddy, Nginx, Traefik). Ensures client IP is properly extracted for rate limiting.
CV_MODEL_DIR	/app/database/models	Storage directory for neural network models (cornelius.onnx, milo.onnx) and built scan catalogs.
CV_SCAN_GAP	0.10	Confidence margin threshold for stranger card rejection. Lower values accept more guesses; higher values require distinct artwork separation.
BACKUP_INTERVAL_HOURS	24	Interval in hours between automated database backups. Set to 0 to disable automated backups.
BACKUP_KEEP_LAST	10	Maximum number of rolling backup snapshot files retained in backups/.

---

Updating Bindarr

To upgrade to the latest release while preserving all collections, custom values, and scan catalogs:

docker compose pull
docker compose up -d

Your database migrations and volume files will be automatically loaded and updated on startup.

---

Container Health Check

The container includes a built-in Docker HEALTHCHECK that queries:

GET /api/health

Returns 200 OK with JSON {"status": "ok"}. No authentication is required for this endpoint.