# Nupplo SE 🧱 > **Formerly Brickfolio.** Since 3.0.0 the app is called **Nupplo SE** – SE > stands for *Server Edition*, the edition you run yourself. Same app, new > name; existing installations keep running without any change. *🇬🇧 English · [🇩🇪 Deutsch](README.md)* [](https://buymeacoffee.com/melle79) [](LICENSE) A self-hosted PWA to scan, manage and value a LEGO® collection – built for the whole family on one shared database, with an optional **Collector-Pro mode** for anyone who buys and sells at flea markets. **Photo → recognition → collection.** Recognition runs on the free [Brickognize API](https://brickognize.com); prices, set inventories and metadata come from [BrickLink](https://www.bricklink.com) and [Rebrickable](https://rebrickable.com) (your own API keys required, see below). > 📖 The full **user manual** lives at [`docs/MANUAL.md`](docs/MANUAL.md) > · [🇩🇪 deutsche Fassung](docs/HANDBUCH.md). ## Features **Capture & manage** - 📷 Scan minifigures and sets straight from the phone camera (candidate list with match score) or search by name/number – plain numbers are looked up as both a set *and* a figure automatically - 📦 Quantities, condition (new/used), notes, image gallery, full-text search (with 🔍 icon and ✕ to clear), sorting and type filter; optional **grid view** (two per row) for browsing - 🔎 Catalogue search from three characters, **10 hits per page** with “load more results” – every match is reachable - 👥 **Add a set's figures with it**: when a set enters the collection, the app asks which of its minifigures are included (all, none or a selection, with their own condition) – without double-counting them in the total value - 👥 Set linking: sets know their figures (“👥 3/4 ✔” completeness), figures show which of your sets they belong to; missing set figures move to the wishlist with a single tap - 🖼 **Reload the image** for an entry if it is missing or wrong - 🔎 **Detail view everywhere**: tapping a search or scan hit opens a popup with year, theme, prices and – for minifigures – the **parts they contain, with colour names** - 🎨 **Custom figures**: home-made builds with a number the app assigns for you (`custom-001`, `-002` …) and your own picture – optionally the photo straight from the scan. They live under the “Custom” theme - 🗂️ **Theme cards**: sorted by theme, the collection shows collapsible cards (Star Wars, City, Custom …) with count and value per theme. The last sort order is remembered per profile **Prices & value** - 💶 BrickLink average prices (new/used) fetched automatically in the background, with a built-in **price-history log** and per-item chart - 🌍 **Selectable price region** (More → Price region): worldwide, Germany, Austria, Switzerland or Europe – with no sales in the chosen region the app widens in two steps (Europe first, then worldwide). Existing prices can be recalculated step by step, priceless items re-fetched with one click. In the item details a small **flag** (🇩🇪/🇪🇺/🌍) on every price row shows where the price comes from - 🏷 **Asking prices** (optional): on top of the average sale price, *from how much* a figure is available right now – in the item details and as a tag in wish and shopping lists - 📊 **Stats tab**: key figures, overall value trend, split by type/condition, value by release year (tap a bar for the year’s details), Top 10 **Wishlist** - ⭐ Save from any scan/search result, average-price widgets, “bought” hand-off into the collection incl. condition choice - 🧩 Figures that belong to one of your sets and are still missing are flagged with “missing from your set” – a tap jumps straight to the set **Trading network** (optional, invite only) > **It is off by default, and nothing is shared.** Your collection stays on > your server. The network only exists for you once you join with an > invitation code – and even then only what you explicitly choose goes out: > the items you offer, your profile and, if you switch it on, your wishlist. > Leaving takes everything out again. - 🤝 Several Nupplo instances connect through a small **trading hub**: everyone offers the items they want to pass on – **for trade, for sale or both** – and sees what the others offer - 🔢 **You pick what goes in**, and how many: out of three identical figures you can offer just one - 🧭 **Discover**: who has what you're looking for, who wants what you have spare, and who collects the same themes – worked out on your own instance - 👤 **Profiles**: about me, area, favourite themes, trade record – all optional; the collection size only rounded and only if you want - 📦 **Trades with a beginning and an end**: accepted → sent → arrived → booked → completed. Adding and removing book straight into the collection, purchase log included - 💬 **Messages are end-to-end encrypted** (X25519 + AES-256-GCM). The hub cannot read them and deletes them once delivered; the readable history stays on the instances involved - ✉️ **Invitations with a quota**: everyone may invite three friends and can request more. Nobody gets in without an invite - ⏸ **Pause after inactivity**: if you haven't been around for a while, the hub hides your offers until you come back - ⚑ **Reports with a follow-up**: the report stays visible to the reporter, the hub admin can ask questions and take a measure (notice, warning, block) that the person concerned sees in their app – without learning who reported them - 🖼️ Custom figures travel with a **downscaled thumbnail** so the other side doesn’t just see a placeholder **Collector-Pro mode** (a role the admin grants per user) - 💰 Purchase price per entry – pre-filled with the BrickLink average of the capture day (⚙️) or entered manually (✏️), with profit/loss display - 🛒 **Shopping lists** for the flea market: fill by scanning, live market value, purchase price per item, a **bundle offer** with proportional distribution by market value and a 60 % price suggestion - 📋 **Sell list**: every duplicate with its giveaway quantity and sale value – figures needed for your own sets stay reserved, everything else keeps one copy for you - 🧩 **Missing set figures**: across all your sets, which minifigures are still missing (count, sets, estimated cost) – add them to the wishlist one by one or all at once, export as CSV or print - 🗒 When receiving from a shopping list, the **list name is written into the notes** of the collection entry (origin stays traceable) - 📈 Extra stats: total paid, profit, best value gains **Family & operations** - 🔐 Multi-user with token login (PBKDF2-hashed passwords), admin and pro roles (admins can appoint further admins), self-service password/name change - 💾 Full **backup** as JSON (download & restore), CSV export and print-ready lists - 🏷 Configurable **display name** in logo and title (empty by default); ideal when several family members each run their own instance - 🌌 Three **themes** to choose from (More → Design): light “Classic”, dark “Galaxy” with a starfield, and “Nova” – a modern glass design with a blue accent; the choice is per device - 🔔 **Notices on the start screen**: if BrickLink renames or removes a number from your collection, it shows up in the Scan tab – and stays there until someone dismisses it. The app looks up the new number in the BrickLink Catalog Change Log and applies it everywhere with one click - 🌐 **External-access helper** (More → External access, admin): turns your Cloudflare tunnel token into a ready-to-paste `docker-compose` block – reach the app on the go without port forwarding. The app never starts the tunnel itself (no Docker access); the token stays in the browser - 🐞 **Error report** (More → Error report, admin): errors from every device report themselves to your own server and identical ones are grouped. With a GitHub token stored, one click turns an entry into an issue; API keys and the token are stripped from the text first - 🖥 **Responsive to screen width**: bottom tab bar on phones, a left sidebar with a wider grid (four to five cards per row) on desktop – same app, just laid out to use the space - ✨ **Modern look**: items open in a window that leads with the **image across the full width**; below it the name, tags and – for dealers – three tiles (paid, value, profit). The rest sits on three tabs (copy, prices, more) instead of stacking up. In the collection the product image shows as a subtle card background - 📲 Installable as a PWA – on a phone the scan page offers to put it **on the home screen** (a button on Android, instructions on iPhone) and hides the hint once it is there. Offline shell, no cloud – everything stays on your own server ## Screenshots | Scan | Collection | |:---:|:---:| | | | | **Stats** | **Shopping list (flea-market mode)** | | | | *(Screenshots with demo data)* ## Quick start (Docker) No source code, no build – two commands: ```bash mkdir nupplo && cd nupplo curl -sLo docker-compose.yml https://raw.githubusercontent.com/Melle79/nupplo/main/docker-compose.example.yml docker compose up -d ``` Open `http://:8300` – on first visit a **setup wizard** walks you through everything: admin account, display name, API keys (with a test button) and, if you have one, your invite to the trading network. Every step can be skipped; anything can be added later under *More*. The database is stored persistently at `./data/brickfolio.db`. The image (`ghcr.io/melle79/nupplo:latest`, mirrored as `melle79/nupplo:latest` on Docker Hub) is built for **amd64** – that is **x86-64**, any ordinary Intel *or* AMD machine (Synology, Intel NAS, PC) and **arm64** (Raspberry Pi, ARM NAS). ### Synology NAS No shell needed: **Container Manager → Project → Create**, paste the YAML, done. Step by step in [`docs/SYNOLOGY.md`](docs/SYNOLOGY.md) (in German). Over SSH it works just as well – create `/volume1/docker/nupplo` and run the commands above with `sudo`. ### Other NAS systems and computers It is an ordinary OCI image on two public registries – it runs wherever containers run. Same YAML as above, just pasted somewhere else: | System | Where the YAML goes | |---|---| | **QNAP** | Container Station → *Applications* → Create | | **UGREEN** | Docker → *Project* → Create | | **TerraMaster** | Docker Manager → *Compose* | | **Asustor** | Portainer (from App Central) → *Stacks* | | **Unraid** | Docker tab, or *Compose Manager* from Community Apps | | **TrueNAS SCALE** | Apps → *Custom App* (YAML) | | **OpenMediaVault** | omv-extras → Compose → *Files* | | **Linux / Raspberry Pi / Mac / Windows** | create a folder, `docker compose up -d` | Very old 32-bit ARM devices (`armv7`) are not supported. **Unraid** has it easier: under *Docker → Settings → Template Repositories* add this address – ``` https://github.com/Melle79/unraid-templates ``` – and Nupplo appears under *Docker → Add Container* in the template picker, with the port, the `/data` path and the optional keys pre-filled. The template is maintained in [Melle79/unraid-templates](https://github.com/Melle79/unraid-templates); a copy lives here under [`unraid/brickfolio.xml`](unraid/brickfolio.xml). ### Hosted instead of at home If you would rather not run your own hardware, rent the instance. **It belongs to whoever creates it** – data, cost and access. There is still no Nupplo service in between. | Provider | How | Note | |---|---|---| | **Render** | [](https://render.com/deploy?repo=https://github.com/Melle79/nupplo) | Reads [`render.yaml`](render.yaml). Needs the smallest **paid** plan: Nupplo requires a persistent disk for `/data`, and the free plan has none | | **Railway** | New project → *Deploy from GitHub* → this repo, then set *Settings → Config-as-Code* to `deploy/railway/railway.json` | Afterwards attach a **volume** at `/data`, otherwise the collection is gone after every restart | | **Coolify / Dokploy** | Paste `docker-compose.example.yml` | On your own VPS, full control | > **Why no free plan?** Without a persistent disk the database lives inside > the container – every restart would wipe the collection. Better an honest > note than a deployment that quietly loses data. Without a compose UI: ```bash docker run -d --name nupplo --restart unless-stopped \ -p 8300:8300 -v /path/to/data:/data \ ghcr.io/melle79/nupplo:latest ``` ### Building it yourself (instead of the ready-made image) Only needed if you want to run your own changes: ```bash mkdir nupplo && cd nupplo curl -sL https://github.com/Melle79/nupplo/archive/refs/heads/main.tar.gz | tar xz --strip-components=1 cp docker-compose.example.yml docker-compose.yml sed -i 's|image: ghcr.io/melle79/nupplo:latest|build: .|' docker-compose.yml docker compose up -d --build ``` ## Configuration | Variable | Required | Description | |---|---|---| | `ADMIN_USER` / `ADMIN_PASSWORD` | no | Optional: create the admin automatically (otherwise via browser setup) | | `DB_PATH` | no | Path to the SQLite file (container default: `/data/brickfolio.db`) | | `BL_CONSUMER_KEY` / `BL_CONSUMER_SECRET` / `BL_TOKEN` / `BL_TOKEN_SECRET` | no | BrickLink Store API for prices & set inventories ([request a key](https://www.bricklink.com/v2/api/register_consumer.page)) | | `BACKUP_KEEP` | no | Keep this many automatic daily backups (default 14, 0 = off) | | `REBRICKABLE_KEY` | no | Rebrickable API for name search ([create a key](https://rebrickable.com/api/)) | | `GITHUB_REPO` | no | Target repository for issues from the error report (default `Melle79/nupplo`) | | `BRICKFOLIO_NAME` | no | Display name in logo/title (empty by default); also settable in-app | All API keys can alternatively be stored **in the app** (More → API keys, admin only) – environment variables serve as a fallback. ## Permissions overview | Action | Default | Collector-Pro | Admin | |---|:-:|:-:|:-:| | Scan, collection, wishlist, stats | ✔ | ✔ | ✔ | | See shopping lists & mark an item “received” | ✔¹ | ✔ | ✔¹ | | Create/fill/archive lists, bundle offer, sell list | – | ✔ | – | | See purchase prices & profit | – | ✔ | – | | Users, roles, API keys, backup | – | – | ✔ | ¹ The tab only appears when at least one active list exists. Roles combine (the admin can grant themselves the pro role). ## Updates & backup **The app tells you.** Under *More → Version & updates* it compares the running version against the latest release, whichever way you installed. **With the ready-made image** (the quick start above), two commands in the project folder: ```bash docker compose pull && docker compose up -d ``` On a Synology the same works without a shell: *Container Manager → Project → nupplo → Action → Build and restart*. The `data/` folder is untouched, database migrations run automatically on start and are idempotent. **A snapshot beforehand never hurts** – download the JSON file in the app under *More → Backup*. > `update.sh` and `update-watch.sh` are **not** in the image and not in your > folder if you only fetched the `docker-compose.yml`. If you want them > (automatic snapshot, updating from inside the app), fetch them once: > > ```bash > curl -sLO https://raw.githubusercontent.com/Melle79/nupplo/main/update.sh > curl -sLO https://raw.githubusercontent.com/Melle79/nupplo/main/update-watch.sh > ``` **Built from source**: `sudo bash update.sh` in the project folder. It takes a database snapshot first (the last three are kept) and detects on its own whether to pull the image or rebuild. ### Updating from inside the app (optional) **Entirely optional** – without setup nothing changes and updates keep working via `update.sh` over SSH. The button only appears once the helper below is in place; until then the app just points to it. **How it works.** The app does **not** run the update itself – it can’t, since it lives inside the container. It only writes `data/update-requested.json`. A small script on the server picks that up and runs `update.sh`. That way the app needs **no Docker access** – handing the socket to a container is effectively root on the host. #### Setup Run `update-watch.sh` regularly. **Once a minute is plenty** – the update itself takes one to three minutes anyway. **Synology (DSM):** Control Panel → Task Scheduler → Create → Scheduled Task → User-defined script | Tab | Setting | | --- | --- | | General | User: **`root`** (otherwise the script may not run `docker compose`) | | Schedule | Daily · start `00:00` · “Continue running within the same day” ✔ · repeat **every minute** · last run time: **`23:59`** | | Task Settings | Command: `sh /path/to/nupplo/update-watch.sh` | > ⚠️ “Last run time” defaults to `00:59` – the task would then only run during > the first hour of the day. Set it to `23:59`. **Linux with cron:** `* * * * * sh /path/to/nupplo/update-watch.sh` #### Multiple instances Running several Nupplos (each in its own folder with its own `docker-compose.yml`)? Prefer **one task per instance**. That is the most robust setup: each runs independently, and the task scheduler shows you per instance whether it succeeded. If you would rather use a single task, append `|| true` to every line: ```sh sh /volume1/docker/nupplo/update-watch.sh || true sh /volume1/docker/nupplo-zweit/update-watch.sh || true ``` > ⚠️ Without `|| true` the second line may never run: if the first one exits > with an error (missing permissions, say), the scheduler aborts the whole > script and the second instance never gets a heartbeat. Either way the instances stay independent – each has its own marker in its own `data` folder, so updating one leaves the other alone. #### Flow The admin picks now / 1 min / 5 min → every signed-in browser shows a countdown (“please finish your edits”), then a lock screen. Once the server is back, the browsers reload themselves. While the countdown runs, the admin can cancel. - The helper touches `data/update-watch-alive` on every run. That is how the app knows it is set up – if the heartbeat is older than five minutes, the update is not offered at all. - Log of every run: `data/update-watch.log`. - Backup: in-app under More → Backup (JSON with all data incl. users and price history) **or** simply copy `data/brickfolio.db`. ## Tech FastAPI + SQLite (no ORM) · Vanilla-JS PWA (no build step) · Docker deployment · APIs: Brickognize, BrickLink Store API (OAuth1), Rebrickable. ### What lives in its own repo This repo holds the **program**. Three things beside it move at their own pace and therefore have their own repo – all three private, because they describe credentials or carry screenshots of a real collection: | what | repo | for | |---|---|---| | project site brickfolio.cc | `brickfolio-website` | static Cloudflare Worker, published by hand | | catalogue service | `brickfolio-katalogdienst` | builds the catalogue index and writes it here, encrypted, to `katalog/index.nupplo` | | hub console | `brickfolio-hub-admin` | interface for running the trade network | | trade hub | `brickfolio-hub` | Cloudflare Worker + D1 that instances talk to for trading | The app itself only talks to the hub over HTTP; it does not need its source. ## Legal LEGO® is a trademark of the LEGO Group, which does not sponsor, authorise or endorse this project. BrickLink, Rebrickable and Brickognize are trademarks of their respective owners; their APIs are subject to their respective terms of use. This is a private hobby project with no commercial intent. Data and images come from Rebrickable (catalogue search), BrickLink (prices, set contents, images) and Brickognize (image recognition – taking a photo sends it there). The same notes are shown in the app under **More → Sources & legal**. The **Nunito** typeface (SIL Open Font License 1.1, licence text in `frontend/fonts/OFL.txt`) is served locally – so no visitor data goes to font CDNs, and the interface still looks right when the server has no internet connection. ### What works without internet Your collection and the interface both live on your own server. If the server is reachable on the local network but has no internet, these keep working: - browsing and editing the collection, wishlist and shopping lists - manual entry, including custom figures with your own picture - statistics, CSV export and print lists - downloading and restoring a backup Everything that asks the outside world needs internet: **scanning** (Brickognize), **search by name** (Rebrickable), **prices and set contents** (BrickLink), the **catalogue images** (they are hosted on their servers – images you uploaded yourself are not), the **update check** and the **trading network**. With no server reachable at all, the installed PWA still loads its interface from the cache but shows no data – data always comes live from your own server, none of it is kept in the browser. ## Support Nupplo is a private hobby project and free to use. If you like it and want to support development, I'd be happy about a coffee ☕ ## License [MIT](LICENSE) for the program code. The figure catalogue in `katalog/` is excluded: it may only be used within Nupplo, see [katalog/LIZENZ.md](katalog/LIZENZ.md).