Deploying Spoolman

Introduction

Spoolman is a self-hosted filament management system designed for 3D printing enthusiasts. It helps you keep track of your filament spools, monitor usage across prints, and never run out of material mid-print again. With integrations for popular slicers and firmware, Spoolman becomes the central hub for your 3D printing workflow.

Built with Python and FastAPI, Spoolman offers a modern web interface alongside a powerful REST API that enables seamless integration with tools like Klipper, Moonraker, OctoPrint, and various slicers.

Key highlights of Spoolman:

• Spool Tracking: Track filament inventory with detailed information per spool
• Usage Monitoring: Automatically track filament consumption across prints
• Multi-Printer Support: Manage filament across multiple printers
• Klipper Integration: Native integration with Moonraker/Klipper
• OctoPrint Plugin: Plugin available for OctoPrint users
• Slicer Integration: Works with PrusaSlicer, Cura, and others
• QR Codes: Generate QR codes for quick spool identification
• Material Database: Store filament types, colors, and properties
• Vendor Management: Track purchases from different suppliers
• REST API: Full API for custom integrations
• Barcode Scanning: Scan spools for quick selection
• Open Source: MIT licensed and actively developed

This guide walks through deploying Spoolman on Klutch.sh using Docker for reliable filament inventory management.

Why Deploy Spoolman on Klutch.sh

Deploying Spoolman on Klutch.sh provides several advantages:

Simplified Deployment: Klutch.sh handles the container build and deployment automatically.

Persistent Storage: Your spool inventory and usage history persist across deployments.

HTTPS by Default: Secure access to your filament database from anywhere.

GitHub Integration: Version control your configuration and deploy updates automatically.

Multi-Location Access: Access your filament inventory from any device or printer.

Custom Domains: Use a memorable URL for your Spoolman instance.

Always Available: 24/7 access for automated spool tracking from your printers.

Network-Wide Access: All printers on your network can connect to one Spoolman instance.

Prerequisites

Before deploying Spoolman on Klutch.sh, ensure you have:

• A Klutch.sh account
• A GitHub account with a repository for your configuration
• Basic familiarity with Docker
• 3D printer(s) for integration (optional but recommended)
• (Optional) A custom domain for your Spoolman instance

Deploying Spoolman on Klutch.sh

Create a GitHub Repository

Create a new GitHub repository for your Spoolman deployment.

Create Your Dockerfile

Create a Dockerfile in your repository:

FROM ghcr.io/donkie/spoolman:latest

# Set environment variables
ENV SPOOLMAN_DB_TYPE=sqlite
ENV SPOOLMAN_LOGGING_LEVEL=INFO

# Create data directory
RUN mkdir -p /home/app/.local/share/spoolman

EXPOSE 8000

HEALTHCHECK --interval=30s --timeout=10s --start-period=30s --retries=3 \
  CMD curl -f http://localhost:8000/api/health || exit 1

Push Your Repository to GitHub

Commit and push your Dockerfile.

Create a New Project on Klutch.sh

Navigate to the Klutch.sh dashboard and create a new project named “spoolman” or similar.

Create a New App

Within your project, create a new app and connect your GitHub repository.

Configure HTTP Traffic

In the deployment settings:

• Select HTTP as the traffic type
• Set the internal port to 8000

Set Environment Variables

Configure the following environment variables:

Variable	Value
SPOOLMAN_DB_TYPE	sqlite (or postgres for PostgreSQL)
TZ	Your timezone (e.g., America/New_York)

Attach Persistent Volumes

Add the following volumes:

Mount Path	Recommended Size	Purpose
/home/app/.local/share/spoolman	5 GB	Database and application data

Deploy Your Application

Click Deploy to build and start Spoolman.

Access Spoolman

Once deployment completes, access your Spoolman at https://your-app-name.klutch.sh.

Initial Configuration

Setting Up Vendors

Before adding spools, set up your filament vendors:

1. Navigate to Vendors in the menu
2. Click Add Vendor
3. Enter vendor name (e.g., “Hatchbox”, “eSUN”, “Prusament”)
4. Add vendor details and website
5. Save the vendor

Adding Filament Types

Configure your filament materials:

1. Go to Filaments section
2. Click Add Filament
3. Select vendor, material type (PLA, PETG, ABS, etc.)
4. Set color and other properties
5. Save the filament

Adding Spools

Track individual spools:

1. Navigate to Spools
2. Click Add Spool
3. Select the filament type
4. Enter spool weight and initial filament weight
5. Set purchase date and price (optional)
6. Save the spool

Printer Integration

Moonraker (Klipper) Integration

Add to your moonraker.conf:

[spoolman]
server: https://your-spoolman-url.klutch.sh
sync_rate: 5

OctoPrint Integration

1. Install the Spoolman OctoPrint plugin
2. Configure the plugin with your Spoolman URL
3. Select active spool before printing

Slicer Integration

PrusaSlicer/OrcaSlicer

1. Configure custom G-code for spool tracking
2. Add spool selection macros
3. Spoolman will track usage automatically

Features

Spool QR Codes

Generate QR codes for easy identification:

1. Navigate to a spool’s detail page
2. Click Generate QR Code
3. Print and attach to the physical spool
4. Scan to quickly access spool info

Usage Tracking

Monitor filament consumption:

Data Tracked	Description
Used Weight	Total filament consumed from spool
Remaining	Estimated filament left
Print History	List of prints using this spool
Cost Per Print	Calculate material costs

Alerts

Set up low filament alerts:

1. Configure minimum weight thresholds
2. Receive notifications when spools run low
3. Plan purchases before running out

API Usage

REST API Examples

Get all spools:

GET /api/v1/spool

Update spool usage:

POST /api/v1/spool/{spool_id}/use
{
  "use_length": 1500,
  "use_weight": 4.5
}

Integration Ideas

• Custom dashboards with usage statistics
• Automated reorder notifications
• Print cost tracking systems
• Multi-location inventory sync

Data Management

Backup

Regularly back up your Spoolman data:

1. The SQLite database is stored in the mounted volume
2. Export data via the API for additional backup
3. Back up vendor and filament configurations

Import/Export

Spoolman supports data import/export:

• Export spool inventory to CSV
• Import spools from spreadsheets
• Migrate between instances

Troubleshooting

Printer Cannot Connect

• Verify Spoolman URL is accessible from printer
• Check firewall settings
• Ensure HTTPS is working correctly

Usage Not Tracking

• Verify printer integration is configured
• Check that the correct spool is selected
• Review printer communication logs

Database Issues

• Ensure persistent volume is mounted correctly
• Check file permissions
• Verify database integrity

Additional Resources

• Spoolman GitHub Repository
• Spoolman Wiki
• Klipper Documentation
• Moonraker Documentation
• Klutch.sh Persistent Volumes
• Klutch.sh Deployments

Conclusion

Deploying Spoolman on Klutch.sh gives you a centralized filament management system accessible from all your printers and devices. Track usage, manage inventory, and never run out of filament mid-print again. With integrations for Klipper, OctoPrint, and various slicers, Spoolman becomes an essential part of your 3D printing workflow.