Filadex - 3D Printing Filament Management System

Filadex is an open-source filament management system for 3D printing enthusiasts. Born from the need for a comprehensive solution to track and manage 3D printing filaments, Filadex offers a clean, intuitive interface for monitoring your filament inventory, usage statistics, and storage information. This project is fully AI-coded, showcasing the potential of AI-assisted development in creating practical, user-friendly applications.

📸 Screenshots

Light Mode

Dark Mode

🌟 Features

• Filament Inventory Management: Track all your filaments in one place
• Material & Color Visualization: See your collection distribution at a glance
• Detailed Filament Properties: Record manufacturer, material type, color, weight, and more
• Usage Tracking: Monitor remaining filament percentages
• Statistics Dashboard: Get insights into your filament collection
• Filtering & Sorting: Easily find the filament you need
• Responsive Design: Works on desktop and mobile devices
• Self-hosted: Keep your data private and secure
• User Management: Admin interface for managing users
• Filament Sharing: Share your filament collection with others (globally or by material type)
• Public Filament View: Shared filament collections include material/color charts and filtering capabilities

📋 Prerequisites

• Node.js (v16 or higher)
• npm or yarn
• PostgreSQL (v12 or higher) or SQLite (embedded, no separate server needed)
• Docker & Docker Compose (optional, for containerized deployment)

🚀 Installation

Option 1: Local Development Setup

1. Clone the repository

git clone https://github.com/yourusername/filadex.git
cd filadex

2. Install dependencies

npm install

3. Set up environment variables

Create a .env file in the root directory:

# For PostgreSQL:
DATABASE_URL=postgres://username:password@localhost:5432/filadex

# Or for SQLite:
# DATABASE_URL=file:./dev.db

4. Initialize the database

npm run db:migrate
npm run db:init

5. Start the development server

npm run dev

The application will be available at http://localhost:5000

Option 2: Docker Deployment

Choose between PostgreSQL (multi-user default) and SQLite (single-user). Note that there is no migration path between the two engines in either direction — a deployer picks once:

Variant A: PostgreSQL (Default)

1. Copy the PostgreSQL template:

   cp docker-compose.template.yml docker-compose.yml
   cp .env.example .env

2. Set a database password. .env.example ships with POSTGRES_PASSWORD empty on purpose, and Compose refuses to start until it has a value:

   echo "POSTGRES_PASSWORD=$(openssl rand -base64 24)" >> .env

3. Start the containers:

   docker-compose up -d

Variant B: SQLite (Single-User, No External DB Container)

1. Copy the SQLite template:

   cp docker-compose.sqlite.template.yml docker-compose.yml
   cp .env.example .env

2. Start the container:

   docker-compose up -d

Database files and backups are persisted inside the filadex_data volume: the database at /data/filadex.db and scheduled snapshots in /data/backups (override with BACKUP_DIR). SQLite runs with write-ahead logging (WAL), producing -wal and -shm files beside the database, which is why external backups should copy the entire /data directory rather than copying a single .db file.

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

Variant C: Synology NAS (Container Manager with SQLite)

For a complete step-by-step guide on deploying Filadex on a Synology NAS using Container Manager, HTTPS reverse proxy, automated SQLite backups, and persistent storage, see docs/deployment-synology.md and docker-compose.synology.yml.

🔧 Configuration

Database Configuration

Filadex supports PostgreSQL and SQLite:

# PostgreSQL:
DATABASE_URL=postgres://username:password@localhost:5432/filadex

# SQLite:
DATABASE_URL=file:/data/filadex.db

When using SQLite, an admin-only DB Backups panel appears in Settings with on-demand snapshot creation, download, and automated scheduled backups (daily or weekly) with configurable retention pruning.

Application Configuration

You can configure various aspects of the application using environment variables:

# Server Configuration
PORT=8080                     # Port the application will run on
LOG_LEVEL=INFO                # Logging level (DEBUG, INFO, WARN, ERROR)

# Authentication
# The first admin account is created whenever no admin account exists. Its
# password is INITIAL_ADMIN_PASSWORD if you set one, and otherwise a random
# password printed once to the server log. Every route except changing the
# password and setting a language preference is refused until it has been
# changed.
INITIAL_ADMIN_PASSWORD=       # Optional; a random one is generated and logged
JWT_SECRET=your_secret_key    # Secret key for JWT token generation

# The address users open Filadex at. Verification and password-reset emails
# link here and are not sent while it is unset.
APP_URL=https://filadex.example.com

# Localization
# Build-time last resort for the UI language (en, de, pl). Reached only when a
# visitor has no stored choice, no language cookie, no <html lang> from the
# server, and no supported browser language - see the note below.
VITE_DEFAULT_LANGUAGE=en

# Data Initialization
INIT_SAMPLE_DATA=false        # Set to 'true' to initialize with sample data

Port Configuration

By default, the application runs on port 5000 in development mode. You can change this by setting the PORT environment variable.

For Docker deployment, you can configure the port in the docker-compose.yml file.

📱 Usage

Authentication and User Management

1. First Login: The first start creates the admin account (username: admin). Its password is whatever you set in INITIAL_ADMIN_PASSWORD, or a random one the server prints to its log once — docker compose logs filadex shows it
2. Password Change: Until that first password has been changed, the server refuses every other request from that account, and the app takes you to the change-password page
3. User Management: Admin users can access the user management interface by clicking the users icon in the header
4. Creating Users: Admins can create new users, set permissions, and manage existing accounts
5. Sharing Filaments: Users can share their filament collection by clicking the share icon in the header
   • Share all filaments or select specific material types to share
   • Copy the shareable link with one click
   • Shared collections include material/color charts and filtering capabilities
   • Public view doesn't require authentication

Filament Management

1. Adding Filaments: Click the "Add Filament" button to add a new filament to your inventory
2. Editing Filaments: Click the edit icon on a filament card to update its details
3. Filtering: Use the sidebar filters to find specific filaments by material, manufacturer, or color
4. Statistics: View your collection statistics in the statistics accordion
5. Visualization: See your material and color distribution in the pie chart

CSV Resources and Import/Export

Filadex comes with pre-populated CSV files in the resources directory that can be used to quickly set up your filament database:

1. Materials List (materials_init.csv): Contains various filament material types (PLA, PETG, ABS, etc.)
2. Filament Colors (filament_colors_init.csv): Contains color names and hex codes organized by manufacturer
3. Vendors List (vendors_init.csv): Contains a list of filament manufacturers/vendors

To use these resources:

1. Navigate to the Settings dialog by clicking the gear icon in the header
2. Find the Import/Export section for the data type you want to import (Materials, Colors, or Manufacturers)
3. Click "Import CSV" and select the corresponding file from the resources directory
4. The application will import the data, skipping any duplicates

You can also export your current data to CSV files for backup or sharing with the community. The community is encouraged to enhance these resource files by adding more materials, colors, and vendors while avoiding duplicate entries.

🤝 Contributing

Contributions are welcome! Please see our Contributing Guidelines for more details.

📝 Project Background

The inspiration for Filadex came from BambuLab's announcement of a filament management system. While waiting for their official release, I decided to create an open-source alternative that provides simple management with useful statistics. The project evolved to include user management and self-hosting capabilities, making it a versatile solution for the 3D printing community.

What makes Filadex unique is that it was fully coded with the assistance of AI. This project demonstrates how AI can be leveraged to create functional, well-structured applications while maintaining high code quality and user experience standards.

Now, I'm excited to share Filadex with the community and welcome contributions to make it even better!

📜 License

This project is licensed under the MIT License - see the LICENSE file for details.

📚 Documentation

API Documentation

Filadex provides a comprehensive API that allows you to interact with all aspects of the application programmatically. The API documentation is available in the API.md file, which includes:

• Detailed information about all available endpoints
• Request and response formats
• Authentication requirements
• Error handling
• Import/export functionality
• And more

Translation Documentation

Filadex supports multiple languages:

1. Available Languages

   • English (en)
   • German (de)
   • Polish (pl)

2. Language Selection

   • Users can select their preferred language from the language selector in the header, and from the login, register, forgot-password, reset-password and verify-email screens
   • Language preference is stored in user settings and persists across sessions
   • The application detects the browser language on first visit, taking the first supported entry from the browser's ranked language list
   • The server picks the same language for the initial HTML, so <html lang> matches the UI from the first render (see ADR 0005)

3. Adding New Languages

   • Language files are located in client/src/i18n/locales/
   • To add a new language, create a new file following the same structure as the existing ones
   • See our Translation Guide for detailed instructions
   • Submit a pull request to contribute translations

4. Environment Variables

   • VITE_DEFAULT_LANGUAGE: last-resort UI language (default: "en"). Inlined at build time, so it must be set when the client is built.

     This ranks lower than it used to. The server now resolves the language for the initial HTML and stamps it into <html lang>, and the client prefers that stamp - which already accounts for the stored account preference, the language cookie and Accept-Language - over this build-time value. Before, a build with VITE_DEFAULT_LANGUAGE=de showed German to every browser that did not ask for German; now such a browser gets its own language. If you relied on this variable to pin the UI for a deployment, set each account's language instead. Docker images are unaffected: the Dockerfile has never had a build arg for it.

🗺️ Roadmap

The following features are planned for future releases:

1. Additional Languages

   • Add support for more languages (French, Spanish, Italian, etc.)
   • Improve translation coverage across the application

2. Advanced Filament Management

   • Batch operations for filaments (delete, update)
   • Filament usage history tracking
   • Print job association with filaments

3. Enhanced Sharing Features

   • QR code generation for shared collections
   • Password protection for shared collections
   • Temporary sharing links with expiration

See the TODO.md file for a detailed list of pending tasks and improvements.

🙏 Acknowledgements

• All the contributors who have helped shape this project
• The 3D printing community for inspiration and feedback
• Open-source libraries and tools that made this project possible

---

Made with ❤️ for the 3D printing community