This guide is aimed at **absolute beginners** and explains step by step how to install FilaMan on a Raspberry Pi. No prior knowledge is required -- just a Raspberry Pi, a PC, and a little patience.

---

| Component | Recommendation | Note |

|---|---|---|

| **Raspberry Pi** | Model 3B+, 4, or 5 | Older models (Pi 1/2/Zero) are too underpowered |

| **Power Supply** | Official Raspberry Pi power supply | USB-C (Pi 4/5) or Micro-USB (Pi 3B+) |

| **microSD Card** | At least 16 GB, recommended 32 GB | Class 10 or faster |

| **Network** | Ethernet cable or Wi-Fi | Ethernet is more stable and recommended |

| **Case** (optional) | Any Pi case | Protects the Pi and improves cooling |

- **Raspberry Pi Imager** -- for writing the OS to the SD card ([Download here](https://www.raspberrypi.com/software/))

- **SSH Client** -- for connecting to the Pi:

- **Windows:** [PuTTY](https://www.putty.org/) or the built-in Windows Terminal (Windows 10+)

- **macOS / Linux:** Terminal (already pre-installed)

- The Raspberry Pi and your PC must be on the **same network** (same Wi-Fi or connected to the same router via cable)

---

The operating system for the Raspberry Pi is written to a microSD card. The easiest way to do this is with the **Raspberry Pi Imager**.

Download the Imager from the official website and install it on your PC:

1. Insert the **microSD card** into your PC (using an SD card reader if needed)

2. Open the **Raspberry Pi Imager**

3. Click **"Choose Device"** and select your Raspberry Pi model

4. Click **"Choose OS"** and select:

- **Raspberry Pi OS (other)** → **Raspberry Pi OS Lite (64-bit)**

5. Click **"Choose Storage"** and select your microSD card

Click **"Next"** and then **"Edit Settings"**. Here you configure important basic settings:

| Setting | Recommendation | Explanation |

|---|---|---|

| **Hostname** | `filaman` | The Pi will be reachable on your network under this name |

| **Username** | `pi` | Your username for logging into the Pi |

| **Password** | A secure password | Remember this password well! |

| **Configure Wi-Fi** | Your Wi-Fi name and password | Only needed if you're not using an Ethernet cable |

| **Locale settings** | Your timezone and keyboard layout | e.g. Europe/London, us |

- Check the box for **"Enable SSH"**

- Select **"Use password authentication"**

Click **"Save"** and then **"Yes"** to write the OS to the SD card.

1. Wait until the writing process is complete

2. Safely remove the microSD card from your PC

3. Insert the microSD card into the Raspberry Pi

4. Connect the Ethernet cable (if using wired networking)

5. Connect the power supply -- the Pi will start automatically

6. Wait approximately **1--2 minutes** for the Pi to fully boot up

---

Now you'll connect to the Raspberry Pi from your PC.

You need the IP address of your Raspberry Pi. There are several ways to find it:

If you set the hostname to `filaman`, try:

ping filaman.local

The response will show you the IP address (e.g. `192.168.1.42`).

1. Open your router's web interface (usually `192.168.1.1` or `192.168.0.1`)

2. Look for "filaman" or "raspberrypi" in the device list

3. Note the displayed IP address

On your PC you can alternatively use this command:

arp -a | grep raspberry

arp -a

ssh pi@filaman.local

Or using the IP address:

ssh pi@192.168.1.42

When connecting for the first time, you'll be asked whether you trust this host. Type `yes` and press Enter. Then enter the password you set in the Raspberry Pi Imager.

1. Open PuTTY

2. Enter in **Host Name**: `filaman.local` (or the IP address)

3. Port: `22`

4. Click **"Open"**

5. Username: `pi`

6. Password: Your chosen password

**When connected**, you'll see a command prompt like:

You're now logged into the Raspberry Pi.

---

Before installing FilaMan, let's bring the operating system up to date:

sudo apt update && sudo apt upgrade -y

This may take a few minutes. Wait until the process is complete.

---

FilaMan runs in a **Docker container**. Docker is software that runs applications in isolated packages (called containers). The advantage is that you don't need to worry about dependencies or configuration -- everything is bundled in the container.

Run the following command:

curl -fsSL https://get.docker.com | sh

So you can run Docker commands without `sudo`:

sudo usermod -aG docker pi

For the group change to take effect, you need to log out and back in:

Then reconnect via SSH:

ssh pi@filaman.local

Check that Docker is correctly installed:

docker --version

Expected output (version number may vary):

Also check Docker Compose:

docker compose version

Expected output:

---

Now we'll create the configuration files for FilaMan.

mkdir ~/filaman && cd ~/filaman

FilaMan requires two secret keys for security. Generate them with the following command:

echo "SECRET_KEY: $(openssl rand -hex 32)"

echo "CSRF_SECRET_KEY: $(openssl rand -hex 32)"

The output looks something like this:

Create the `.env` file with the settings for FilaMan:

nano .env

Paste the following content and **adjust the marked sections**:

Save the file with **Ctrl+O**, **Enter**, and close the editor with **Ctrl+X**.

nano docker-compose.yml

Paste the following content:

Save the file with **Ctrl+O**, **Enter**, and close the editor with **Ctrl+X**.

---

Everything is set up. Start FilaMan with:

docker compose up -d

On first start, the Docker image will be downloaded (approx. 200--400 MB). This may take a few minutes depending on your internet connection.

Review the logs to verify everything starts correctly:

docker compose logs -f

You should see output similar to:

docker compose ps

If everything works, you'll see:

---

FilaMan is now ready! Open a browser on your PC and navigate to:

Or use the IP address of your Raspberry Pi:

You'll see the FilaMan login page. Sign in with the credentials you set in the `.env` file:

- **Email:** The `ADMIN_EMAIL` from your `.env` (e.g. `admin@example.com`)

- **Password:** The `ADMIN_PASSWORD` from your `.env`

After signing in, you'll see the **Dashboard** -- FilaMan's home page.

---

Once FilaMan is running, it's recommended to set up your data in the following order:

| Step | What | Where | Documentation |

|---|---|---|---|

| 1 | **Create manufacturers** | Menu → Manufacturers | [Manufacturers](https://docu.filaman.app/Docs/En/05-Manufacturers) |

| 2 | **Define colors** | Menu → Filaments → "Manage Colors" | [Color Management](https://docu.filaman.app/Docs/En/12-Colors) |

| 3 | **Create filaments** | Menu → Filaments → "Add Filament" | [Filaments](https://docu.filaman.app/Docs/En/06-Filaments) |

| 4 | **Set up locations** | Menu → Locations → "Add Location" | [Locations](https://docu.filaman.app/Docs/En/08-Locations) |

| 5 | **Add spools** | Menu → Spools → "Add Spool" | [Spools](https://docu.filaman.app/Docs/En/07-Spools) |

| 6 | **Connect printers** (optional) | Menu → Printers → "Add Printer" | [Printers](https://docu.filaman.app/Docs/En/09-Printers) |

---

FilaMan can be extended with plugins. Installation is done conveniently through the web interface.

1. Go to **Admin Panel** → **System**

2. Click **"Install Plugin"**

3. Select the desired plugin from the **"Install from Registry"** dropdown

4. Click **"Install Plugin"**

5. The plugin will be automatically downloaded and installed

| Plugin | Type | Description | Documentation |

|---|---|---|---|

| **BambuLab** | Driver | Connect BambuLab printers (AMS, filament sync) | [Plugin: BambuLab](https://docu.filaman.app/Docs/En/14-Plugin-Bambulab) |

| **SpoolmanDB Import** | Import | Import filaments from the SpoolmanDB database | [Plugin: SpoolmanDB](https://docu.filaman.app/Docs/En/15-Plugin-Spoolmandb) |

| **Spoolman API** | Import | Spoolman-compatible API for external tools | [Plugin: Spoolman API](https://docu.filaman.app/Docs/En/16-Plugin-Spoolmanapi) |

| **Bambuddy** | Integration | Bambuddy integration for inventory sync | [Plugin: Bambuddy](https://docu.filaman.app/Docs/En/17-Plugin-Bambuddy) |

---

To update FilaMan to the latest version, run the following commands on the Raspberry Pi:

cd ~/filaman

docker compose pull

docker compose up -d

---

Here's an overview of the most important Docker commands for daily operation:

cd ~/filaman

docker compose stop

docker compose start

docker compose restart

docker compose down

docker compose up -d

docker compose logs -f

docker compose logs --tail 100

docker compose logs --since 1h

docker compose ps

docker inspect filaman-system-app

If you've forgotten your password:

docker exec -it filaman-system-app python -m app.cli reset-password admin@example.com

FilaMan data is stored in a Docker volume. Automatic SQLite backups are created under `/app/data/backups` inside the container.

docker exec filaman-system-app ls -la /app/data/backups/

---

Check the logs for error messages:

docker compose logs

Common causes:

- **Missing or invalid `.env` file** -- Check that all required fields are set

- **Syntax error in `docker-compose.yml`** -- Ensure correct indentation (spaces, not tabs)

If port 8000 is already used by another service:

1. Open the `.env` file:

nano ~/filaman/.env

2. Change the port, e.g.:

3. Restart the container:

cd ~/filaman

docker compose down

docker compose up -d

4. FilaMan will then be accessible at `http://filaman.local:8080`

- Make sure your PC and Raspberry Pi are on the **same network**

- Use the **IP address** instead of the hostname (`http://192.168.x.x:8000`)

- Check if a firewall on the Pi is blocking the port:

sudo ufw status

If active, allow the port:

sudo ufw allow 8000/tcp

See [Reset Administrator Password](#reset-administrator-password) above or in the documentation: [Tips & FAQ](https://docu.filaman.app/Docs/En/13-Faq#ive-forgotten-my-admin-password-what-now)

If the database is corrupted, you can restore a backup:

1. Via the web interface: **Admin Panel → Database Backup → SQLite Backups → Restore**

2. Or manually via the command line:

docker exec filaman-system-app ls -la /app/data/backups/

---

| Resource | Link |

|---|---|

| **FilaMan Documentation (English)** | [docu.filaman.app/Docs/En/00-Contents](https://docu.filaman.app/Docs/En/00-Contents) |

| **FilaMan Documentation (German)** | [docu.filaman.app/Docs/De/00-Inhalt](https://docu.filaman.app/Docs/De/00-Inhalt) |

| **GitHub: FilaMan System** | [github.com/Fire-Devils/filaman-system](https://github.com/Fire-Devils/filaman-system) |

| **GitHub: FilaMan Plugins** | [github.com/Fire-Devils/filaman-plugins](https://github.com/Fire-Devils/filaman-plugins) |

| **GitHub: FilaMan ESP32** | [github.com/Fire-Devils/FilaMan-System-ESP32](https://github.com/Fire-Devils/FilaMan-System-ESP32) |

| **Docker Image** | [ghcr.io/fire-devils/filaman-system](https://github.com/Fire-Devils/filaman-system/pkgs/container/filaman-system) |

---

← [Back: Plugin: Bambuddy](/Docs/En/17-Plugin-Bambuddy) | [Back to Table of Contents](/Docs/En/00-Contents)

---