Spoolman

Spoolman is a self‑hosted, full‑stack web service that transforms raw filament spools into structured inventory data. From a developer standpoint, it operates as a REST‑first API backed by a relational database, exposing real‑time updates via WebSockets and optional Prometheus metrics. The core use case is to capture the weight change of a filament spool during a print job, automatically compute usage, and persist this information for reporting or downstream automation. The system is intentionally lightweight: a single Go binary serves HTTP, WebSocket, and gRPC endpoints, while the database layer abstracts over SQLite, PostgreSQL, MySQL, or CockroachDB.

Architecture

Spoolman is written in Go (Golang), leveraging the net/http standard library for routing and middleware. The API layer is built on top of gin‑framework (or a minimal custom router), which provides JSON request/response handling, validation, and graceful shutdown. Persistence uses GORM as the ORM, allowing developers to swap databases with minimal code changes. WebSocket support is implemented via gorilla/websocket, enabling push notifications to the web client whenever a spool’s weight changes. For monitoring, Spoolman exposes metrics in Prometheus format, which can be scraped by an external Prometheus server. The front‑end is a single‑page application written in React (or similar), consuming the API and WebSocket streams; it is bundled with Vite for fast builds.

Core Capabilities

• REST API: CRUD operations on filaments, spools, manufacturers, and custom fields. The API is fully documented (OpenAPI) and supports pagination, filtering, and bulk uploads.
• WebSocket Feed: Clients can subscribe to spool/updates events, receiving JSON payloads whenever a spool’s weight is altered by an external printer integration.
• Printer Integrations: Plug‑ins for OctoPrint, Moonraker (and its front‑ends), and OctoEverywhere send HTTP POSTs to Spoolman’s /api/spools/:id/update endpoint with weight deltas.
• Label Generation: The API can return QR‑coded labels for spools, which are printable via the web UI or programmatically fetched.
• Custom Fields: Developers can extend the data model with arbitrary key/value pairs per spool, enabling domain‑specific metadata.
• Prometheus Exporter: Exposes metrics such as spool_usage_total, printer_active_jobs, and historical usage histograms.

Deployment & Infrastructure

Spoolman ships as a single statically‑compiled binary, making it trivial to deploy on any Linux server, Docker host, or even ARM devices like Raspberry Pi. A Docker image is available on Docker Hub, with environment variables for database DSN, port, and optional TLS termination. The application is stateless beyond the database, so horizontal scaling is straightforward: run multiple instances behind a load balancer, and let them share the same database. For high‑availability, CockroachDB or PostgreSQL with replication can be used; SQLite is suitable for local development or hobbyist setups.

Integration & Extensibility

The plugin ecosystem is driven by HTTP endpoints: any printer or workflow tool can push spool updates via a simple POST request. Developers may also hook into WebSocket events to trigger custom logic (e.g., send an email when a spool is low). The API’s OpenAPI spec allows automatic client generation in languages such as Python, TypeScript, or Rust. For deeper integration, Spoolman exposes a gRPC interface (experimental) that can be used for low‑latency bulk updates. Custom field schemas are stored in the database, so you can add new attributes without modifying the core codebase.

Developer Experience

Spoolman’s documentation lives in a dedicated GitHub Wiki, with clear sections for API reference, integration guides, and deployment. The codebase follows Go conventions (go.mod, linting) and is fully unit‑tested with coverage reports. Community support is active: issues are triaged promptly, and pull requests for new integrations (e.g., Home Assistant) are merged quickly. The project is licensed under MIT, allowing unrestricted use in commercial or private environments.

Use Cases

• Print Farm Management: A developer can spin up Spoolman on a central server and connect dozens of OctoPrint or Moonraker instances, automatically aggregating filament usage across the farm.
• Custom Workflow Automation: Using WebSockets and the API, a CI/CD pipeline could trigger re‑ordering of filament when a spool falls below a threshold.
• Analytics Dashboard: Export Prometheus metrics to Grafana, creating visual reports on filament consumption per printer or material type.
• Hardware Integration: Embed Spoolman in a home‑automation stack (Home Assistant) to display real‑time spool status on dashboards or trigger notifications.

Advantages

• Performance: Go’s compiled binaries and efficient goroutine model provide low latency updates, even with many concurrent printers.
• Flexibility: The abstraction over multiple databases and the ability to add custom fields make it adaptable to varied workflows.
• Licensing: MIT license removes any barriers for commercial deployment, unlike some proprietary filament managers.
• Community‑driven: Regular contributions from the 3D printing community mean new printer integrations and database entries are added rapidly.
• Ease of Deployment: A single binary or Docker