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

Software (on your PC)

• Raspberry Pi Imager -- for writing the OS to the SD card (Download here)
• SSH Client -- for connecting to the Pi:
  • Windows: PuTTY 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:

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

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:

# macOS / Linux:
arp -a | grep raspberry

# Windows (PowerShell):
arp -a

Establish SSH Connection

macOS / Linux (Terminal):

ssh pi@filaman.local

Or using the IP address:

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:

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:

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:

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:

exit

Then reconnect via SSH:

ssh pi@filaman.local

Verify the Installation

Check that Docker is correctly installed:

docker --version

Expected output (version number may vary):

Docker version 27.x.x, build xxxxxxx

Also check Docker Compose:

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

mkdir ~/filaman && cd ~/filaman

Generate Secure Keys

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

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:

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:

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

Create Docker Compose File

nano docker-compose.yml

Paste the following content:

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:

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:

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

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

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

20.9 First Steps After Installation

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

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

For detailed information about plugin management: Admin Area

20.11 Update FilaMan

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

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

# 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

# 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

# Status of all containers
docker compose ps

# Detailed container info
docker inspect filaman-system-app

Reset Administrator Password

If you've forgotten your password:

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.

# 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

20.13 Troubleshooting

Container Won't Start

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)

Port Already in Use

If port 8000 is already used by another service:

1. Open the .env file:
   nano ~/filaman/.env
   

2. Change the port, e.g.:
   PORT=8080
   

3. Restart the container:
   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:
  sudo ufw status
  

  If active, allow the port:
  sudo ufw allow 8000/tcp
  

Forgotten Password

See Reset Administrator Password above or in the documentation: Tips & FAQ

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

For detailed information about backup recovery: Database Backup

20.14 Further Links

← Back: Plugin: Bambuddy | Back to Table of Contents

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