FilaMan - Filament Management System

Support the FilaMan Project

ko-fi

♻️ Support Recycling Fabrik

Empty spools don't belong in the trash! We support the Recycling Fabrik. Send your empty filament spools and 3D printing waste there to have it recycled into new filament.

Exciting News: Recycling Fabrik is the first manufacturer that will soon start shipping their filament spools with pre-programmed, FilaMan-compatible RFID tags!

Looking for the German version? Read the README.de.md.

About the Project

FilaMan is a comprehensive filament management system for 3D printing. It helps you keep track of your filament spools, manufacturers, colors, and current stock levels. It also features integrations with printers and AMS (Automatic Material System) units.

Documentation

The full user manual is available at docu.filaman.app. See the label rendering and print-request API for device and client integration.

💡 Hardware Extension: FilaMan ESP32 Scale

To unlock the full potential of this system, we highly recommend our companion hardware project: FilaMan-System-ESP32 With this ESP32-based smart scale and RFID integration, you can simply place your spools on the scale, automatically measure the remaining weight, and sync the data seamlessly with this software via RFID tags!

🏠 Home Assistant Integration

If you are using Home Assistant, install FilaMan from our add-on repository: Fire-Devils/filaman-ha-app Add that URL under Settings → Add-ons → Add-on store → ⋮ → Repositories, then install FilaMan and run it directly inside your Home Assistant environment.

🎋 Bambuddy Integration

Connect FilaMan to Bambu Lab printers and AMS units with the Bambuddy driver plugin. The integration keeps spool and AMS information in sync, supports automatic assignment after weighing and inserting a spool, and reports filament usage back to FilaMan.

When used with Bambuddy, FilaMan can also apply your custom, Bambu Cloud-synced slicer profiles automatically when a spool is placed in an AMS slot. The correct material profile is then available in both the AMS and Bambu Studio, giving custom and third-party filament much the same seamless workflow as an official Bambu RFID spool.

Features

• Spool Management: Track remaining weight, estimated metres and percentage, location, and status.
• Filament and Spool Details: Consistent, responsive pages with quick actions and in-place editing.
• Standard Filament Properties: Temperature ranges, drying recommendations, print settings, and dimensions alongside typed extra fields.
• Catalogs and Imports: Search FilaManDB for filament specifications and import existing inventory from Spoolman.
• Dual RFID Tags: Store two RFID tag UIDs per spool, so either side of a dual-tag spool can identify the same inventory item.
• Multi-User: Role-based access control and tenant support.
• Printer Integration: Plugin system to connect with 3D printers and AMS units.
• Bambuddy Integration: Synchronize spool inventory and AMS assignments, track filament use, and automatically apply custom Bambu Cloud slicer profiles.
• Printable Labels: Print and export spool or filament labels with QR codes, custom layouts, grouped and searchable field tokens, and label-paper sheet output.
• Database Support: Works with SQLite (default), MySQL, and PostgreSQL.
• Responsive UI: Modern design with light, dark, and brand themes.
• OIDC (OAuth2) Login: Single Sign-On (SSO) via OpenID Connect for existing users.

🗺️ Roadmap

We have exciting plans for the future of FilaMan:

• Printer Plugins: Develop plugins to connect with various 3D printers (community contributions are highly welcome!).
• Mobile Apps: Dedicated apps for iOS and Android.

Installation

Quick Start (Docker)

The easiest way to start FilaMan is using Docker:

docker run -d \
  --name filaman-system-app \
  --restart unless-stopped \
  --pull always \
  -p 8083:8000 \
  -v filaman_data:/app/data \
  ghcr.io/fire-devils/filaman-system:latest

The application will be available at http://localhost:8083.

• Default Email: admin@example.com
• Default Password: admin123

Labels use a shared SVG/WASM renderer for the designer, exports and API. The image packages Node 20 and fonts; no server browser is required. SVG is the only label renderer, with no renderer selector or fallback. Container checks pass on native ARM64 and emulated AMD64/ARMv7; physical print/scan acceptance is still pending. See API documentation.

Build Docker Container Yourself

Prerequisites

• Docker
• Docker Buildx with multi-architecture support (for ARM/AMD)

Build and Run

git clone https://github.com/Fire-Devils/filaman-system.git && cd filaman-system

# Create .env if needed, then configure it.
test -e .env || cp .env.example .env

# Build image
docker build -t filaman-system:latest .

# Or use Docker Compose (adjust its data-volume path first)
PORT=8083 docker compose -f docker-compose.build.yml up --build

# Start container
docker run -d \
  --name filaman-system-app \
  --restart unless-stopped \
  -p 8083:8000 \
  -v filaman_data:/app/data \
  -e DEBUG=false \
  -e SECRET_KEY=your-secret-key \
  -e CSRF_SECRET_KEY=your-csrf-secret \
  -e ADMIN_EMAIL=admin@example.com \
  -e ADMIN_PASSWORD=your-admin-password \
  filaman-system:latest

Local Development

Prerequisites

• Python 3.11+
• Node.js 20.3+
• uv (Python Package Manager)

Start Backend

cd backend
uv sync
uv run uvicorn app.main:app --reload

The API will be available at http://localhost:8000.

Start Frontend

cd frontend
npm install
npm run dev

The frontend will be available at http://localhost:4321.

Build Frontend for Production

cd frontend
BUILD_MODE=static npx astro build

The static files will be in frontend/dist/.

Configuration (Environment Variables)

Create a .env file in the project root directory. Use .env.example as a template:

# Database Configuration
# SQLite (default):
DATABASE_URL=sqlite+aiosqlite:///./filaman.db

# MySQL:
# DATABASE_URL=mysql+aiomysql://username:password@hostname:3306/database

# PostgreSQL:
# DATABASE_URL=postgresql+asyncpg://username:password@hostname:5432/database

Generate Secrets

# Generate single secret
openssl rand -hex 32

# Generate all secrets at once
echo "SECRET_KEY=$(openssl rand -hex 32)"
echo "CSRF_SECRET_KEY=$(openssl rand -hex 32)"
echo "OIDC_ENC_KEY=$(openssl rand -hex 32)"

OIDC / SSO Configuration

To enable OIDC (OpenID Connect) login, set the following environment variable:

# Required for encrypting the OIDC client secret in the database
OIDC_ENC_KEY=your-fernet-key

Worker Processes

The Docker image starts 4 worker processes by default. Each one holds a full copy of the application (about 90 MB), so on a small host such as a Raspberry Pi you can run fewer:

# Default: 4. A single worker runs the printer drivers itself, nothing is forwarded.
WEB_CONCURRENCY=1

Note: When using MySQL or PostgreSQL, backups must be managed externally by the administrator. The automatic SQLite backup is disabled in this case.

Project Structure

/
├── backend/
│   ├── app/
│   │   ├── core/          # Config, database, security
│   │   ├── models/        # Database models
│   │   ├── services/      # Shared domain logic
│   │   └── plugins/       # Printer plugins
│   ├── alembic/           # Database migrations
│   └── tests/             # Backend tests
├── frontend/
│   ├── src/
│   │   ├── pages/         # Astro pages
│   │   ├── layouts/       # Page layouts
│   │   └── components/    # UI components
│   └── dist/              # Production build
└── docs/                  # Project documentation

Technology

Backend:

• FastAPI
• SQLAlchemy 2.0 + Alembic
• Python 3.11+

Frontend:

• Astro + Tailwind CSS
• Static Docker build; Node server output for source builds

License

MIT