FileBrowser: Self-Hosted Web File Manager

Overview

FileBrowser is a lightweight, self-hosted web application that provides an intuitive file management interface accessible from any web browser. Think of it as your personal cloud storage interface - like Dropbox or Google Drive - but completely under your control and running on your own infrastructure.

Built with Go and modern web technologies, FileBrowser offers a clean, responsive interface that works seamlessly on desktop and mobile devices. Whether you need to browse files from your phone, share documents with family members, or manage your media library remotely, FileBrowser provides the perfect balance of simplicity and functionality.

What You’ll Learn:

Deploy FileBrowser using Docker with persistent storage
Configure user authentication and permissions
Set up multiple user accounts with isolated directories
Implement file sharing with custom permissions
Configure upload limits and file type restrictions
Integrate with reverse proxies for secure remote access
Customize the interface and branding
Set up automated backups of FileBrowser configuration

Why Choose FileBrowser?

Unlike heavyweight alternatives like Nextcloud, FileBrowser focuses exclusively on file management without the bloat of additional features. It’s perfect for homelabbers who want simple, fast file access without managing complex dependencies or databases. The entire application runs as a single binary with minimal resource usage, making it ideal for Raspberry Pi and low-power devices.

Prerequisites

Before starting, ensure you have:

Required:

Docker and Docker Compose installed
Basic understanding of Docker concepts
100 MB RAM minimum (512 MB recommended)
Network port 8080 available (or your chosen port)
Storage space for your files

Optional but Recommended:

Reverse proxy (Traefik, Nginx Proxy Manager, Caddy)
Domain name for HTTPS access
Basic understanding of file permissions

Pre-Deployment Checklist:

Docker environment is functional
Storage location identified for file hosting
User access requirements planned
Port 8080 is available (or alternative chosen)
Backup strategy considered

Understanding FileBrowser

Core Features

File Management:

Upload, download, rename, move, and delete files
Create and extract archives (ZIP, TAR, etc.)
Text file editing with syntax highlighting
Image and video preview in browser
Audio playback with playlist support
PDF viewing without downloads

User Management:

Multiple user accounts with individual permissions
Per-user directory scoping (home directories)
Customizable access rules per user
Guest accounts with read-only access
LDAP authentication support (optional)

Sharing:

Generate shareable links for files and folders
Password-protected shares
Expiring links with automatic cleanup
Download-only or view-and-download options
Share statistics and tracking

Advanced Features:

Command execution on server (with permissions)
Custom commands for file operations
WebDAV support for desktop mounting
Search functionality across files
Sorting and filtering options
Multiple language support

Architecture Overview

Browser/Client
      ↓
   FileBrowser Web UI (Port 8080)
      ↓
   FileBrowser Server
      ↓
   Docker Volume or Host Directory
      ↓
   Your Files

FileBrowser operates as a single Go binary that serves both the web interface and handles file operations. All configuration is stored in a SQLite database, making it easy to backup and migrate.

Installation and Deployment

Method 1: Docker Compose (Recommended)

This method provides the best balance of simplicity and control.

Create directory structure:

# Create FileBrowser directory
mkdir -p /opt/filebrowser/{config,data}
cd /opt/filebrowser

Create docker-compose.yml:

version: '3.8'

services:
  filebrowser:
    image: filebrowser/filebrowser:latest
    container_name: filebrowser
    restart: unless-stopped

    # Environment variables
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=America/New_York

    # Port mapping
    ports:
      - "8080:80"

    # Volume mounts
    volumes:
      # FileBrowser database and config
      - ./config/filebrowser.db:/database/filebrowser.db
      - ./config/settings.json:/config/settings.json
      # Root directory for file management
      - ./data:/srv
      # Optional: Add additional mount points
      - /mnt/media:/srv/media
      - /mnt/documents:/srv/documents
      - /mnt/backups:/srv/backups

    # Security
    security_opt:
      - no-new-privileges:true

    # Resource limits (optional)
    deploy:
      resources:
        limits:
          cpus: '1'
          memory: 512M
        reservations:
          cpus: '0.25'
          memory: 128M

    # Network
    networks:
      - filebrowser-net

networks:
  filebrowser-net:
    driver: bridge

Deploy FileBrowser:

# Start the container
docker-compose up -d

# View logs
docker-compose logs -f filebrowser

# Check status
docker-compose ps

Access FileBrowser:

Open your browser to http://YOUR-SERVER-IP:8080

Default credentials:

Username: admin
Password: admin

IMPORTANT: Change these credentials immediately after first login!

Method 2: Docker with Custom Configuration

For more control over initial setup:

# Create configuration directory
mkdir -p /opt/filebrowser/config

# Create custom config file
cat > /opt/filebrowser/config/settings.json << 'EOF'
{
  "port": 80,
  "baseURL": "",
  "address": "0.0.0.0",
  "log": "stdout",
  "database": "/database/filebrowser.db",
  "root": "/srv",
  "signup": false,
  "createUserDir": true,
  "defaults": {
    "scope": ".",
    "locale": "en",
    "viewMode": "list",
    "singleClick": false,
    "sorting": {
      "by": "name",
      "asc": true
    },
    "perm": {
      "admin": false,
      "execute": true,
      "create": true,
      "rename": true,
      "modify": true,
      "delete": true,
      "share": true,
      "download": true
    }
  }
}
EOF

# Run with custom config
docker run -d   --name filebrowser   --restart unless-stopped   -p 8080:80   -v /opt/filebrowser/config:/config   -v /opt/filebrowser/config/filebrowser.db:/database/filebrowser.db   -v /opt/filebrowser/data:/srv   -e PUID=1000   -e PGID=1000   filebrowser/filebrowser:latest

Initial Configuration

Change Default Credentials

CRITICAL SECURITY STEP:

Log in with default credentials (admin/admin)
Click on Settings (gear icon in top right)
Click User Management → admin
Change username and password
Click Save

Alternatively, change password via CLI:

# Access container
docker exec -it filebrowser /bin/sh

# Change admin password
filebrowser users update admin --password "YOUR-STRONG-PASSWORD-HERE"

# Exit container
exit

Configure Basic Settings

Access Settings:

Click Settings (gear icon)
Go to Global Settings

Key configurations:

Branding:

Instance Name: Your custom name
Disable external links: Toggle if desired
Custom CSS: Add your styling

Security:

Signup: Disabled (prevent unauthorized registration)
Create User Dir: Enabled (auto-create user directories)
User Home Base: Path where user dirs are created

Defaults:

View Mode: List or Grid
Sorting: Name, Size, Modified date
Locale: Your language preference

Example configuration:

{
  "signup": false,
  "createUserDir": true,
  "userHomeBasePath": "/srv/users",
  "defaults": {
    "scope": ".",
    "locale": "en",
    "viewMode": "list",
    "perm": {
      "admin": false,
      "execute": false,
      "create": true,
      "rename": true,
      "modify": true,
      "delete": true,
      "share": true,
      "download": true
    }
  }
}

User Management

Creating Users

Via Web Interface:

Go to Settings → User Management
Click New User
Configure user settings:

User Details:

Username: Unique identifier
Password: Strong password
Scope: Directory the user can access
- / = Full access to all files
- /users/john = Restricted to john’s directory
- /media = Only media directory

Permissions:

Admin: Full system access
Execute: Run commands
Create: Upload and create files/folders
Rename: Rename files/folders
Modify: Edit file contents
Delete: Remove files/folders
Share: Generate share links
Download: Download files

Example user creation via CLI:

# Create a regular user
docker exec -it filebrowser filebrowser users add john "secure-password"   --scope /srv/users/john   --perm.create --perm.rename --perm.modify --perm.delete --perm.share --perm.download

# Create a read-only user
docker exec -it filebrowser filebrowser users add guest "guest-password"   --scope /srv/shared   --perm.download

# Create an admin user
docker exec -it filebrowser filebrowser users add superuser "admin-password"   --perm.admin

User Permission Strategies

Strategy 1: Isolated User Directories

volumes:
  - ./data/users:/srv/users

Users: john (scope: /users/john), jane (scope: /users/jane)

# Create user directories
mkdir -p /opt/filebrowser/data/users/{john,jane}
chown -R 1000:1000 /opt/filebrowser/data/users

Strategy 2: Shared with Personal Folders

volumes:
  - ./data:/srv

Structure:

/srv
├── shared/      (all users can access)
├── users/
│   ├── john/   (only john)
│   └── jane/   (only jane)
└── public/      (read-only for all)

Strategy 3: Role-Based Access

Admins: scope /, full permissions
Editors: scope /content, create/modify/delete
Viewers: scope /content, download only

Managing User Directories

Automatic directory creation:

When createUserDir is enabled, FileBrowser automatically creates user directories on first login.

Manual directory management:

# Create structure
mkdir -p /opt/filebrowser/data/users/{john,jane,bob}

# Set ownership (match PUID/PGID in docker-compose)
chown -R 1000:1000 /opt/filebrowser/data/users

# Set permissions
chmod -R 755 /opt/filebrowser/data/users

Via Web Interface:

Navigate to file or folder
Click Share icon
Configure share options:
- Password: Optional protection
- Expires: Set expiration date/time
- Unit: Download count limit
Copy the generated link
Share with recipients

Share link format:

http://YOUR-SERVER-IP:8080/share/RANDOM-TOKEN

Best practices:

Always use passwords for sensitive files
Set expiration dates to limit exposure
Use unit limits for one-time downloads
Review active shares regularly

Managing shares:

Go to Settings → Share Management
View all active shares
Delete unused or expired shares
Monitor download statistics

Customize share settings in settings.json:

{
  "sharing": {
    "enabled": true,
    "passwordProtection": true,
    "expirationEnabled": true,
    "downloadLimit": true
  }
}

Disable sharing globally:

docker exec -it filebrowser filebrowser config set --sharing.enabled=false

Disable sharing per user:

Remove the “share” permission when creating or updating users.

Storage Configuration

Mounting Additional Directories

Add directories to docker-compose.yml:

volumes:
  # Main data directory
  - ./data:/srv

  # Media libraries
  - /mnt/media/movies:/srv/movies:ro  # Read-only
  - /mnt/media/tv:/srv/tv:ro
  - /mnt/media/music:/srv/music

  # Documents
  - /mnt/documents:/srv/documents

  # Backups
  - /mnt/backups:/srv/backups

  # Network shares (if mounted on host)
  - /mnt/nas:/srv/nas:ro

After adding volumes:

# Recreate container with new volumes
docker-compose up -d

File Upload Limits

Configure maximum upload size:

By default, FileBrowser has no upload size limit. To add restrictions:

Using reverse proxy (Nginx):

client_max_body_size 100M;

Using reverse proxy (Traefik):

http:
  middlewares:
    limit:
      buffering:
        maxRequestBodyBytes: 104857600  # 100 MB

File Type Restrictions

FileBrowser doesn’t have built-in file type restrictions, but you can implement them via:

Custom commands (restrict certain extensions) Reverse proxy rules (block specific MIME types) File system permissions (prevent writing certain files)

Reverse Proxy Integration

Traefik Configuration

Update docker-compose.yml:

services:
  filebrowser:
    image: filebrowser/filebrowser:latest
    container_name: filebrowser
    restart: unless-stopped

    environment:
      - PUID=1000
      - PGID=1000

    volumes:
      - ./config/filebrowser.db:/database/filebrowser.db
      - ./data:/srv

    networks:
      - traefik

    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.filebrowser.rule=Host(`files.yourdomain.com`)"
      - "traefik.http.routers.filebrowser.entrypoints=websecure"
      - "traefik.http.routers.filebrowser.tls.certresolver=letsencrypt"
      - "traefik.http.services.filebrowser.loadbalancer.server.port=80"

networks:
  traefik:
    external: true

Nginx Proxy Manager Configuration

Log into Nginx Proxy Manager
Add Proxy Host:
- Domain: files.yourdomain.com
- Scheme: http
- Forward Hostname: filebrowser (or container IP)
- Forward Port: 80
Enable SSL → Request Let’s Encrypt certificate
Optional: Enable Force SSL

Caddy Configuration

Caddyfile:

files.yourdomain.com {
    reverse_proxy filebrowser:80

    # Optional: Basic auth
    basicauth {
        user $2a$14$hashed_password_here
    }
}

Cloudflare Tunnel

If using Cloudflare Tunnels for secure access:

tunnel: YOUR-TUNNEL-ID
credentials-file: /root/.cloudflared/YOUR-TUNNEL-ID.json

ingress:
  - hostname: files.yourdomain.com
    service: http://filebrowser:80
  - service: http_status:404

Customization

Custom Branding

Add custom CSS:

Go to Settings → Global Settings
Scroll to Custom Stylesheet
Add your CSS:

/* Custom header color */
header {
    background-color: #2c3e50 !important;
}

/* Custom accent color */
.button--flat {
    color: #3498db !important;
}

/* Hide certain elements */
.action--delete {
    display: none;
}

Change instance name:

Settings → Global Settings → Instance Name

Custom Commands

Add server-side commands accessible from the UI:

Go to Settings → Global Settings → Commands
Add custom commands:

Example: Image optimization

# Command name: Optimize Image
# Command: convert #{file} -quality 85 #{file}

Example: Video thumbnail

# Command name: Generate Thumbnail
# Command: ffmpeg -i #{file} -ss 00:00:01.000 -vframes 1 #{file}.jpg

Available placeholders:

#{file} - Selected file path
#{username} - Current username
#{scope} - User’s scope directory

Language and Locale

Change interface language:

User Settings → Locale
Choose from available languages

Supported languages include English, Spanish, French, German, Portuguese, Russian, Chinese, and many more.

Security Hardening

Authentication Best Practices

Strong passwords:

# Generate strong random password
openssl rand -base64 32

# Update user password
docker exec -it filebrowser filebrowser users update USERNAME --password "STRONG-PASSWORD"

Disable signup:

docker exec -it filebrowser filebrowser config set --signup=false

HTTPS/TLS Configuration

Never expose FileBrowser directly to the internet without HTTPS.

Always use a reverse proxy with SSL/TLS:

Let’s Encrypt certificates (free)
Cloudflare SSL (free)
Self-signed certificates (for local network only)

Firewall Rules

UFW (Ubuntu firewall):

# Allow only from local network
sudo ufw allow from 192.168.1.0/24 to any port 8080 proto tcp

# Or block direct access entirely (use reverse proxy only)
sudo ufw deny 8080/tcp

Docker network isolation:

networks:
  filebrowser-net:
    driver: bridge
    internal: true  # No external access

Then expose only via reverse proxy.

File System Permissions

Principle of least privilege:

# FileBrowser runs as PUID/PGID (default 1000)
# Ensure files are owned correctly

# Set ownership
chown -R 1000:1000 /opt/filebrowser/data

# Read-only directories
chown -R 1000:1000 /mnt/media
chmod -R 555 /mnt/media  # Read and execute only

# Writable user directories
chmod -R 755 /opt/filebrowser/data/users

Backup and Restore

Backup FileBrowser Configuration

What to backup:

FileBrowser database: ./config/filebrowser.db
Settings file: ./config/settings.json
Your data files: ./data (or wherever they’re stored)

Automated backup script:

#!/bin/bash
# /opt/scripts/backup-filebrowser.sh

BACKUP_DIR="/mnt/backups/filebrowser"
DATE=$(date +%Y%m%d_%H%M%S)
SOURCE_CONFIG="/opt/filebrowser/config"
SOURCE_DATA="/opt/filebrowser/data"

# Create backup directory
mkdir -p "$BACKUP_DIR"

# Backup database and config
tar -czf "$BACKUP_DIR/filebrowser-config-$DATE.tar.gz" -C "$SOURCE_CONFIG" .

# Backup data (optional, may be large)
# tar -czf "$BACKUP_DIR/filebrowser-data-$DATE.tar.gz" -C "$SOURCE_DATA" .

# Keep only last 7 days of backups
find "$BACKUP_DIR" -name "filebrowser-config-*.tar.gz" -mtime +7 -delete

echo "Backup completed: $DATE"

Automate with cron:

# Edit crontab
crontab -e

# Add daily backup at 2 AM
0 2 * * * /opt/scripts/backup-filebrowser.sh >> /var/log/filebrowser-backup.log 2>&1

Restore from Backup

# Stop FileBrowser
docker-compose down

# Restore configuration
tar -xzf /mnt/backups/filebrowser/filebrowser-config-20250115_020000.tar.gz   -C /opt/filebrowser/config

# Restore data (if backed up)
# tar -xzf /mnt/backups/filebrowser/filebrowser-data-20250115_020000.tar.gz #   -C /opt/filebrowser/data

# Set permissions
chown -R 1000:1000 /opt/filebrowser

# Start FileBrowser
docker-compose up -d

Troubleshooting

Issue 1: Cannot Access FileBrowser

Symptoms:

Browser shows “Connection refused” or “Unable to connect”

Diagnostics:

# Check if container is running
docker ps | grep filebrowser

# Check container logs
docker logs filebrowser

# Verify port is listening
sudo netstat -tlnp | grep 8080

Solutions:

Container not running:

docker-compose up -d

Port conflict:

# Change port in docker-compose.yml
ports:
  - "8081:80"  # Use different port

Firewall blocking:

sudo ufw allow 8080/tcp

Issue 2: Permission Denied Errors

Symptoms:

Cannot upload files
Cannot create directories
Error messages about permissions

Diagnostics:

# Check file ownership
ls -la /opt/filebrowser/data

# Check container user
docker exec filebrowser id

Solutions:

Fix ownership:

# Stop container
docker-compose down

# Fix ownership (match PUID/PGID in docker-compose)
chown -R 1000:1000 /opt/filebrowser/data

# Fix permissions
chmod -R 755 /opt/filebrowser/data

# Restart
docker-compose up -d

Verify PUID/PGID:

environment:
  - PUID=1000  # Should match your user's ID
  - PGID=1000  # Should match your user's group ID

Check your user ID:

id
# Output: uid=1000(username) gid=1000(username) ...

Issue 3: Database Locked

Symptoms:

Error: “database is locked”
Cannot save settings

Solution:

# Stop container
docker-compose down

# Check for lock file
ls -la /opt/filebrowser/config/

# Remove lock file if exists
rm /opt/filebrowser/config/filebrowser.db-shm
rm /opt/filebrowser/config/filebrowser.db-wal

# Restart
docker-compose up -d

Issue 4: High Memory Usage

Symptoms:

Container using excessive RAM
System slowdown when uploading large files

Solutions:

Add resource limits:

deploy:
  resources:
    limits:
      cpus: '1'
      memory: 512M

Tune upload handling: Use reverse proxy buffering to handle large uploads:

Nginx:

client_body_buffer_size 128k;
client_max_body_size 100M;

Issue 5: Shares Not Working

Symptoms:

Share links return 404
Password-protected shares fail

Diagnostics:

# Check share configuration
docker exec filebrowser filebrowser config show | grep sharing

# Verify database
docker exec filebrowser sqlite3 /database/filebrowser.db "SELECT * FROM shares;"

Solutions:

Enable sharing:

docker exec filebrowser filebrowser config set --sharing.enabled=true

Check user permissions: Ensure user has “share” permission enabled.

Advanced Usage

WebDAV Access

FileBrowser doesn’t provide built-in WebDAV, but you can mount it via other methods:

Option 1: Use separate WebDAV server pointing to same directory

services:
  webdav:
    image: bytemark/webdav
    restart: unless-stopped
    ports:
      - "8081:80"
    volumes:
      - /opt/filebrowser/data:/var/lib/dav
    environment:
      - AUTH_TYPE=Basic
      - USERNAME=davuser
      - PASSWORD=secure-password

Option 2: SSHFS mounting

# From client machine
sshfs user@server:/opt/filebrowser/data /mnt/filebrowser

API Usage

FileBrowser provides a REST API for automation:

Authentication:

# Get auth token
curl -X POST http://YOUR-SERVER-IP:8080/api/login   -H "Content-Type: application/json"   -d '{"username": "admin", "password": "your-password"}'

# Returns: {"token": "your-jwt-token"}

Upload file via API:

TOKEN="your-jwt-token"

curl -X POST http://YOUR-SERVER-IP:8080/api/resources/path/to/file.txt   -H "X-Auth: $TOKEN"   --data-binary @local-file.txt

List files:

curl -X GET http://YOUR-SERVER-IP:8080/api/resources/path/to/directory   -H "X-Auth: $TOKEN"

Integration with External Services

Rclone integration for cloud backup:

# Install rclone in a separate container or on host
rclone sync /opt/filebrowser/data remote:backup/filebrowser   --exclude "*.tmp"   --exclude ".DS_Store"

Monitoring with Uptime Kuma:

Add HTTP(s) monitor pointing to FileBrowser URL to track uptime.

Performance Optimization

Caching Static Assets

Use reverse proxy caching for better performance:

Nginx:

location ~* .(jpg|jpeg|png|gif|ico|css|js|woff|woff2)$ {
    expires 30d;
    add_header Cache-Control "public, immutable";
}

Database Optimization

For very large file structures:

# Compact database
docker exec filebrowser sqlite3 /database/filebrowser.db "VACUUM;"

Resource Allocation

For high-traffic deployments:

deploy:
  resources:
    limits:
      cpus: '2'
      memory: 1G
    reservations:
      cpus: '1'
      memory: 512M

Alternatives and Comparisons

FileBrowser vs. Nextcloud

Feature	FileBrowser	Nextcloud
Resource Usage	Very Low (50-100 MB)	High (512 MB+)
Setup Complexity	Simple	Moderate to Complex
Features	File management only	Full suite (calendar, contacts, etc.)
Database	SQLite	MySQL/PostgreSQL required
Best For	Simple file access	Complete collaboration platform

FileBrowser vs. File Browser Alternatives

Similar projects:

Tiny File Manager: Single PHP file, even lighter
DirectoryLister: Simple directory browsing, no auth
H5ai: Stylish directory listings
Pydio Cells: More features, higher complexity

FileBrowser advantages:

Clean, modern UI
Built-in authentication
Docker-friendly
Active development

Conclusion

You now have a fully functional FileBrowser deployment providing web-based file management for your homelab.

Key Takeaways:

Lightweight: Minimal resource requirements, perfect for any homelab
Flexible: Multiple users, custom permissions, various storage options
Secure: Proper authentication, HTTPS support, permission controls
Accessible: Web interface works on any device with a browser
Simple: Focus on file management without unnecessary complexity

Next Steps:

Set up HTTPS via reverse proxy for secure remote access
Create user accounts for family members or team
Configure automated backups of your FileBrowser database
Explore custom commands for file processing
Integrate with your existing homelab services

Related Guides:

Traefik Reverse Proxy: Secure Your Homelab Services
Nextcloud: Full-Featured Cloud Storage Alternative
Syncthing: Peer-to-Peer File Synchronization

Welcome to simplified, self-hosted file management!

Guide Version: 1.0 Last Updated: January 15, 2025 Tested With: FileBrowser v2.27.0 Estimated Read Time: 25-30 minutes Estimated Implementation Time: 30 minutes

Part of the homelabbing.io File Sharing & Transfer series

Overview

Prerequisites

Understanding FileBrowser

Core Features

Architecture Overview

Installation and Deployment

Method 1: Docker Compose (Recommended)

Method 2: Docker with Custom Configuration

Initial Configuration

Change Default Credentials

Configure Basic Settings

User Management

Creating Users

User Permission Strategies

Managing User Directories

File Sharing and Links

Creating Share Links

Share Link Security

Advanced Sharing Configuration

Storage Configuration

Mounting Additional Directories

File Upload Limits

File Type Restrictions

Reverse Proxy Integration

Traefik Configuration

Nginx Proxy Manager Configuration

Caddy Configuration

Cloudflare Tunnel

Customization

Custom Branding

Custom Commands

Language and Locale

Security Hardening

Authentication Best Practices

HTTPS/TLS Configuration

Firewall Rules

File System Permissions

Backup and Restore

Backup FileBrowser Configuration

Restore from Backup

Troubleshooting

Issue 1: Cannot Access FileBrowser

Issue 2: Permission Denied Errors

Issue 3: Database Locked

Issue 4: High Memory Usage

Issue 5: Shares Not Working

Advanced Usage

WebDAV Access

API Usage

Integration with External Services

Performance Optimization

Caching Static Assets

Database Optimization

Resource Allocation

Alternatives and Comparisons

FileBrowser vs. Nextcloud

FileBrowser vs. File Browser Alternatives

Conclusion