🔬 Meistertracker

Meistertracker is a self-hosted lab management system for mushroom cultivation. Workers walk the lab with phones or tablets, scan barcodes on bags and cultures with the device camera, and the software tracks every fruiting block from inoculation to harvest — across the four phases of the cultivation cycle (spawn run → incubation → fruiting → contamination triage).

Print barcode and QR labels at the workbench, file contamination reports with photos, weigh harvests against KPI dashboards, manage cultures and inventory, and sync tasks and due dates to any CalDAV calendar (Apple Calendar, Google Calendar, Thunderbird, DAVx5). Multi-user with role-based access (worker / admin), MCP integration for Claude Desktop and other LLM clients, offline-capable as a PWA. One Node.js process, SQLite database, no cloud dependencies — runs on Windows, macOS, or Linux (including a Raspberry Pi).

Meistertracker is the operational backbone of Meisterpilze, an urban mushroom farm in Erlangen, Germany, growing shiitake, oyster, king oyster, lion's mane, and blue oyster mushrooms for restaurants, retail, and home growers. Every fruiting block, every culture transfer, and every harvest gram in the lab is tracked through this software — released under AGPL-3.0-or-later so other labs can run, modify, and self-host it freely.

🍄‍🟫 About

Meistertracker is developed and maintained at Meisterpilze UG in Erlangen, Germany — an urban specialty-mushroom farm founded in June 2024 by Dr. Jonas Hahn (research, biologist) and Luis Veloso (production, chemist). In their own words: „Eine Verbindung von Wissenschaft und Natur" — a blend of science and nature in service of better food.

The software was built in-house because no off-the-shelf tool fit how a real mushroom lab actually works: barcode scanning over typing, lifecycle phases that match the fungal biology, and a label printer right at the workbench. It runs daily in our lab and is published under AGPL-3.0-or-later so other labs can build on it freely.

The software is provided without warranty of any kind and the authors accept no liability for damages arising from its use.

AGPL §13 reminder: if you operate this software as a network service for users other than yourself, you must offer them the corresponding source code (including any modifications). The unmodified upstream is at https://github.com/meisterpilze/meistertracker — linking back is usually enough to comply.

See LICENSE for the full terms.

Legal notice: the meistertracker.com domain that redirects to this repository is operated privately by Julian Zienert (Netherlands). See its imprint & privacy notice for how visits to the domain and emails to @meistertracker.com addresses are handled.

✨ Features

Core lab workflow

• Barcode scanning — ADD, MOVE, REMOVE, HARVEST actions via USB-keyboard scanner or phone camera
• Batch management — fruiting blocks and grain spawn bags with full lifecycle tracking
• Culture library — mother cultures, petri dishes, liquid cultures, grain-to-grain spawn with lineage tracing
• Harvest logging — per-bag weight tracking with flush numbers and yield analytics
• Inventory ledger — substrate stock, delivery logging, low-stock alerts, audit trail per change
• Contamination reports — photo upload + on-screen annotations, optional auto-MOVE to CONTAM zone, follow-up tasks
• Task management — auto-generated batch tasks plus manual tasks with team assignment
• CalDAV calendar sync — built-in CalDAV server consumed by Apple Calendar, Thunderbird, DAVx5
• Dashboard — KPIs, production pipeline chart, harvest analytics, rack occupancy, contamination rate
• Label printing — Code 128 + QR labels for Zebra GK420d (50×30 mm, 203 dpi)
• PWA — installable on phones / tablets, offline scan queue replays on reconnect
• Multi-language UI — German, English, Portuguese

Optional modules

• MCP integration — expose batches, cultures, scans, harvests, and maintenance to Claude Desktop via the Model Context Protocol with OAuth + PKCE
• Camera AI (in active development) (mushroom_camera/) — Python sidecar for RTSP-based fruiting and incubation monitoring, writing hourly snapshots back to the same SQLite database
• Print bridge — HTTPS-secured Windows service that forwards label prints from a Linux server to a USB-attached Zebra GK420d
• DuckDNS + Let's Encrypt — built-in dynamic DNS and automatic free TLS for self-hosted public access (no Nginx required)
• Harvest feed — signed, outbound-only push of what you harvested and what is coming, to a URL you choose, so a shop or listing page can answer "what's available today?" without the lab machine being reachable

👥 Who is this for?

• Specialty mushroom farms with 5-50 fruiting tents who have outgrown spreadsheets
• University and commercial fungal labs that need traceable culture lineage, contamination logs, and audit trails
• Mushroom growkit producers doing per-bag QC and harvest analytics
• Fungal R&D labs experimenting with substrates, strain crosses, and yield optimisation

You probably do not need this if you are hobby-growing one or two bags at home — a notebook is fine. If you are tracking 100+ bags across multiple zones with multiple workers, label printers, and offline phone scanners, this is built for you.

🚀 Quick Start

git clone https://github.com/meisterpilze/meistertracker.git
cd meistertracker
bash update_server.sh

On Windows, double-click START.bat instead.

Open https://localhost:3000 in your browser. The server upgrades plain HTTP automatically and (best-effort) binds port 80 for the redirect. For other devices on the same WiFi, use https://<your-ip>:3000 and accept the self-signed certificate warning on first connect.

Prerequisites

• Node.js v22+ — nodejs.org
• Git — repo must be cloned (not just copied)

Setting up a fresh Linux server? See DEPLOYMENT.md for a step-by-step guide covering Node install, PM2, TLS, DuckDNS + Let's Encrypt, and security hardening.

⚙️ Configuration

Create a .env file in the project root to override defaults:

PORT=3000
PRINTER_NAME=ZDesigner GK420d

🖥️ Server Management

Linux / macOS

bash update_server.sh            # Update code, back up data, restart
bash update_server.sh start      # Start (without pulling updates)
bash update_server.sh stop       # Stop the server
bash update_server.sh status     # Show PM2 process status

Both scripts use PM2 for process management and auto-restart, so commands like pm2 logs meisterpilze, pm2 monit, and pm2 list work identically on either platform.

Windows

START.bat does the same job as update_server.sh: it pulls the latest code, installs deps, backs up the DB (using sqlite3 .backup if available, otherwise a file copy), generates a TLS cert if missing, and (re-)starts the PM2 process. Double-click it or run it from a terminal.

Auto-start on boot

Linux — pm2 startup systemd generates a systemd unit, then pm2 save freezes the current process list:

pm2 startup
# copy and run the printed `sudo env PATH=...` line
pm2 save

Windows — two equally valid options:

1. Startup folder shortcut (per-user, runs at logon)

   • Win + R → shell:startup → Enter
   • Right-click in the folder → New → Shortcut → point at C:\path\to\meistertracker\START.bat
   • Optional: in the shortcut Properties, set "Run" to Minimized so the console window doesn't pop into focus.

2. Task Scheduler (more robust — works even without an interactive logon)

   • Open Task Scheduler → Create Basic Task
   • Trigger: At log on (or At startup, if you want it before login)
   • Action: Start a program
     • Program: C:\path\to\meistertracker\START.bat
     • "Start in": C:\path\to\meistertracker
   • Optional: in the task's Settings tab, enable "Run task as soon as possible after a scheduled start is missed".

After either setup, PM2 needs to know the process list to restore. Run once after starting the server normally:

pm2 save

PM2 then writes %USERPROFILE%\.pm2\dump.pm2 and START.bat reads it on the next launch to restore the meisterpilze process.

📷 Scanning Workflow

1. Print the Reference Barcodes page (Print tab) and hang it at your station
2. Scan ADD → scan a location (INC, TENT1, etc.) → scan bag barcodes
3. Scan MOVE → scan FROM → scan TO → scan bags
4. Scan REMOVE → scan bags
5. Scan HARVEST → scan a bag → enter weight

The scan bar works on every tab. Scanners must be in USB Keyboard mode.

📍 Where things are — zones, racks, and the scan that records it

Locations are two levels deep. A zone is a room or a tent (SPAWN, INC, TENT1…3, CONTAM out of the box, renameable in Settings → Zones). A rack belongs to a zone and is whatever shelving unit you can point at and name. Both get a numeric barcode automatically, from the same registry that numbers bags and cultures — you never invent a code by hand.

Scan the rack, not the zone. A zone answers "which tent", which is rarely the question you have at 7 a.m. with a crate in your arms. The app nudges you: scan a zone that has racks under it and the feedback turns amber and names one of its racks as an example. Zone-level scans still work — for a tent you deliberately do not shelf-sort, that is the right granularity.

The labels you need already print themselves

Print tab → Reference barcodes renders every action, zone and rack as Code 128 or QR (one toggle) on ordinary paper:

• Hang the action codes (ADD, MOVE, MOVE_BATCH, REMOVE, HARVEST, CONTAM) at each station.
• Cut out the rack codes and tape one to each rack end, at the height a hand passes.
• Bag and culture labels come off the Zebra when the batch is created; they are the other half of every scan.

That is the whole hardware requirement for location tracking: paper, tape, and a printer you already own.

The truth is in the database, and a human puts it there

There is no automatic localization in Meistertracker, and that is a deliberate limit rather than a missing feature. A block's position changes when someone picks it up, so the moment of handling is the only moment at which anything reliable is known — and it is already the moment a hand is on the block. Radio and camera approaches were evaluated for this lab and do not survive the conditions: dense metal racking puts neighbouring racks inside each other's read range, the fruiting rooms run at ~90 % humidity with active fogging, and blocks behind other blocks are invisible to any fixed lens. Commercial systems in this industry that do track single units track them the same way this one does — a scan on contact, against a location hierarchy.

The practical consequence is worth stating plainly: a move nobody scans did not happen, as far as every dashboard, rack-occupancy chart and MCP answer is concerned. And for multi-row racks, blocks reachable only by moving other blocks are rea