# 20. Installation on Raspberry Pi

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.

---

## 20.1 What You Need (Prerequisites)

### Hardware

| 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 |

### Software (on your PC)

- **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)

### Network

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

---

## 20.2 Install Raspberry Pi OS

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**.

### Step 1: Download Raspberry Pi Imager

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

> https://www.raspberrypi.com/software/

### Step 2: Open Imager and Configure

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)**

   > **Why "Lite"?** The Lite variant has no graphical desktop and uses fewer resources. FilaMan is a web application -- you access it through your PC's browser, not on the Pi itself.

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

   > **Warning:** All data on the SD card will be erased!

### Step 3: Configure Advanced Settings

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

**"General" tab:**

| 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 |

**"Services" tab:**

- Check the box for **"Enable SSH"**
- Select **"Use password authentication"**

> **What is SSH?** SSH (Secure Shell) allows you to remotely control the Raspberry Pi from your PC via the command line -- without needing a monitor connected to the Pi.

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

### Step 4: Boot the Raspberry Pi

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

---

## 20.3 Connect to the Raspberry Pi (SSH)

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

### Find the IP Address

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

**Option A: Using the hostname (easiest method)**

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

```bash
ping filaman.local
```

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

**Option B: Check your router**

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

**Option C: Scan the network**

On your PC you can alternatively use this command:

```bash
# macOS / Linux:
arp -a | grep raspberry

# Windows (PowerShell):
arp -a
```

### Establish SSH Connection

**macOS / Linux (Terminal):**

```bash
ssh pi@filaman.local
```

Or using the IP address:

```bash
ssh pi@192.168.1.42
```

> Replace `192.168.1.42` with the actual IP address of your Pi.

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.

**Windows (PuTTY):**

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

> **Tip:** Starting with Windows 10, you can also use the **Windows Terminal** or **Command Prompt** and use the same `ssh` command as on macOS/Linux.

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

```
pi@filaman:~ $
```

You're now logged into the Raspberry Pi.

---

## 20.4 Update the System

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

```bash
sudo apt update && sudo apt upgrade -y
```

> **What's happening here?**
> - `sudo` = run the command with administrator privileges
> - `apt update` = refresh the list of available software packages
> - `apt upgrade -y` = upgrade all packages to the latest version (`-y` = confirm automatically)

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

---

## 20.5 Install Docker

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.

### Install Docker

Run the following command:

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

> This command downloads the official Docker installation script and executes it. The installation takes about 2--5 minutes.

### Add Your User to the Docker Group

So you can run Docker commands without `sudo`:

```bash
sudo usermod -aG docker pi
```

> Replace `pi` with your username if you chose a different one.

### Log Out and Log Back In

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

```bash
exit
```

Then reconnect via SSH:

```bash
ssh pi@filaman.local
```

### Verify the Installation

Check that Docker is correctly installed:

```bash
docker --version
```

Expected output (version number may vary):

```
Docker version 27.x.x, build xxxxxxx
```

Also check Docker Compose:

```bash
docker compose version
```

Expected output:

```
Docker Compose version v2.x.x
```

> If both commands show a version number, Docker is ready to go.

---

## 20.6 Set Up FilaMan

Now we'll create the configuration files for FilaMan.

### Create a Directory

```bash
mkdir ~/filaman && cd ~/filaman
```

### Generate Secure Keys

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

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

> **Important:** Copy the two generated keys and save them. You'll need them shortly for the `.env` file.

The output looks something like this:

```
SECRET_KEY: 3a7f2b1e9c4d8f6a5e2b1c7d9f3a8e6b4c1d7f2a9e5b3c8d6f4a1e7b2c9d5f
CSRF_SECRET_KEY: 8e2f4a6c1d9b7e3f5a2c8d4b6e1f9a7c3d5b8e2f4a6c1d9b7e3f5a2c8d4b6e
```

### Create Configuration File (.env)

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

```bash
nano .env
```

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

```env
# ===========================================
# Database Configuration
# ===========================================
# SQLite (default - recommended for Raspberry Pi)
DATABASE_URL=sqlite+aiosqlite:////app/data/filaman.db

# ===========================================
# Security
# ===========================================
# IMPORTANT: Replace these with your generated keys!
SECRET_KEY=PASTE_YOUR_GENERATED_SECRET_KEY_HERE
CSRF_SECRET_KEY=PASTE_YOUR_GENERATED_CSRF_SECRET_KEY_HERE

# ===========================================
# Administrator Account
# ===========================================
# These credentials are used to create the admin account on first start
ADMIN_EMAIL=admin@example.com
ADMIN_PASSWORD=MySecurePassword123!
ADMIN_DISPLAY_NAME=Admin
ADMIN_LANGUAGE=en
ADMIN_SUPERADMIN=true

# ===========================================
# Application Settings
# ===========================================
DEBUG=false
CORS_ORIGINS=*
PORT=8000

# ===========================================
# Logging
# ===========================================
LOG_LEVEL=INFO
LOG_FORMAT=text
```

**Explanation of settings:**

| Setting | Description |
|---|---|
| `DATABASE_URL` | Database connection string. The default SQLite database is stored inside the container at `/app/data/` and is backed up automatically. |
| `SECRET_KEY` | Secret key for session encryption. **Must** be replaced with your generated key! |
| `CSRF_SECRET_KEY` | Secret key for CSRF protection. **Must** be replaced with your generated key! |
| `ADMIN_EMAIL` | Email address for the first administrator. This is your login name. |
| `ADMIN_PASSWORD` | Password for the administrator. **Choose a secure password!** At least 8 characters. |
| `ADMIN_DISPLAY_NAME` | Display name of the administrator in the UI. |
| `ADMIN_LANGUAGE` | UI language (`en` for English, `de` for German). |
| `ADMIN_SUPERADMIN` | Grants the first user full administrator rights. |
| `DEBUG` | Debug mode. Leave at `false` for normal operation. |
| `CORS_ORIGINS` | Allowed origin domains for API requests. `*` allows all. |
| `PORT` | External port on which FilaMan is accessible. Default: `8000`. |
| `LOG_LEVEL` | Detail level of log output (`INFO`, `DEBUG`, `WARNING`, `ERROR`). |
| `LOG_FORMAT` | Log format (`text` or `json`). |

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

### Create Docker Compose File

```bash
nano docker-compose.yml
```

Paste the following content:

```yaml
services:
  filaman-system-app:
    image: ghcr.io/fire-devils/filaman-system:latest
    container_name: filaman-system-app
    env_file:
      - .env
    environment:
      - DATABASE_URL=${DATABASE_URL}
      - SECRET_KEY=${SECRET_KEY}
      - CSRF_SECRET_KEY=${CSRF_SECRET_KEY}
      - DEBUG=${DEBUG}
      - CORS_ORIGINS=${CORS_ORIGINS}
      - ADMIN_EMAIL=${ADMIN_EMAIL}
      - ADMIN_PASSWORD=${ADMIN_PASSWORD}
      - ADMIN_DISPLAY_NAME=${ADMIN_DISPLAY_NAME}
      - ADMIN_LANGUAGE=${ADMIN_LANGUAGE}
      - ADMIN_SUPERADMIN=${ADMIN_SUPERADMIN}
    volumes:
      - filaman_data:/app/data
    restart: unless-stopped
    ports:
      - "${PORT}:8000"
    healthcheck:
      test: ["CMD", "python", "-c", "import urllib.request; urllib.request.urlopen('http://localhost:8000/health')"]
      interval: 30s
      timeout: 5s
      start_period: 15s
      retries: 3

volumes:
  filaman_data:
```

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

---

## 20.7 Start FilaMan

Everything is set up. Start FilaMan with:

```bash
docker compose up -d
```

> **What's happening here?**
> - `docker compose up` = starts the containers defined in `docker-compose.yml`
> - `-d` = run in the background (detached mode)

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

### Check the Logs

Review the logs to verify everything starts correctly:

```bash
docker compose logs -f
```

You should see output similar to:

```
filaman-system-app  | Checking for database migrations...
filaman-system-app  | Running migrations...
filaman-system-app  | Database migrations complete.
filaman-system-app  | Starting nginx...
```

> Press **Ctrl+C** to exit the log view (the container continues running in the background).

### Check Status

```bash
docker compose ps
```

If everything works, you'll see:

```
NAME                   STATUS                    PORTS
filaman-system-app     Up X minutes (healthy)    0.0.0.0:8000->8000/tcp
```

> The status should change to `(healthy)` after approximately 30 seconds.

---

## 20.8 Access FilaMan in the Browser

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

```
http://filaman.local:8000
```

Or use the IP address of your Raspberry Pi:

```
http://192.168.1.42:8000
```

> **Tip:** You can find your Pi's IP address with this command (on the Pi via SSH):
> ```bash
> hostname -I
> ```

### First Login

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.

> For detailed information about the login process, see the documentation: [Login](https://docu.filaman.app/Docs/En/02-Login)

---

## 20.9 First Steps After Installation

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) |

> **Tip:** Alternatively, you can import filaments from SpoolmanDB instead of creating everything manually. Install the SpoolmanDB plugin to do this (see next chapter).

---

## 20.10 Install Plugins

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

### Installing a Plugin

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

### Available Plugins

| 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) |

> For detailed information about plugin management: [Admin Area](https://docu.filaman.app/Docs/En/11-Admin#115-system-plugin-management)

---

## 20.11 Update FilaMan

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

```bash
cd ~/filaman
docker compose pull
docker compose up -d
```

> **What happens during an update?**
> 1. `docker compose pull` downloads the latest version of the Docker image
> 2. `docker compose up -d` restarts the container with the new version
> 3. On startup, a **database backup** is automatically created
> 4. Then all necessary **database migrations** are automatically applied
>
> Your data is fully preserved!

---

## 20.12 Useful Commands

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

### Manage Containers

```bash
# Navigate to the FilaMan directory
cd ~/filaman

# Stop containers
docker compose stop

# Start containers
docker compose start

# Restart containers
docker compose restart

# Stop and remove containers (data is preserved!)
docker compose down

# Create and start containers
docker compose up -d
```

### View Logs

```bash
# Show all logs (continuously)
docker compose logs -f

# Show only the last 100 lines
docker compose logs --tail 100

# Show logs since a specific time
docker compose logs --since 1h
```

### Check Container Status

```bash
# Status of all containers
docker compose ps

# Detailed container info
docker inspect filaman-system-app
```

### Reset Administrator Password

If you've forgotten your password:

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

> Replace `admin@example.com` with your actual admin email address. You'll be prompted to enter the new password twice.

### Data and Backups

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

```bash
# List backups inside the container
docker exec filaman-system-app ls -la /app/data/backups/
```

> Backups can also be managed through the web interface under **Admin Panel → Database Backup**. See: [Database Backup](https://docu.filaman.app/Docs/En/11-Admin#116-database-backup-restore)

---

## 20.13 Troubleshooting

### Container Won't Start

Check the logs for error messages:

```bash
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)

### Port Already in Use

If port 8000 is already used by another service:

1. Open the `.env` file:
   ```bash
   nano ~/filaman/.env
   ```
2. Change the port, e.g.:
   ```
   PORT=8080
   ```
3. Restart the container:
   ```bash
   cd ~/filaman
   docker compose down
   docker compose up -d
   ```
4. FilaMan will then be accessible at `http://filaman.local:8080`

### Cannot Access from Another Device

- 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:
  ```bash
  sudo ufw status
  ```
  If active, allow the port:
  ```bash
  sudo ufw allow 8000/tcp
  ```

### Forgotten Password

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)

### Database Issues

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:
   ```bash
   # List available backups
   docker exec filaman-system-app ls -la /app/data/backups/
   ```

> For detailed information about backup recovery: [Database Backup](https://docu.filaman.app/Docs/En/11-Admin#116-database-backup-restore)

---

## 20.14 Further Links

| 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)

---

*This guide was created for FilaMan. For technical questions or issues, please contact your system administrator.*