FilaMan - Filament Management System

Support the FilaMan Project

♻️ 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.

💡 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, there is a very convenient Add-on available: ha-filaman-system This allows you to install and run the FilaMan System directly within your Home Assistant environment with just a few clicks.

Features

• Spool Management: Track remaining weight, location, and status.
• Multi-User: Role-based access control and tenant support.
• Printer Integration: Plugin system to connect with 3D printers and AMS units.
• 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.
• Printable Labels: Generate and print custom labels for your spools.

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

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

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

# Or with docker-compose
docker-compose 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 18+
• 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
npm run 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=aiomysql://username:password@hostname:3306/database

# PostgreSQL:
# DATABASE_URL=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

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
│   │   ├── modules/       # Domain modules
│   │   └── plugins/       # Printer plugins
│   ├── alembic/           # Database migrations
│   └── tests/             # Backend tests
├── frontend/
│   ├── src/
│   │   ├── pages/         # Astro pages
│   │   ├── layouts/       # Page layouts
│   │   └── components/    # UI components
│   └── dist/              # Production build
└── spec/                  # Project specifications

Technology

Backend:

• FastAPI
• SQLAlchemy 2.0 + Alembic
• Python 3.11+

Frontend:

• Astro + Tailwind CSS
• Static Build

License

MIT