lucifix/model-workshop-manager repository overview

⁠Model Workshop Manager

Your model kit stash, paint shelf, and builds — self-hosted, on your own hardware.

Website⁠ · Quick start⁠ · Changelog⁠ · Discussions⁠ · Report a bug⁠

No more guessing whether you already own that Revell kit, digging through drawers for the right shade of Tamiya paint, or losing track of build progress. Model Workshop Manager keeps your catalog, inventory, and builds in one place — installable as an app on your phone or desktop, and running entirely on your own server.

⁠Features

• 📦 Stash vs. catalog — a searchable catalog of models and paints, kept separate from what you actually own (and what's on your wishlist).
• 🎨 10,000+ paints in one click — the community miniature-paints⁠ dataset, with names, codes, and colors for 30+ brands: Tamiya, Vallejo, Citadel, Mr. Hobby, AK, Mig, Mission Models, Humbrol, Revell, and more. Find it under Import & Export → Import starter catalog.
• 📷 Barcode scanning — snap the barcode on a kit box and find out straight away if you already own it. Optional UPCitemdb lookup (off by default, enable in Settings) pre-fills name, brand, and box art.
• 🛠️ Builds — start one in a guided flow, log progress with timestamps and photos, and see "required vs. owned" paints for each project.
• 🛒 Shopping list & wishlist — one tap turns a build's missing paints into a shopping list; longer-term wants live in the wishlist.
• 🖌️ Supplies — brushes, cement, masking tape, and other consumables, with low-stock alerts.
• 📊 Dashboard — stash stats, low-stock and missing-paint alerts, and recent activity at a glance.
• 🔁 Import, export & backups — bring in an existing collection (or that spreadsheet you've been keeping) via CSV/JSON, and back up or restore from the UI.
• 📱 Installable app — add it to your phone's home screen or your desktop as a PWA.
• 🔒 Private by default — single-user login, one SQLite file, photos on your own disk. No accounts, no cloud, no tracking.

⁠Quick start (Docker)

Two ways to run it: pull the published image (no clone needed — this is the one to use for a Portainer stack), or build from source.

⁠Option A: pull the published image

Multi-arch (linux/amd64 + linux/arm64 — Raspberry Pi and ARM NAS boxes included):

• GHCR: ghcr.io/lucifix/model-workshop-manager
• Docker Hub: docker.io/lucifix/model-workshop-manager

Paste this straight into Portainer (Stacks → Add stack → Web editor) or save it as docker-compose.yml anywhere — nothing needs to be filled in:

services:
  app:
    image: ghcr.io/lucifix/model-workshop-manager:latest
    container_name: model-workshop-manager
    restart: unless-stopped
    ports:
      - 8080:3000
    environment:
      # Set true once you're serving this over HTTPS, or login will silently fail.
      SESSION_COOKIE_SECURE: "false"
      # Number of reverse proxies in front of the app, if any. Omit if none.
      # TRUST_PROXY: 1
    volumes:
      - workshop-data:/data
      - workshop-backups:/backups

volumes:
  workshop-data:
  workshop-backups:

Everything else (database path, uploads, port inside the container) is baked into the image. For the full file — including the optional nightly-backup sidecar and bind-mount options — use docker-compose.yml⁠ from this repo:

mkdir model-workshop-manager && cd model-workshop-manager
curl -O https://raw.githubusercontent.com/Lucifix/model-workshop-manager/main/docker-compose.yml
curl -O https://raw.githubusercontent.com/Lucifix/model-workshop-manager/main/.env.example
cp .env.example .env          # optional tweaks — nothing required
docker compose pull
docker compose up -d

Updating: docker compose pull && docker compose up -d — see CHANGELOG.md⁠ for what's new.

⁠Option B: build from source

git clone https://github.com/Lucifix/model-workshop-manager.git && cd model-workshop-manager
cp .env.example .env          # optional tweaks — nothing required
docker compose up -d --build  # migrations run automatically on boot

Updating: git pull && docker compose up -d --build

Both options open http://localhost:8080 (or whatever HOST_PORT you set) — first visit shows a one-time setup screen to create your username/password, then you're logged in. To start with a full paint catalog instead of an empty one, open Import & Export → Import starter catalog.

Stopping: docker compose down (your data lives in the workshop-data volume, untouched)

⁠Environment variables

Nothing is required — every variable has a working default.

⁠Local development

A single React Router v8 (framework mode) app → Express → Drizzle ORM → SQLite, one Node process behind Docker Compose. React + TypeScript UI and API resource routes live in the same app; photos live on disk, never as DB blobs.

Requires Node.js 22+ (see .nvmrc — better-sqlite3 needs a matching native build; older Node versions fail silently instead of erroring).

npm install
npm run db:migrate && npm run db:seed   # first time only
npm run dev                              # :3000 — one process, UI + API

Open http://localhost:3000. Run tests with npm test.

⁠Security

This is a single-user private app and it requires login — but login raises the bar, it isn't a substitute for not exposing an unaudited personal app to the open internet. Keep it behind a reverse proxy, LAN-only or on a VPN.

⁠Backup & restore

Three ways to get a backup, easiest first: the Backups tab in the app (create, list, download, restore, delete), an automated nightly snapshot (a docker-volume-backup sidecar container, opt-in — see below), or ./scripts/backup.sh for a manual one from the shell. All three produce the same tarball format, so a backup from any one can be restored via any other.

⁠Contributing

Bug reports, feature requests, and PRs are welcome — see CONTRIBUTING.md⁠ for dev setup and conventions. Please also read the Code of Conduct⁠. Found a security issue? See SECURITY.md⁠ instead of opening a public issue.

⁠License

MIT⁠

If this saves you from buying the same kit twice, a ⭐ helps other modellers find it.