sytxlabs/spoolbeacon repository overview

⁠Screenshots

Dashboard	Inventory

Filament Detail	Spools

Print Board	New Print Job

3D Preview

Shop Rules	Manufacturers

API Keys

⁠📦 Features

⁠🔧 Requirements

• Docker + Docker Compose

For local development: Python 3.12+

⁠🚀 Quick Start

⁠Option A — Docker Hub (recommended, no clone needed)

Create a compose.yaml:

services:
  web:
    image: sytxlabs/spoolbeacon:latest
    ports:
      - "${APP_PORT:-8080}:${APP_PORT:-8080}"
    env_file: .env
    restart: unless-stopped
    depends_on:
      db:
        condition: service_healthy

  db:
    image: mariadb:11
    restart: unless-stopped
    environment:
      MARIADB_ROOT_PASSWORD: ${DB_PASSWORD}
      MARIADB_DATABASE: ${DB_NAME}
      MARIADB_USER: ${DB_USER}
      MARIADB_PASSWORD: ${DB_PASSWORD}
    volumes:
      - db_data:/var/lib/mysql
    healthcheck:
      test: ["CMD", "healthcheck.sh", "--connect", "--innodb_initialized"]
      interval: 10s
      timeout: 5s
      retries: 5

volumes:
  db_data:

Create a .env next to it:

SECRET_KEY=       # generate: python -c "import secrets; print(secrets.token_hex(32))"
APP_PORT=8080
DB_HOST=db
DB_PORT=3306
DB_USER=spoolbeacon
DB_PASSWORD=changeme
DB_NAME=spoolbeacon
QUART_AUTH_COOKIE_SECURE=true

Pull and start:

docker compose up -d

⁠Option B — From source (GitHub)

git clone https://github.com/Sytxlabs/SpoolBeacon.git
cd SpoolBeacon
cp .env.example .env   # edit SECRET_KEY and DB_PASSWORD
docker compose up --build -d

MariaDB starts automatically, migrations run on container start. The app is exposed on APP_PORT (default 8080) — only that port is mapped to the host, MariaDB stays internal to the compose network.

⁠First admin account

Open http://your-host:8080/setup — only available when no users exist yet.

⁠⬆️ Updating

Docker Hub install:

docker compose pull
docker compose up -d

From source:

git pull
docker compose up --build -d

Migrations run automatically on restart.

⁠🛠️ Local Development

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
playwright install --with-deps chromium
cp .env.example .env   # fill in DB credentials
python migration.py upgrade head
python main.py         # runs on http://localhost:8080

Seed sample data:

python seed.py           # manufacturers, products, purchases, links, rules (idempotent)
python seed.py --reset   # wipe all tables (except users/settings) and re-seed
python seed_shops.py     # ShopRules only, no inventory data

⁠⚙️ Configuration

All runtime settings are managed on the Settings page (/settings, admin only) — not via .env.

⁠📈 Price Monitoring

⁠Built-in Adapters

These shops work out of the box without any manual configuration:

To add a new adapter: subclass BaseAdapter in app/shop_adapters/, implement extract(html, url) -> AdapterResult, register in registry.py via _reg(YourAdapter()).

⁠ShopRules (generic)

For any other shop: create a rule at /shop-rules with domain, CSS price selector, and optional regex — or use the visual point-and-click picker to build one without touching CSS.

⁠🖨️ Print Board

Navigate to Prints in the nav bar (or /prints/) for a Kanban-style board of your print jobs, grouped into Planned → Printing → Done columns.

Hit + New Print Job to plan a new job:

1. Enter an optional print name and notes.
2. Add one or more filament lines — select a spool from the grouped dropdown, enter planned grams. The live preview shows how much is left on that spool.
3. Optionally attach print files: a link to Printables/MakerWorld/Thingiverse/etc., or upload an STL/3MF directly — uploaded files get an in-browser 3D preview (three.js, no external service).
4. Hit Add to Board — the job lands in Planned with a generated job code (e.g. PJ-20260803-002, template configurable under Settings).

Move a card forward with Start / Mark Done, or back with the reopen button. Filament is only deducted from the spool once a job is marked Done — moving it back out of Done restores the weight. Planned/printing jobs can be edited (name, notes, filament lines, files) via the pencil icon; completed jobs are read-only history (reopen first to edit).

Supports multi-filament prints (e.g. dual-extrusion or colour changes mid-print) by adding multiple lines.

⁠🔌 REST API

SpoolBeacon exposes a versioned JSON API at /api/v1/. Interactive documentation (Swagger UI) is available at /api/docs — no login required, just a bearer token.

⁠Authentication

API keys are managed at /api-keys (admin only). Each key is shown once at creation time and stored as a SHA-256 hash.

Authorization: Bearer <your-token>

⁠Endpoints

⁠POST /api/v1/prints body

{
  "print_name": "Benchy",
  "notes": "Optional",
  "lines": [
    {
      "spool_id": 3,
      "used_g": 12.5
    },
    {
      "spool_id": 7,
      "used_g": 4.0
    }
  ]
}

The job is created with status planned. Spool weight is only deducted once the job is moved to done via PATCH /api/v1/prints/{id}/status ({"status": "done"}), and spool status auto-updates (new → opened → almost empty → empty). Moving a job back out of done restores the deducted weight.

⁠Quick example

TOKEN=your-token-here

# List active spools
curl -H "Authorization: Bearer $TOKEN" http://your-host:8080/api/v1/spools?status=opened

# Log a print job
curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"print_name":"Benchy","lines":[{"spool_id":1,"used_g":6.2}]}' \
  http://your-host:8080/api/v1/prints

Full schema and "Try it out" in Swagger UI: http://your-host:8080/api/docs

⁠⚠️ Known Limitations

• Amazon / eBay not supported — Amazon requires an authenticated session or the Product Advertising API; eBay blocks scraping via Cloudflare
• Heavy WAFs (Cloudflare Enterprise) block even cloudscraper — a proxy or official API is needed
• No printer / slicer integration — no Klipper, OrcaSlicer or automatic print job import; print jobs can be submitted via the REST API
• No mobile app — web only, mobile-optimised responsive layout

⁠🩺 Troubleshooting

⁠🐳 Docker Image

Pre-built images are published to Docker Hub⁠ on every push to master and on version tags:

docker pull sytxlabs/spoolbeacon:latest

⁠📄 License

MIT⁠ — see the LICENSE file for details.