FileBrowser

FileBrowser is a web-based file manager for browsing and managing files on the px3 NAS node. It provides a user-friendly interface to access storage across the homelab infrastructure.

Overview

Property	Value
Location	px3 (UK Homelab NAS)
Host IP	REDACTED_IP7
Port	8080
URL	https://files.charliehub.net
Auth	FileBrowser built-in (username/password)
Root Directory	/mnt/filebrowser
Database	/etc/filebrowser/filebrowser.db

Quick Start

1. Open https://files.charliehub.net
2. Log in with FileBrowser credentials
3. Browse and manage files on NAS

Accessible Storage

FileBrowser exposes the following storage via symlinks in /mnt/filebrowser/:

Path	Size	Purpose
NAS-Storage → /mnt/nas-storage	1.8TB	Primary NAS storage
USB-Drive → /mnt/usb-wd	External	USB backup drive

NAS-Storage Contents

/mnt/nas-storage/
├── .private/          # Private user directories (restricted)
│   └── charles/       # Charles's personal files
├── public/            # Public shared files (readable by all)
├── synced/            # Team synchronized files
├── dump/              # General file dump
├── snippets/          # Code snippets
├── images/            # Media library
├── template/          # Template files
└── lost+found/        # Recovered files (if any)

User Access Control

Current Users

Username	Scope	Admin	Permissions
admin	/ (root)	Yes	Full access
charles	/ (root)	Yes	Full access

Authentication Flow

1. User visits https://files.charliehub.net
         ↓
2. Traefik routes to FileBrowser (SSL termination)
         ↓
3. User logs in with FileBrowser credentials
         ↓
4. User sees file browser

Architecture

Service Configuration

Systemd Service (on px3)

[Unit]
Description=File Browser
After=network-online.target

[Service]
Type=simple
ExecStart=/usr/local/bin/filebrowser \
  -d /etc/filebrowser/filebrowser.db \
  -r /mnt/filebrowser \
  -p 8080 \
  -a 0.0.0.0
Restart=on-failure

Traefik Route (on hub2)

# /opt/charliehub/traefik/config/dynamic/filebrowser.yml
http:
  routers:
    filebrowser-charliehub-net:
      entryPoints: [websecure]
      rule: Host(`files.charliehub.net`)
      service: filebrowser-charliehub-net-service
      tls:
        certResolver: letsencrypt
      # No Authelia - FileBrowser has its own authentication

  services:
    filebrowser-charliehub-net-service:
      loadBalancer:
        servers:
          - url: http://REDACTED_IP7:8080

Key Components

• hub2 (Traefik): Entry point, SSL termination
• px3 (FileBrowser): File serving, built-in authentication
• WireGuard VPN: Secure network tunnel between hub2 and px3

Managing Users

Add New User with Restricted Access

# SSH to px3
ssh root@px3

# Stop filebrowser service
systemctl stop filebrowser.service

# Add user with scope-based access (only sees specific directory)
/usr/local/bin/filebrowser -d /etc/filebrowser/filebrowser.db users add contractor password \
  --scope /NAS-Storage/synced \
  --perm.admin=false \
  --perm.create --perm.delete --perm.download

# Restart service
systemctl start filebrowser.service

Available Permissions

• perm.admin - Admin panel access
• perm.create - Create files/directories
• perm.delete - Delete files/directories
• perm.rename - Rename items
• perm.modify - Edit files
• perm.share - Create share links
• perm.download - Download files
• perm.execute - Run commands (if enabled)

Add Path-Based Restrictions

# Deny access to .private folders for a user
/usr/local/bin/filebrowser -d /etc/filebrowser/filebrowser.db rules add \
  "^/NAS-Storage/\.private/.*" --regex --username contractor

Update User Password

# Change password for existing user
/usr/local/bin/filebrowser -d /etc/filebrowser/filebrowser.db users update username --password newpassword

Remove User

/usr/local/bin/filebrowser -d /etc/filebrowser/filebrowser.db users rm username

Operations

Check Service Status

# On px3
systemctl status filebrowser.service
journalctl -u filebrowser.service -f

View Configuration

# On px3 (stop service first)
systemctl stop filebrowser.service
/usr/local/bin/filebrowser -d /etc/filebrowser/filebrowser.db config cat
systemctl start filebrowser.service

Restart Service

# On px3
systemctl restart filebrowser.service

Test Local Access

HEAD Requests Return 404

FileBrowser does not properly support HTTP HEAD requests (curl -I). Always use GET requests for testing:

# WRONG - returns 404
curl -I http://REDACTED_IP7:8080

# CORRECT - returns 200
curl -s -o /dev/null -w "%{http_code}" http://REDACTED_IP7:8080

# From px3 CT
wget -qS -O /dev/null http://localhost:8080

# From hub2 (via WireGuard)
curl -s -o /dev/null -w "%{http_code}" http://REDACTED_IP7:8080

Test Public Access

# Test via HTTPS (should return 200)
curl -s -o /dev/null -w "%{http_code}" https://files.charliehub.net

Troubleshooting

504 Gateway Timeout / Connection Refused

Symptom: https://files.charliehub.net returns 504 or connection refused

Cause: Network misconfiguration on CT 3117 (FileBrowser container)

Checks: 1. Verify hub2 can reach FileBrowser:

# From hub2
curl -s -o /dev/null -w "%{http_code}" http://REDACTED_IP7:8080
# Should return 200

1. Check CT network configuration:

   # From px3
   pct config 3117 | grep net0
   # Should show: ip=REDACTED_IP7/24,gw=REDACTED_IP
   

2. Verify bidirectional connectivity:

   # From hub2
   ping -c 2 REDACTED_IP7
   
   # From px3
   pct exec 3117 -- ping -c 2 REDACTED_IP  # hub2 WireGuard IP
   

Common Issue - Wrong Netmask:

If the CT has /16 instead of /24, it thinks the entire 10.44.x.x range is local and tries to ARP for hub2's WireGuard IP instead of routing through the gateway.

Fix:

# On px3 - correct the netmask and gateway
pct set 3117 -net0 name=eth0,bridge=vmbr0,gw=REDACTED_IP,hwaddr=BC:24:11:1F:C0:8F,ip=REDACTED_IP7/24,type=veth
pct reboot 3117

Cannot Access Files from Browser

Symptom: Login works but directory listing shows 403 or 404

Checks: 1. Verify filebrowser is running:

systemctl status filebrowser.service

1. Verify storage is accessible:

   ls -la /mnt/filebrowser/
   ls -la /mnt/nas-storage/
   

2. Check filebrowser logs:

   journalctl -u filebrowser.service -n 50
   

3. Verify user has proper permissions:

   systemctl stop filebrowser.service
   /usr/local/bin/filebrowser -d /etc/filebrowser/filebrowser.db users ls
   systemctl start filebrowser.service
   

Network Unreachable

Symptom: Cannot connect to https://files.charliehub.net or times out

Checks: 1. Verify DNS resolution:

dig files.charliehub.net
# Should return 51.68.235.106 (hub2's IP)

1. Verify Traefik route exists:

   # On hub2
   docker logs charliehub-traefik | grep filebrowser
   

2. Verify px3 connectivity:

   # From hub2
   ping REDACTED_IP7
   curl -s -o /dev/null -w "%{http_code}" http://REDACTED_IP7:8080
   

3. Check firewall:

   # On px3
   ss -tlnp | grep 8080
   

Security Notes

1. Built-in Authentication: FileBrowser uses its own user database for authentication
2. Not directly accessible from the internet (only via hub2 reverse proxy)

3. Accessible only through WireGuard-connected Traefik

4. HTTPS Only: All traffic encrypted via Let's Encrypt certificates

5. User Isolation: Use scopes and rules to restrict user access to specific directories

6. Password Requirements: Minimum 12 characters enforced by FileBrowser

Backup & Recovery

Backup FileBrowser Database

The FileBrowser database contains all user accounts, settings, and permissions:

# On px3
sudo cp /etc/filebrowser/filebrowser.db /backup/filebrowser-$(date +%Y%m%d).db

Restore FileBrowser Database

# On px3
systemctl stop filebrowser.service
sudo cp /backup/filebrowser-YYYYMMDD.db /etc/filebrowser/filebrowser.db
systemctl start filebrowser.service

Version Information

• FileBrowser Version: 2.53.0
• Deployment Date: 2026-01-14
• Last Updated: 2026-01-21

Related Documentation

• Traefik Routing
• px3 Proxmox Node