An open-source trading card scanner and physical sorter. A camera identifies each card with on-device image embeddings, a rule engine picks its bin, and a feeder plus servo modules driven by an Arduino or ESP32 drop it there. Collections, storage boxes, prices, stats and integrations live in the same app.
- Hosted app: mault.xyz
- Printable sorter: MakerWorld
- Build guide (BOM, wiring, assembly):
/buildin the app
Magic: The Gathering, Pokemon, Yu-Gi-Oh, One Piece, Lorcana, Gundam, Flesh and Blood, Riftbound, Grand Archive, Star Wars: Unlimited, Cyberpunk, Sorcery: Contested Realm.
Each game is a pluggable adapter (packages/server/src/lib/adapters/<game>/) plus a Game row in the admin Games Manager, whose field definitions drive rules, sorting, filters and notifications for that game.
- The feeder pushes a card from the hopper into the camera's calibrated scan region and waits for it to settle at the IR sensor.
- The client finds the card's four corners, dewarps it and embeds it with CollectorVision's corner detector and Milo embedder (ONNX, in the browser or on the phone). If the client can't run the models, the server embeds the image instead.
- The server finds the closest cards by comparing the embedding against its in-memory index of every card vector (stored in Postgres with pgvector). When printings look alike, OCR of the name, set and number breaks the tie; weak matches are flagged for review.
- The collection's active bin preset decides the bin (rules, auto-assign, repack, alphabetical, chaos, pick lists, overflow and copy limits), client-side.
- The client tells the sorter which module and direction to use, over USB serial, Bluetooth or Wi-Fi, and saves the scan in parallel.
Scanning
- Webcam scanning in the browser, or a paired phone used as the camera (QR pairing)
- Several sorters from one browser tab, each with its own camera and collection
- Multi-language scanning, OCR tie-breaking, a review mode for low-confidence matches and one-click corrections
- Offline-tolerant saves: scans queue in IndexedDB and retry until the server accepts them
Sorting
- Bin presets per collection with and/or rule trees over each game's own fields, plus override bins that win over ordinary ones
- Auto bin assignment, repack building, alphabetical drill-down, chaos sort, overflow bins, copy limits and decklist pick lists
- Custom sounds played when matching cards are sorted
Collections and value
- Multiple organizations and collections, with roles, invites and an audit log
- Storage locations: empty a bin into a box and Mault records each card's position, searchable and exportable as CSV
- Prices from TCGplayer, Cardmarket and Card Kingdom, with per-org price source and condition multipliers
- Stats, a leaderboard and live remote monitoring (or a shareable read-only monitor link)
Integrations
- Discord bot:
/linka server to an org,/statsfor collection stats; scan, alert and rule-based channels are configured in Settings > Integrations - Public REST API with org API keys and signed webhooks, following Scryfall's conventions (docs/public-api.md, reference site in
packages/api-docs)
Hardware
- Calibration for servos, feeder, bin heights, routes and the camera's scan region, with a guided tour
- In-browser firmware flashing, firmware feature gating, device self-test and session locks
- Wi-Fi remote control for ESP32 boards, relayed through the server
- Native iOS/Android app (packages/mobile) that scans with the phone camera and drives a sorter over Bluetooth
Plans
- Free and Business tiers (Stripe), with features and limits editable in Admin > Plans
packages/
├── shared/ @magic-vault/shared types, constants, zod schemas, rule engine, vision + serial protocol (no build step)
├── server/ @magic-vault/server Hono API, Drizzle schema, auth providers, sync and price jobs
├── web/ @magic-vault/web React SPA: landing, build guide, scanner, calibration, admin
├── mobile/ @magic-vault/mobile Expo iOS/Android app
├── bot/ @magic-vault/bot Discord bot, talks to the server over HTTP only
└── api-docs/ @magic-vault/api-docs Scalar reference for the public API (openapi.json)
firmware/ Sorter sketch (firmware/main/*.ino) and wire protocol (firmware/PROTOCOL.md)
3d model/ Fusion 360 / STEP source and printable .3mf
drizzle/ Generated SQL migrations
docs/ Public API guide
docker/ Web container start-up script (runtime env.js)
scripts/ Release and version helpers, plus scripts/pi for a Raspberry Pi host
.github/ Build check, deploy, firmware PR check and firmware release workflows
CLAUDE.md records the project's conventions and invariants; CONTRIBUTING.md covers the dev workflow and database changes.
- Web: React 19, Vite, React Router v7, Tailwind CSS 4, TanStack Query, React Hook Form + Zod, onnxruntime-web
- Server: Hono 4, Drizzle ORM, PostgreSQL with pgvector (Neon or self-hosted), onnxruntime-node (PaddleOCR text detection and recognition)
- Mobile: Expo, React Native, onnxruntime-react-native, BLE
- Auth:
AUTH_PROVIDER=neon(Neon Auth, JWT via JWKS) orlocal(own-auth, bearer sessions in your own Postgres) - Hardware: Arduino Uno R4 Minima / R4 WiFi or ESP32(-S3), PCA9685 servo driver, SG90 servos
- Monorepo: pnpm workspaces + Turborepo
For a production install, follow the step-by-step guide at mault.xyz/self-host. This section covers development.
Mault needs Postgres with pgvector and an identity provider, picked with AUTH_PROVIDER / VITE_AUTH_PROVIDER:
neon(default): a hosted Neon project. The free tier is enough.local: fully self-hosted.docker-compose.ymlruns Postgres, the API, the web app and the API docs. A Raspberry Pi can host the same local-auth app from a prebuilt SD image or release bundle (Raspberry Pi).
Both read one .env in the repo root:
cp .env.neon.example .env # Neon
cp .env.docker.example .env # local- Create a project at console.neon.tech and run
CREATE EXTENSION IF NOT EXISTS vector;. - Enable Neon Auth (Dashboard > Auth) before migrating: the RLS policies use its
authenticatedrole andauth.user_id(). - Set
DATABASE_URL(pooled),NEON_AUTH_URLandVITE_NEON_AUTH_URL(same URL) andVITE_NEON_DATA_API_URL. - Migrate and run:
pnpm install pnpm --filter @magic-vault/server db:migrate pnpm dev # web :5173, API :3001, API docs :5174
- In
.env, setPOSTGRES_PASSWORD,OWN_AUTH_TOKEN_PEPPER,IMPERSONATION_SECRET, andMONITOR_LINK_SECRET(openssl rand -hex 32each). docker compose up -d, then openhttp://localhost:8080and sign up. The first account becomes platform admin with a "Home" organization.- In
/app/admin, add a game in the Games Manager and sync it. Scans can't match until one has synced.
The server container runs every migration and packages/server/src/db/bootstrap-local.sql on start (pnpm db:migrate-local, idempotent). Postgres listens only on 127.0.0.1:5433. Email verification, profile/password editing, multi-session management and social sign-in are Neon-only.
Optional: API_URL (public API base for next_page links), SORTER_LINK_URL (see Wi-Fi remote), WEBHOOK_ALLOW_INSECURE_URLS=true (webhooks to http:// and LAN addresses; keep it off on public servers).
To make another user platform admin (no UI yet):
INSERT INTO platform_user_roles (user_id, role) VALUES ('<own_auth_users.id>', 'admin')
ON CONFLICT (user_id) DO UPDATE SET role = 'admin';A Raspberry Pi or Orange Pi Zero 4 can host the local-auth app and run the sorter headlessly. Nothing is cloned or built on the board: it runs a prebuilt release built by .github/workflows/pi-release.yml. Like the firmware and mobile releases, it is dispatched by hand: from master it publishes pi-v<app version> (bundle, SD image and installer) and points the pi-latest release's manifest.json and install.sh at it; from dev it publishes <version>-dev.<run> to the moving pi-dev pre-release, which dev installs update from. The bundle holds its own Node, the built API with its runtime dependencies, the Pi-mode web build and the Pi helpers. The scanner camera is a USB webcam plugged into the board, owned by mault-camera.service. Phone and computer browsers use the authenticated camera relay; they do not need browser permission to access that webcam.
Raspberry Pi 4 or 5: download mault-pi.img.xz from the newest pi-v* release and flash it with Raspberry Pi Imager (Imager offers no OS customisation for custom images). Before the first boot, open the card's bootfs drive on any computer and fill in mault-config.txt: a username and password (an administrator account), ssh=yes for ssh <username>@mault.local, and Wi-Fi details; Ethernet needs none of it. mault-boot-config.service applies it on every boot, erases the passwords from the file and writes the result on its Status line, so the same file also resets a forgotten password. On first boot, mault-setup.service writes secrets, creates the database and starts Mault. Then open http://mault.local (or the board's IP address) from any browser on the network.
Other arm64 boards, or an existing Raspberry Pi OS install:
curl -fsSL https://github.com/<owner>/<repo>/releases/download/pi-latest/install.sh | sudo bashinstall.sh installs Postgres with pgvector, nginx, ffmpeg, the webcam tools, BlueZ and Bleak, creates the mault-service account, unpacks the release into root-owned /opt/mault/releases/<version> (/opt/mault/current points at the running one), installs the mault command and the root helpers (see Security), and runs scripts/pi/setup.sh. Setup writes /var/lib/mault/.env with AUTH_PROVIDER=local, PI_HOST=1, a generated CARD_API_USER_AGENT and new secrets, creates the mault role and database, and enables the user services under mault-service with linger so they start at boot. Reruns keep the saved settings. sudo bash install.sh --bundle mault-pi-arm64.tar.gz installs a downloaded bundle offline.
The hardware choice is PI_SORTER=1 (the board drives the sorter through GPIO/I2C) or PI_SORTER=0 (an Arduino/ESP32 over USB or Bluetooth). The SD image picks it on first boot: PI_SORTER=1 when a PCA9685 answers on I2C bus 1 (the image enables I2C), else PI_SORTER=0. The curl installer asks, or reads PI_SORTER and PI_SORTER_BOARD from the environment (PI_SORTER=1 PI_SORTER_BOARD=orange-pi-zero4). Change it later with sudo mault sorter usb or sudo mault sorter builtin [raspberry-pi|orange-pi-zero4].
A board that still has a ~/mault checkout from the old git-based installer is migrated when the installer runs with sudo from that user: .env, calibration, pending scan saves and downloaded models are copied into /var/lib/mault, the database is reused, and the old user services are disabled. Delete the old checkout once Mault is running.
Orange Pi Zero 4 direct mode requires a supported Zero 4 system image and the libgpiod v2 Python API (python3-libgpiod); setup installs and checks that API. Enable the image's i2c0 boot overlay separately and reboot so the header TWI0 adapter is available. GPIO and I2C devices are discovered by their hardware paths.
In direct mode the Pi itself is the sorter. The API sends commands to the local controller process, which operates the PCA9685 and sensors through GPIO/I2C. Direct mode uses a single built-in sorter; additional USB, Bluetooth and Wi-Fi sorter stations are unavailable in this mode. The web app automatically attaches its built-in sorter controls through authenticated /pi-sorter access without an automatic mechanical test. Multiple browsers share the server's controller connection; commands and replies are coordinated centrally. A scan reserves hardware-changing commands, and competing motion or configuration commands return busy. Viewing the app from another device does not take control away. Calibration is stored in /var/lib/mault/.pi-controller/calibration.json; setup writes absolute PI_CONTROLLER_CONFIG and PI_CONTROLLER_SOCKET paths into .env. The Python controller uses the existing serial command protocol and updates with the app; it does not require firmware flashing. Native mobile connections remain BLE or Wi-Fi relay connections.
Linux and Pi installations with external sorters use PI_HOST=1 with PI_SORTER=0; USB and host Bluetooth connections do not require GPIO control. Use the sorter menu to connect an attached USB sorter as another station, then choose its camera from the camera menu. Each station keeps its own device calibration, collection and camera preference, just as it does with browser-connected hardware. USB sorters can stay connected while you switch station tabs. Identical cameras are distinguished by their Linux device IDs; stable USB by-id paths are used when available. The helper keeps each camera's stream, frame buffer and focus settings separate.
Headless scanning runs one session per organization. Stop that session before switching its hardware pair; starting the next scan passes the station's selected controller and camera to the API, which continues using that pair if the browser closes. A missing selected device produces an error instead of selecting another sorter or camera. Native mobile sorter connections remain BLE and Wi-Fi; Pi hardware selection is available in desktop and mobile browsers.
| Service | Role |
|---|---|
nginx (system) |
Serves the web app on ports 80 and 8080 and proxies /api to the API, including /api/pi-camera |
mault-api |
API on 127.0.0.1:3001; runs migrations on start |
mault-camera |
scripts/pi/camera-ctl.py on 127.0.0.1:8765. This process owns the USB webcam |
mault-controller |
Direct mode only: local Python GPIO/I2C controller, started and stopped with the API |
mault-prices |
Daily price sync at 04:00 (timer) |
The mault-* units are systemd user services of mault-service. The API binds only to localhost; HTTP and WebSocket requests reach it through nginx. Other deployments keep the existing API bind address unless API_HOST is configured. The web app in the bundle runs in Pi mode (VITE_PI_HOST=true in its env.js): / goes straight to sign-in and the marketing and legal pages are left out.
Everything on the board goes through the mault command:
sudo mault status # version and service state
sudo mault version # installed version only
sudo mault update # install the latest release
sudo mault update --bundle mault-pi-arm64.tar.gz # install a downloaded bundle
sudo mault os-updates # turn on automatic OS security updates
sudo mault sorter usb | builtin [raspberry-pi|orange-pi-zero4]
sudo mault logs [api|camera|controller|update|setup]
sudo mault start | stop | restart
sudo mault prices # pull prices now
sudo mault urls # addresses to openAdmins can also update from the app's update banner (Update Mault), which asks the root updater (mault-update.path and mault-update.service) to run /usr/local/lib/mault/run-update.sh. The app can only request an update, never choose what gets installed: the updater downloads the bundle named in the manifest its release.json points at (pi-latest or pi-dev), checks its SHA-256, unpacks it next to the running release, stops the services, switches /opt/mault/current, re-renders the units and starts them. If the new version does not answer, it switches back to the previous release. Boards install whatever version the manifest names, so dispatching Pi Release from master with rollback_tag: pi-vX.Y.Z moves every board back to that release. It keeps the running and previous releases. Finish scanning, disconnect the sorter and stop any database sync first; the API refuses browser updates otherwise. Settings, accounts and saved cards stay in place, and database migrations run when the API starts.
The operating system patches itself: the installer turns on unattended-upgrades for Debian security fixes and the Raspberry Pi archive (kernel, firmware), installed daily without rebooting, so a scan is never cut off. When an update needs a restart (Debian's /run/reboot-required, or a kernel installed since boot), admins see a banner in the app asking them to run sudo reboot when no scan is running; Mault starts again on its own. Mault updates only cover Mault and the Node runtime it bundles (each Pi release ships the newest Node of its major version). Boards installed before this was added turn it on with sudo mault os-updates or their next sudo mault update.
Security. The API faces the network as mault-service, so nothing root runs is within that account's reach:
| Path | Holds |
|---|---|
/opt/mault |
Releases and the current link, root-owned and read-only to the service |
/usr/local/sbin/mault |
The mault command (a root-owned copy, not a link into a release) |
/usr/local/lib/mault |
Root helpers that never run from a release: boot settings, OS updates, the root updater and the release check |
/var/lib/mault-system |
Root state (setup marker, update state and log); requests/ is the app's update drop box |
/var/lib/mault |
The service account's own data (.env, calibration, logs); root never reads or writes it directly |
Before root runs anything from a release, trusted-tree.py checks that every directory leading to it, the current link and every file under scripts/pi are root-owned and not writable by anyone else, and refuses otherwise. Root scripts pin PATH and run Python with -I, so nothing is picked up from the working directory or the environment. Anything that reads the service's files, renders its units or runs Node runs as mault-service.
Upgrading boards on Pi release 1.0.209 or older. Those releases were writable by mault-service, so they can't be trusted to switch themselves over. Run the newest installer once over SSH instead of sudo mault update:
curl -fsSL https://github.com/maultxyz/mault/releases/download/pi-latest/install.sh | sudo bashIt deletes the old releases and the old /usr/local/bin/mault link without running or adopting them, then installs a fresh release; settings, accounts, saved cards and calibration in /var/lib/mault stay. Until then, sudo mault update and the app's update button refuse and point to this command.
The API log is at /var/lib/mault/.local/state/mault/api.log (sudo mault logs), including scan failures and feed commands.
Open http://mault.local (or port 8080) from another computer to scan. That browser is not on localhost, so while PI_HOST is on it uses the Pi's webcam stream and the sorter plugged into the Pi. The scan loop runs in the API: feed, wait the capture settle delay once, take the photo, match, and route. The camera helper owns the webcam, and the API owns the sorter during a scan. Camera preview and focus control require signing in to an organization.
The API reports a Pi host when PI_HOST=1, and also when /proc/device-tree/model contains Raspberry Pi and PI_HOST is unset. PI_HOST=0 turns the remote-browser behavior off. WEBCAM_DEVICE selects a specific /dev/video* node when the helper should not pick one itself.
Sign up on the Pi's page. The first account is the platform admin. Add a game in Admin and sync it before scanning. On a Pi host, Start on this computer uses the remote computer's browser to vectorize missing card images for the bulk database sync. Keep that admin page open while it works; the cards-at-a-time control sets its concurrency. Live scans still identify cards on the Pi.
If a bin fills or all repack packs are complete, scanning pauses with the current card retained. Empty the relevant bins in the app, then resume. The API reloads rules, capacities, and bin contents before routing that card. Presets with skip saving use the existing sort-only path. Stopping a scan may leave a card in the sorter; remove it before starting another session.
On Linux/Pi hosts with PI_SORTER=0, the connection menu offers Bluetooth when BlueZ and the system Python Bleak package are installed and an adapter is present. A powered-off adapter shows a disabled status; enable it with the host's Bluetooth settings. Open Connect Bluetooth to search for nearby sorters advertising the Nordic UART BLE service, then select the sorter. Discovery is on demand, never continuous. The API owns the Bluetooth connection, so this works from remote browsers (including Firefox) and headless scans. USB and Bluetooth connections use the same per-device ownership checks; a missing or disconnected Bluetooth sorter never falls back to another device. Keep the ESP32 nearby and advertising, and disconnect other clients before connecting. Available simultaneous connections depend on the adapter. GPIO mode remains a single built-in sorter and does not expose Bluetooth.
The installer always installs bluez and python3-bleak and enables the Bluetooth service; the helper uses /usr/bin/python3. The default BlueZ adapter must support BLE. Ordinary non-host browser Bluetooth still uses Web Bluetooth and the browser computer's adapter, with its browser/platform requirements; native mobile BLE remains unchanged.
To build a bundle yourself, run scripts/pi/build-bundle.sh --version <x.y.z> --manifest-url <url> --out <dir> on linux-arm64 with the Dockerfiles' Node and pnpm.
pnpm --filter @magic-vault/server dev
pnpm --filter @magic-vault/web dev
pnpm dev:bot # Discord bot (excluded from pnpm dev)
pnpm --filter @magic-vault/mobile start # Expo dev server, see packages/mobile/README.md
pnpm build # server (tsup) + web (tsc -b, vite build)
pnpm --filter @magic-vault/web lintThere are no automated tests; the web build's tsc -b is the type check.
pnpm --filter @magic-vault/server db:generate # migration from schema.ts changes
pnpm --filter @magic-vault/server db:migrate # apply migrations
pnpm --filter @magic-vault/server db:push # local iteration only
pnpm --filter @magic-vault/server db:studioThese target whatever DATABASE_URL points at. Read CONTRIBUTING.md before shipping a migration; Drizzle orders migrations by journal timestamp, so check them after merging branches.
node packages/server/dist/scripts/sync-prices.js pulls TCGplayer prices and SKU ids for the TCGplayer CSV export (via TCGTracking), Cardmarket and Card Kingdom, downloading only what changed. Nothing runs it automatically.
- Once a day is enough. TCGplayer prices only re-download sets TCGTracking reports as changed, and the Card Kingdom step skips any run within 20 hours of its last pull.
- No automatic retries. A failed run waits for the next daily run.
- First run: after your first game sync, run it once by hand. Cards have no price until then.
--forcere-downloads everything; use it sparingly. - Only some games:
--games=mtg(comma-separated game keys) limits every source and the price refresh to those games; Card Kingdom only runs when a listed game uses it. - Set
CARD_API_USER_AGENTto a name unique to your install: a source that blocks a name blocks every install using it.
Docker Compose, with crontab -e (replace /opt/mault with your docker-compose.yml folder):
0 4 * * * cd /opt/mault && docker compose exec -T server sh -c 'if [ "$AUTH_PROVIDER" = local ]; then export DATABASE_URL="${DATABASE_URL:-postgresql://mault:$POSTGRES_PASSWORD@postgres:5432/mault}" DATABASE_SSL="${DATABASE_SSL:-false}"; fi; exec node packages/server/dist/scripts/sync-prices.js' >> /var/log/mault-prices.log 2>&1Coolify: see step 5 under Coolify. Outside Docker: pnpm --filter @magic-vault/server build, then schedule the command from the repo root with the .env values in its environment.
pnpm --filter @magic-vault/server sync:catalogs runs the card sync (the same worker the admin page starts) in its own process against DATABASE_URL, one game and language after another, so the server does none of the work. --games=mtg,pokemon and --languages=en limit it, --force force-resyncs. A running server picks the new cards up within a minute.
.github/workflows/card-catalog-sync.yml runs it nightly on a GitHub runner. It needs the DATABASE_URL secret in the production environment and, optionally, a CARD_API_USER_AGENT variable. Run it by hand to limit it to some games or languages.
Five images, built from the repo root and published by CI (.github/workflows/deploy.yml) to ghcr.io/maultxyz/mault-*, tagged vX.Y.Z, sha-* and :latest (from master) or :dev:
| Dockerfile | Image | Notes |
|---|---|---|
Dockerfile.server |
mault-server |
Hono API; also contains the sync-prices script |
Dockerfile.web |
mault-web |
Vite SPA on nginx, proxies /api to the server |
Dockerfile.api-docs |
mault-api-docs |
Public API reference |
Dockerfile.bot |
mault-bot |
Optional Discord bot |
Dockerfile.shortener |
mault-shortener |
Optional link shortener |
The images are public, so the web image reads its VITE_* settings at container start (docker/web-env.sh writes env.js). The server reports the bundled firmware's version from FIRMWARE_VERSION in firmware/main/main.ino, which the server image copies.
The scanner downloads its ONNX weights from huggingface.co at runtime (pinned by revision and SHA-256). Allowlist it in DNS blockers such as Pi-hole.
docker compose up --build -d # postgres, server, web (:8080), api-docs (:8081)
docker compose --profile shortener up --build -d # + link shortener (:8082)
docker compose --profile bot up --build -d # + Discord bot (internal :3002)- For production, set
WEB_URLto your public origin and use real secrets. - With
AUTH_PROVIDER=neon,.envmust point at a migrated Neon project; the bundledpostgresthen sits unused. - Prices need the cron job from Prices.
- Leaderboards: an owner or admin can link an organization to the hosted Mault leaderboards under Settings > Integrations with a stats sync key from mault.xyz. Only daily scan totals are sent, first every past day, then once a day.
STATS_SYNC_TARGET_URL(defaulthttps://mault.xyz/api) changes where they go.
Short links are optional. Without them, share links and shop catalogs are shared as their full tokenized URLs. To share https://<short domain>/<code> instead, run the standalone shortener (packages/shortener, image mault-shortener) on its own domain:
- Route the short domain to the shortener on port 3003 and set its
SHORT_LINK_TARGET_ORIGINto the web origin. It keeps its table in the database'sshortenerschema, created on start. - On the API, set
SHORT_LINK_BASE_URL(the short domain),SHORTENER_URL(how the API reaches the shortener internally) andSHORTENER_API_SECRET(also given to the shortener).
The API then registers each link's code with the shortener and re-registers every live link when it starts, so links created while short links were off also get short URLs. Unknown codes redirect to the web app's /link-not-found. Platform admins can also create custom links on the short domain (for example /discord to an invite) under Admin > Short links. Mobile builds need MOBILE_SHORT_LINK_URL set to the same domain to read those QR codes.
docker-compose-coolify.yml runs the published images (web, API, pgvector Postgres, optional bot and link shortener), so nothing builds on your server. MAULT_IMAGE_TAG picks the tag (default latest; set e.g. v1.2.3 to pin).
- + New > Public Repository with
https://github.com/maultxyz/mault, branchmaster, build pack Docker Compose and compose file/docker-compose-coolify.yml. - Set
WEB_URL(public origin, no trailing slash) and givePOSTGRES_PASSWORD,IMPERSONATION_SECRET,OWN_AUTH_TOKEN_PEPPER, andMONITOR_LINK_SECRETeach its ownopenssl rand -hex 32value. Everything else is optional (see.env.docker.example). - Route your domain to the web service on port 80 (e.g.
https://mault.example.com:80). - Deploy. The API migrates before starting. To update, redeploy: Coolify fetches the latest compose file and pulls the current images.
- Under Scheduled Tasks, add the price sync: command
node packages/server/dist/scripts/sync-prices.js, containerserver, frequency0 4 * * *.
- Neon: also set
AUTH_PROVIDER/VITE_AUTH_PROVIDERtoneon,DATABASE_SSL=trueand the Neon values, and run the migrations from a checkout before each deploy. - Short links: route a short domain to the shortener service on port 3003 and set
SHORT_LINK_BASE_URL,SHORT_LINK_TARGET_ORIGINandSHORTENER_API_SECRET(see Link shortener); without them the shortener idles. - Discord: set
DISCORD_BOT_TOKEN,DISCORD_CLIENT_IDandBOT_API_SECRETand redeploy; without them the bot idles. - Data: Postgres lives in the
mault-postgresvolume; keep it and back it up. The defaultDATABASE_URLusesPOSTGRES_PASSWORDunencoded, so keep it URL-safe (hex is). ChangingPOSTGRES_PASSWORDlater doesn't change the database's password, and changingOWN_AUTH_TOKEN_PEPPERsigns everyone out.
Error tracking and uptime monitoring are optional and use Better Stack.
- Errors: set
BETTER_STACK_ERRORS_DSN(API) andVITE_BETTER_STACK_ERRORS_DSN(web) to the Sentry-compatible DSN of a Better Stack Errors application. Only exceptions are sent. - Uptime: create an Uptime API token, then run
pnpm uptime:syncwith the public URLs of the deployment (it refuseslocalhost). It creates or updates, by name, HTTP monitors for the web app, the API's/api/public/version, and the link shortener and API docs whenSHORT_LINK_BASE_URLandVITE_API_DOCS_URLare set. It also creates heartbeats for services Better Stack can't reach from outside and prints each heartbeat URL:- Discord bot: set
BETTER_STACK_BOT_HEARTBEAT_URLon the bot; it pings every minute while connected to Discord. - Price sync and card catalog sync (production only): set
BETTER_STACK_PRICE_SYNC_HEARTBEAT_URLandBETTER_STACK_CATALOG_SYNC_HEARTBEAT_URLas secrets in the GitHubproductionenvironment. Scheduled runs ping on success and report/failon failure.
- Discord bot: set
BETTER_STACK_UPTIME_API_TOKEN=... WEB_URL=https://mault.example.com \
SHORT_LINK_BASE_URL=https://mlt.example VITE_API_DOCS_URL=https://docs.mault.example.com \
pnpm uptime:sync # add -- --environment=dev for a dev deploymentRerun it whenever a URL changes. Values in your shell take precedence over .env. No monitor or heartbeat touches the database, so none of them keeps Neon awake: the API monitor checks only that the process answers, and database failures surface through error tracking when real requests hit them.
The bot only talks to the server over HTTP (SERVER_URL), and the server calls back into the bot's small HTTP server (BOT_URL/BOT_PORT) to post scan notifications, alerts and rule matches into the channels chosen in Settings > Integrations. Both directions share BOT_API_SECRET. Commands are registered globally; set DISCORD_DEV_GUILD_ID for faster iteration in development. To give people who link their account with /link-account a role in your own server, pick the server and role under Admin > Discord channels (the bot needs Manage Roles and a role above it). Linking and unlinking add and remove the role right away. Someone who links before joining that server gets the role by running /link-account again once they're in it. To DM new members of your own server instructions for /link-account, set DISCORD_WELCOME_GUILD_IDS to its server ID (comma-separate several) and enable the Server Members intent under Bot > Privileged Gateway Intents in the Discord Developer Portal; without the intent the bot can't log in.
Full BOM, wiring and assembly steps are at /build. In short:
- Controller: Arduino Uno R4 Minima (USB), Uno R4 WiFi (USB + Bluetooth) or ESP32 / ESP32-S3 (USB, Bluetooth and Wi-Fi), driving a PCA9685 over I2C
- Modules: 3 positional SG90 servos each (trapdoor, paddle gate, pusher); add modules any time without reflashing, the count is set in Calibration
- Feeder: one continuous-rotation servo plus an IR sensor for feed detection
- Enclosure:
3d model/(Fusion 360 / STEP source and printable.3mf)
The sketch is firmware/main/ (main.ino plus the BLE, Wi-Fi and LED tabs). The easiest path is flashing from the app, which uses the builds published by .github/workflows/firmware-release.yml. To build it yourself, install ArduinoJson, Adafruit PWM Servo Driver, Adafruit NeoPixel and (Uno R4 WiFi) ArduinoBLE, and use the FQBNs from that workflow; ESP32-S3 builds need USBMode=hwcdc,CDCOnBoot=cdc,FlashMode=dio,PartitionScheme=min_spiffs.
The firmware has no idea what a bin is: the app resolves each bin to a module and direction (left, right or bottom) and sends newline-delimited JSON at 9600 baud, such as {"seq":42,"route":{"module":2,"direction":"left"}}. Note that "left" lands on the physical right. firmware/PROTOCOL.md documents every command and the USB, BLE and Wi-Fi transports. The PCA9685 channel layout (Standard from channel 0, or Legacy from channel 4 for older wiring) is chosen in Calibration and sent at connect time.
See Raspberry Pi. The sorter stays plugged into the Pi, and a USB webcam on the Pi is the scanner camera.
ESP32 boards on firmware 2.10.0+ can be driven without a cable. Wi-Fi is configured over USB or Bluetooth, then the board holds a WebSocket to /sorter-link/device and the server relays it to one browser. The board dials SORTER_LINK_URL, else API_URL, else the web origin. In local development set it to a LAN address the board can reach, e.g. ws://192.168.1.20:3001/sorter-link/device. The relay is in process, so the board and its browser must reach the same server instance.
A Logitech C920 works well with: auto focus off, focus 50%, auto exposure on, low light compensation on, auto white balance on, brightness 140, contrast 140, saturation 160, sharpness 130.
| Component | License |
|---|---|
| Software source code | GPL-3.0 |
3D models (3d model/) |
CC BY-NC-SA 4.0 |
See the LICENSE file in each directory for the full terms.