Why Start a Blog?​

After years of documenting various self-hosting solutions and Docker configurations, I realized that some content doesn't quite fit the documentation format. Sometimes you want to:

• Share thoughts and opinions on new tools and technologies
• Discuss trends in the self-hosting community
• Provide quick tips that don't warrant a full tutorial
• Announce updates to the documentation site
• Document my homelab journey and lessons learned

What to Expect​

Here's what you can look forward to in future posts:

Technical Deep-Dives​

Detailed explorations of specific technologies, comparing different approaches, and sharing real-world experiences running services in production.

Quick Tips & Tricks​

Short, actionable tips that can improve your homelab setup without requiring a full tutorial read.

News & Updates​

Announcements about new documentation, major updates to tools we cover, and community news.

Homelab Stories​

Real experiences from running a homelab - the wins, the fails, and everything in between.

Join the Community​

If you're interested in self-hosting and homelabs, make sure to:

• Join our Discord server for real-time discussions
• Check out the documentation for detailed tutorials
• Consider buying me a beer if you find this content helpful

Thanks for reading, and stay tuned for more content!

What topics would you like to see covered? Drop a message in Discord!

1. Always Pin Your Image Versions​

# ❌ Don't do this
services:
  postgres:
    image: postgres:latest

# ✅ Do this instead
services:
  postgres:
    image: postgres:16.2-alpine

Using latest might seem convenient, but it can lead to unexpected breaking changes when images update. Always pin to specific versions and update intentionally.

2. Use Environment Files​

Keep your secrets and configuration out of your compose files:

services:
  app:
    image: myapp:1.0.0
    env_file:
      - .env
      - .env.local

Create a .env.example file to document required variables:

# .env.example
DATABASE_URL=
REDIS_URL=
SECRET_KEY=

3. Implement Health Checks​

Don't assume your container is healthy just because it started:

services:
  web:
    image: nginx:1.25-alpine
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s

4. Set Resource Limits​

Prevent runaway containers from consuming all available resources:

services:
  app:
    image: myapp:1.0.0
    deploy:
      resources:
        limits:
          cpus: '2.0'
          memory: 2G
        reservations:
          cpus: '0.5'
          memory: 512M

5. Use Named Volumes for Persistent Data​

services:
  database:
    image: postgres:16.2-alpine
    volumes:
      - postgres_data:/var/lib/postgresql/data

volumes:
  postgres_data:
    name: myapp_postgres_data

Named volumes are easier to manage, backup, and migrate than bind mounts for database storage.

6. Organize with Networks​

Separate your services into logical networks:

services:
  frontend:
    networks:
      - frontend

  api:
    networks:
      - frontend
      - backend

  database:
    networks:
      - backend

networks:
  frontend:
  backend:

This limits which services can communicate with each other, improving security.

7. Use Depends On with Conditions​

services:
  api:
    depends_on:
      database:
        condition: service_healthy
      redis:
        condition: service_started

This ensures your services start in the correct order and wait for dependencies to be ready.

Wrapping Up​

These practices have saved me countless hours of debugging and made my homelab much more reliable. Start implementing them one at a time, and you'll notice the difference.

Have your own best practices? Share them in our Discord!

Next up: A deep dive into Docker networking and troubleshooting common issues.

1. Follow Container Logs with Timestamps​

docker logs -f --timestamps container_name

The -f flag follows the log output (like tail -f), and --timestamps adds timestamps to each line. Essential for correlating events across multiple containers.

Pro tip: Limit output with --tail:

docker logs -f --tail 100 container_name

2. Get a Shell in a Running Container​

docker exec -it container_name /bin/sh

If /bin/sh doesn't work (minimal containers), try /bin/bash or ash. This lets you poke around inside the container to debug issues.

For containers that don't have a shell at all:

docker run -it --rm --pid=container:container_name --net=container:container_name alpine sh

3. Inspect Container Details​

docker inspect container_name | jq '.[0].NetworkSettings.Networks'

Combined with jq, you can extract exactly what you need. Common queries:

# Get IP address
docker inspect -f '{{range.NetworkSettings.Networks}}{{.IPAddress}}{{end}}' container_name

# Get mounted volumes
docker inspect -f '{{range .Mounts}}{{.Source}} -> {{.Destination}}{{"\n"}}{{end}}' container_name

# Get environment variables
docker inspect -f '{{range .Config.Env}}{{println .}}{{end}}' container_name

4. Check Resource Usage​

docker stats --no-stream

Shows CPU, memory, network, and disk I/O for all running containers. The --no-stream flag gives you a snapshot instead of real-time updates.

For a specific container with more details:

docker stats container_name

5. Clean Up Docker System​

# Remove unused containers, networks, images, and optionally volumes
docker system prune -a

# See what's using disk space
docker system df

# Nuclear option - reclaim ALL space (careful!)
docker system prune -a --volumes

Bonus: Docker Compose Specific​

# Rebuild a single service without cache
docker compose build --no-cache service_name

# View logs for all services
docker compose logs -f

# Restart a single service
docker compose restart service_name

# See running containers in a compose project
docker compose ps

What are your go-to Docker troubleshooting commands? Share them in Discord!

The Problem: Everything on One Host​

My original setup was simple but fragile:

• Docker containers running directly on the host OS
• No isolation between services
• One kernel panic = entire homelab down
• Updates were terrifying
• No easy way to snapshot or rollback

It worked, but it wasn't sustainable.

Why Virtualization?​

Moving to a hypervisor provides:

• Isolation - Problems in one VM don't affect others
• Snapshots - Test changes safely, rollback instantly
• Resource management - Allocate CPU/RAM per workload
• Flexibility - Run different OSes side by side
• Better backups - Backup entire VMs easily

Options I Considered​

VMware ESXi​

The enterprise standard, but in 2023 Broadcom acquired VMware and discontinued the free ESXi hypervisor. Even before that, the free tier had limitations that made it less appealing for homelabs.

Proxmox VE​

Open source, free, and actively developed. Supports both VMs and LXC containers. This is what I went with.

Other Options​

• Hyper-V - Windows-only, still need a Windows license
• XCP-ng - Solid option, but smaller community
• Unraid - Great for storage-focused builds

Why Proxmox Won​

1. It's Truly Free (and Open Source)​

Proxmox VE is free to use without artificial limitations. The paid subscription gets you enterprise support and access to the stable repository, but the free tier is fully functional.

2. Built-in Container Support​

Proxmox supports both VMs and LXC containers out of the box. Running lightweight services in containers instead of full VMs saves significant resources.

# Create a container from template
pct create 100 local:vztmpl/ubuntu-22.04-standard_22.04-1_amd64.tar.zst \
  -hostname mycontainer \
  -memory 2048 \
  -cores 2 \
  -rootfs local-lvm:8

3. Web-Based Management​

The Proxmox web UI is modern and capable. No need for special client software—just a browser.

4. Excellent ZFS Integration​

Native ZFS support means I can create pools, snapshots, and replications directly from the UI.

5. Clustering is Free​

Want to cluster multiple nodes? It's included. No additional licensing required.

My Setup Now​

After migrating to Proxmox:

• Separate VMs for different workloads (media, networking, development)
• LXC containers for lightweight services
• Snapshots before updates - no more fear
• Easy backups to NAS storage
• GPU passthrough to a dedicated VM

The difference is night and day. I can experiment freely knowing I can roll back in seconds.

Getting Started​

If you're still running everything on bare metal, consider making the switch. Check out my Proxmox installation guide for a step-by-step walkthrough.

Still running everything on a single host? Made the switch to virtualization? Share your experience on Discord!

The Numbers​

Let's start with some stats from this year:

• 40+ containers running daily
• 99.7% uptime (excluding planned maintenance)
• 150TB of data managed
• 3 major outages (all self-inflicted 😅)
• 0 security incidents

Major Additions​

Jellyfin Migration​

Finally made the switch from Plex to Jellyfin. The reasons:

1. No account required for local streaming
2. Hardware transcoding works great without a subscription
3. Open source = no surprise feature removals
4. Active community development

The migration was smoother than expected. All my users adjusted within a week.

Arr Stack Overhaul​

Rebuilt my entire Arr stack from scratch using the full stack guide. Key improvements:

• Moved to hardlinks for storage efficiency
• Implemented proper folder structure
• Set up cross-seed for ratio maintenance

Network Upgrade​

Upgraded my network infrastructure:

• Replaced my aging Netgear Router with a UDM Pro paired with some Unifi APs
• Added 10GbE between Gateway | NVR | Switch
• Implemented proper VLANs (finally!)
• Upgraded Internet plan to 2GB/1GB Fiber Optic

What Didn't Work​

Automated Everything​

Tried to automate too much, too fast. Spent more time fixing automation than it would have taken to just do things manually. Lesson learned: automate incrementally.

Lessons Learned​

1. Backups are mandatory - Lost the majority of our family pictures when a drive failed. Now running syncthing backup strategy to all owned PCs/Laptops for multiple backups.

2. Document as you go - Future you will thank present you.

3. Start simple - The fancy solution isn't always the right solution.

4. The community is helpful - Don't be afraid to ask questions. Everyone was a beginner once.

Plans for 2026​

Here's what's on the roadmap:

• Set up proper monitoring with Grafana/Prometheus
• Implement GitOps for configuration management
• Build a dedicated backup server
• Write more documentation and blog posts!

Thank You​

Thanks to everyone who's used this documentation, joined the Discord, or just stopped by. Building this community has been one of the highlights of my year.

Here's to more uptime, fewer 3 AM debugging sessions, and continued learning in 2026!

What were your homelab highlights of 2025? Share them in the Discord!

Why MariaDB?​

MariaDB is the community-developed fork of MySQL, offering:

• Open source - Truly free, no licensing concerns
• MySQL compatible - Drop-in replacement
• Active development - Regular security updates
• Performance - Often faster than MySQL
• Docker ready - Official images available

Basic Docker Setup​

services:
  mariadb:
    image: mariadb:10.11
    container_name: mariadb
    restart: unless-stopped
    environment:
      - MYSQL_ROOT_PASSWORD=${DB_ROOT_PASSWORD}
      - MYSQL_DATABASE=myapp
      - MYSQL_USER=myuser
      - MYSQL_PASSWORD=${DB_PASSWORD}
    volumes:
      - mariadb_data:/var/lib/mysql
    ports:
      - "3306:3306"

volumes:
  mariadb_data:

Backup Strategies​

Method 1: mysqldump​

Best for small/medium databases:

# Backup
docker exec mariadb mysqldump -u root -p${DB_ROOT_PASSWORD} --all-databases > backup.sql

# Single database
docker exec mariadb mysqldump -u root -p${DB_ROOT_PASSWORD} mydatabase > mydatabase.sql

Method 2: Volume Backup​

Best for large databases:

# Stop container first!
docker stop mariadb

# Backup volume
docker run --rm \
  -v mariadb_data:/data:ro \
  -v $(pwd):/backup \
  alpine tar czf /backup/mariadb-data.tar.gz /data

# Restart
docker start mariadb

Method 3: Automated Backups​

services:
  mariadb-backup:
    image: databack/mysql-backup
    container_name: mariadb-backup
    environment:
      - DB_SERVER=mariadb
      - DB_USER=root
      - DB_PASS=${DB_ROOT_PASSWORD}
      - DB_DUMP_TARGET=/backup
      - DB_DUMP_FREQ=1440  # Daily
      - DB_DUMP_BEGIN=0300 # 3 AM
    volumes:
      - ./backups:/backup
    depends_on:
      - mariadb

Updating MariaDB​

Minor Updates (10.11.x)​

Safe and usually painless:

# Update image
docker compose pull mariadb

# Recreate container
docker compose up -d mariadb

Major Updates (10.x → 11.x)​

Always backup first!

# 1. Backup everything
docker exec mariadb mysqldump -u root -p --all-databases > pre-upgrade.sql

# 2. Stop container
docker compose stop mariadb

# 3. Update compose file version
# image: mariadb:10.11  →  image: mariadb:11.2

# 4. Start new version
docker compose up -d mariadb

# 5. Run upgrade script
docker exec mariadb mysql_upgrade -u root -p

mysql_upgrade Explained​

After major version upgrades, run:

docker exec -it mariadb mysql_upgrade -u root -p

This:

• Upgrades system tables
• Checks all tables
• Fixes compatibility issues

Restoring from Backup​

From mysqldump​

# Restore all databases
docker exec -i mariadb mysql -u root -p${DB_ROOT_PASSWORD} < backup.sql

# Restore single database
docker exec -i mariadb mysql -u root -p${DB_ROOT_PASSWORD} mydatabase < mydatabase.sql

From Volume Backup​

# Stop container
docker stop mariadb

# Remove old volume
docker volume rm mariadb_data

# Restore volume
docker run --rm \
  -v mariadb_data:/data \
  -v $(pwd):/backup \
  alpine tar xzf /backup/mariadb-data.tar.gz -C /

# Start container
docker start mariadb

Performance Tuning​

Basic Tuning​

[mysqld]
innodb_buffer_pool_size = 1G
innodb_log_file_size = 256M
innodb_flush_log_at_trx_commit = 2
max_connections = 200
query_cache_size = 0
query_cache_type = 0

Mount config file:

volumes:
  - ./custom.cnf:/etc/mysql/conf.d/custom.cnf:ro

Monitoring​

# Check status
docker exec mariadb mysqladmin -u root -p status

# Show processes
docker exec mariadb mysqladmin -u root -p processlist

# Interactive monitor
docker exec -it mariadb mysql -u root -p -e "SHOW FULL PROCESSLIST;"

Common Issues​

Container Won't Start​

# Check logs
docker logs mariadb

# Common: permissions issue
docker run --rm -v mariadb_data:/data alpine chown -R 999:999 /data

Can't Connect​

# Check if running
docker ps | grep mariadb

# Test connection
docker exec mariadb mysqladmin -u root -p ping

Forgot Root Password​

# Stop container
docker stop mariadb

# Start with skip-grant-tables
docker run -it --rm \
  -v mariadb_data:/var/lib/mysql \
  mariadb:10.11 \
  --skip-grant-tables --user=mysql

# In another terminal, reset password
docker exec -it container_id mysql
# mysql> FLUSH PRIVILEGES;
# mysql> ALTER USER 'root'@'localhost' IDENTIFIED BY 'newpassword';

Health Checks​

Add to compose:

services:
  mariadb:
    healthcheck:
      test: ["CMD", "mysqladmin", "ping", "-h", "localhost", "-u", "root", "-p${DB_ROOT_PASSWORD}"]
      interval: 30s
      timeout: 10s
      retries: 3

Learn More​

• MariaDB Update Guide
• Nextcloud Database Setup

Database tips to share? Post them on Discord!

What is KMS?​

Key Management Service (KMS) is Microsoft's volume activation technology used by enterprises. Instead of each machine calling Microsoft, they call a local KMS server.

Important Legal Notes​

• KMS is intended for volume licensing customers
• Using this for personal/testing in your homelab is a gray area
• Never use this for production systems you don't have licenses for
• Consider Microsoft 365 Developer Program for legitimate free licenses

Setting Up a KMS Server​

We'll use vlmcsd, an open-source KMS emulator:

services:
  kms:
    image: mikolatero/vlmcsd
    container_name: kms-server
    ports:
      - "1688:1688"
    restart: unless-stopped

Start it:

docker compose up -d

Your KMS server is now running on port 1688.

Activating Windows​

Step 1: Set KMS Server​

Open Command Prompt as Administrator:

slmgr /skms YOUR-KMS-SERVER-IP

Step 2: Install Generic Volume License Key​

Use Microsoft's official GVLK keys:

Windows 11/10 Pro:

slmgr /ipk W269N-WFGWX-YVC9B-4J6C9-T83GX

Windows 11/10 Enterprise:

slmgr /ipk NPPR9-FWDCX-D2C8J-H872K-2YT43

Windows Server 2022 Standard:

slmgr /ipk VDYBN-27WPP-V4HQT-9VMD4-VMK7H

Step 3: Activate​

slmgr /ato

Verify Activation​

slmgr /xpr

Should show "The machine is permanently activated" (or 180 days for volume).

Activating Microsoft Office​

Step 1: Navigate to Office Directory​

For Office 2021/2019:

cd "C:\Program Files\Microsoft Office\Office16"

Or for 32-bit on 64-bit Windows:

cd "C:\Program Files (x86)\Microsoft Office\Office16"

Step 2: Set KMS Server​

cscript ospp.vbs /sethst:YOUR-KMS-SERVER-IP
cscript ospp.vbs /setprt:1688

Step 3: Activate​

cscript ospp.vbs /act

Verify Status​

cscript ospp.vbs /dstatus

Office GVLK Keys​

Office 2021 Pro Plus:

FXYTK-NJJ8C-GB6DW-3DYQT-6F7TH

Office 2019 Pro Plus:

NMMKJ-6RK4F-KMJVX-8D9MJ-6MWKP

Upgrading Windows Editions​

Did you know you can upgrade Windows editions with just a key?

From Home to Pro​

# Check current edition
DISM /Online /Get-CurrentEdition

# Change product key to upgrade
changepk.exe /productkey W269N-WFGWX-YVC9B-4J6C9-T83GX

# Then activate via KMS
slmgr /ato

No reinstall needed!

Troubleshooting​

Error 0xC004F074​

"The Software Licensing Service reported that the computer could not be activated."

• Verify KMS server is reachable: telnet KMS-IP 1688
• Check firewall allows port 1688
• Verify correct GVLK is installed

Error 0x8007232B​

"DNS name does not exist."

• Ensure you set KMS server IP, not hostname
• Use /skms to set server address manually

Office Won't Activate​

• Verify you're using Volume License version, not Retail
• Check ospp.vbs path is correct
• Run Command Prompt as Administrator

Alternative: Microsoft 365 Developer Program​

For legitimate free access:

1. Sign up at developer.microsoft.com
2. Get 90-day renewable subscription
3. Includes Windows, Office, and more
4. Perfect for development/testing

Learn More​

• KMS Server Setup
• Activating Windows
• Activating Office
• Upgrading Windows Edition

Running Windows in your homelab? Share your setup on Discord!

What's in the Arr Suite?​

The "Arr" applications handle different media types:

The Media Flow​

Here's how everything connects:

1. User requests media through Seerr
2. Request goes to Radarr/Sonarr
3. Arr app queries indexers via Prowlarr
4. Best release is sent to qBittorrent
5. Completed download is imported and renamed
6. Jellyfin picks up the new media

Docker Compose Setup​

Here's a simplified version of our full stack:

services:
  radarr:
    image: lscr.io/linuxserver/radarr:latest
    container_name: radarr
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=America/New_York
    volumes:
      - radarr_config:/config
      - /data:/data
    ports:
      - "7878:7878"
    restart: unless-stopped

  sonarr:
    image: lscr.io/linuxserver/sonarr:latest
    container_name: sonarr
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=America/New_York
    volumes:
      - sonarr_config:/config
      - /data:/data
    ports:
      - "8989:8989"
    restart: unless-stopped

  prowlarr:
    image: lscr.io/linuxserver/prowlarr:latest
    container_name: prowlarr
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=America/New_York
    volumes:
      - prowlarr_config:/config
    ports:
      - "9696:9696"
    restart: unless-stopped

  seerr:
    image: ghcr.io/seerr-team/seerr:latest
    container_name: seerr
    init: true
    environment:
      - TZ=America/New_York
    volumes:
      - seerr_data:/app/config
    ports:
      - "5055:5055"
    healthcheck:
      test: wget --no-verbose --tries=1 --spider http://localhost:5055/api/v1/status || exit 1
      start_period: 20s
      timeout: 3s
      interval: 15s
      retries: 3
    restart: unless-stopped

  qbittorrent:
    image: lscr.io/linuxserver/qbittorrent:latest
    container_name: qbittorrent
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=America/New_York
      - WEBUI_PORT=8080
    volumes:
      - qbit_config:/config
      - /data/downloads:/data/downloads
    ports:
      - "8080:8080"
    restart: unless-stopped

volumes:
  radarr_config:
  sonarr_config:
  prowlarr_config:
  seerr_data:
  qbit_config:

Critical: Folder Structure​

This is where most people go wrong. Use a unified structure:

Why this matters: When Radarr/Sonarr imports a download, it can create a hardlink instead of copying. Same file, two paths, instant import with zero disk space used.

VPN Integration​

Use the binhex/qbittorrentvpn image for built-in VPN:

qbittorrent:
  image: binhex/arch-qbittorrentvpn
  environment:
    - VPN_ENABLED=yes
    - VPN_PROV=custom
    - VPN_CLIENT=openvpn

Quality Profiles​

Configure quality profiles in Radarr/Sonarr:

Recommended for movies:

• Minimum: 5GB
• Preferred: 10-15GB
• Maximum: 40GB
• Format: Bluray-2160p > Bluray-1080p > WEB-DL

Recommended for TV:

• Minimum: 1GB per episode
• Preferred: 2-4GB per episode
• Format: HDTV-2160p > Bluray-1080p > WEB-DL

Recyclarr for Automation​

Use Recyclarr to sync quality profiles from TRaSH Guides:

docker run --rm -v recyclarr_config:/config ghcr.io/recyclarr/recyclarr sync

This keeps your profiles up-to-date with community best practices.

Flaresolverr for Cloudflare​

Some indexers use Cloudflare protection. Add Flaresolverr:

flaresolverr:
  image: ghcr.io/flaresolverr/flaresolverr:latest
  container_name: flaresolverr
  environment:
    - TZ=America/New_York
  ports:
    - "8191:8191"
  restart: unless-stopped

Configure in Prowlarr under Settings → Indexers → Add (FlareSolverr).

Learn More​

For the complete production-ready setup:

• Full Stack Docker Compose
• Radarr Configuration
• VPN Setup with qBittorrent

What does your Arr stack look like? Share your setup on Discord!

What Does a Reverse Proxy Do?​

Instead of accessing services by port numbers:

• http://192.168.1.100:8096 (Jellyfin)
• http://192.168.1.100:8989 (Sonarr)
• http://192.168.1.100:7878 (Radarr)

You get clean URLs with SSL:

• https://jellyfin.home.yourdomain.com
• https://sonarr.home.yourdomain.com
• https://radarr.home.yourdomain.com

Benefits:​

• SSL everywhere - Encrypt all traffic
• Single entry point - One port to expose (443)
• Subdomain routing - Clean URLs for each service
• Load balancing - Distribute traffic (for HA setups)
• Caching - Improve performance for static content

Network Architecture​

Installing Nginx on Ubuntu​

# Install Nginx
sudo apt update
sudo apt install -y nginx

# Enable and start
sudo systemctl enable nginx
sudo systemctl start nginx

# Verify
sudo nginx -t

Basic Configuration Structure​

Nginx configuration files:

SSL with Certbot (Let's Encrypt)​

First, install Certbot:

sudo apt install -y certbot python3-certbot-nginx

Get certificates for your domains:

sudo certbot --nginx -d jellyfin.yourdomain.com

Certbot will:

1. Validate domain ownership
2. Generate certificates
3. Configure Nginx automatically
4. Set up auto-renewal

Reverse Proxy Configuration​

Here's a template for any service:

server {
    listen 80;
    server_name service.yourdomain.com;
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl http2;
    server_name service.yourdomain.com;

    # SSL certificates (managed by Certbot)
    ssl_certificate /etc/letsencrypt/live/service.yourdomain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/service.yourdomain.com/privkey.pem;

    # SSL settings
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256;
    ssl_prefer_server_ciphers off;

    # Security headers
    add_header X-Frame-Options "SAMEORIGIN" always;
    add_header X-Content-Type-Options "nosniff" always;
    add_header X-XSS-Protection "1; mode=block" always;

    location / {
        proxy_pass http://127.0.0.1:8096;  # Internal service port
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

Enable the site:

sudo ln -s /etc/nginx/sites-available/service.conf /etc/nginx/sites-enabled/
sudo nginx -t && sudo systemctl reload nginx

Jellyfin Specific Configuration​

Jellyfin needs WebSocket support for live transcoding:

server {
    listen 443 ssl http2;
    server_name jellyfin.yourdomain.com;

    ssl_certificate /etc/letsencrypt/live/jellyfin.yourdomain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/jellyfin.yourdomain.com/privkey.pem;

    # Large file uploads for libraries
    client_max_body_size 20M;

    location / {
        proxy_pass http://127.0.0.1:8096;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        # WebSocket support
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }

    location /socket {
        proxy_pass http://127.0.0.1:8096;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

Cloudflare Integration​

If using Cloudflare for DNS:

1. Set SSL mode to "Full (Strict)"
2. Add Cloudflare real IP restoration:

# /etc/nginx/conf.d/cloudflare.conf
set_real_ip_from 103.21.244.0/22;
set_real_ip_from 103.22.200.0/22;
# ... add all Cloudflare IP ranges
real_ip_header CF-Connecting-IP;

Troubleshooting​

502 Bad Gateway​

• Check if backend service is running
• Verify proxy_pass URL is correct
• Check firewall rules

SSL Certificate Issues​

sudo certbot renew --dry-run

View Access Logs​

sudo tail -f /var/log/nginx/access.log

Learn More​

• Complete Nginx Documentation
• Certbot with Cloudflare
• Example Nginx Configs

Running a different reverse proxy? Share your setup on Discord!

Why Jellyfin?​

After years of Plex, several changes pushed me to explore alternatives:

• No account required - Works entirely locally
• Free hardware transcoding - No Plex Pass needed
• Truly open source - GPL licensed, community driven
• No phone-home - Your server, your rules
• Active development - Regular updates and improvements

Jellyfin vs Plex vs Emby​

Docker Installation​

Here's a production-ready compose file:

services:
  jellyfin:
    image: jellyfin/jellyfin:latest
    container_name: jellyfin
    restart: unless-stopped
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=America/New_York
    volumes:
      - jellyfin_config:/config
      - jellyfin_cache:/cache
      - /path/to/media/movies:/data/movies:ro
      - /path/to/media/tv:/data/tv:ro
      - /path/to/media/music:/data/music:ro
    ports:
      - "8096:8096"
    devices:
      - /dev/dri:/dev/dri # For Intel QuickSync

volumes:
  jellyfin_config:
  jellyfin_cache:

Hardware Transcoding​

For Intel QuickSync (most common):

1. Ensure your user has access to render group:

sudo usermod -aG render $USER

2. The /dev/dri device mapping in compose handles the rest

3. In Jellyfin Dashboard → Playback → Transcoding:

   • Select "Intel QuickSync (QSV)"
   • Enable hardware decoding for supported codecs

Folder Structure​

Organize your media properly:

TinyMediaManager Integration​

For the best metadata management, use TinyMediaManager:

1. Point TMM at your media folders
2. Scrape metadata from TMDB/TVDB
3. Download artwork and NFO files
4. Then add to Jellyfin

The workflow is: TMM First, Then Jellyfin

This gives you:

• Better metadata accuracy
• More artwork options
• Bulk editing capabilities
• NFO files for backup/portability

Plugins Worth Installing​

From the official repository:

• Intro Skipper - Auto-skip intros (like Plex Pass)
• Open Subtitles - Auto-download subtitles
• Playback Reporting - Track your watch history
• TMDb Box Sets - Better collection handling
• ConfusedPolarBear.Plugin.Intro - Chapter generation

Client Apps​

Jellyfin has clients for everything:

• Web - Built-in, works great
• Android/iOS - Official apps
• Android TV - Native app
• Roku - Native app
• Kodi - Jellyfin for Kodi plugin
• Desktop - Jellyfin Media Player

Migration from Plex​

If you're coming from Plex:

1. Export your watch history (there are community scripts)
2. Set up Jellyfin with the same library structure
3. Import watch history to Jellyfin
4. Update your DNS/reverse proxy
5. Install clients on your devices

The hardest part is updating all your devices, but it's worth it.

My Setup​

Currently running:

• Jellyfin in Docker behind Nginx reverse proxy
• NVIDIA NVENC for transcoding
• 100TB+ library with movies, TV, and music
• Arr stack for automated acquisition
• TinyMediaManager for metadata

Learn More​

For complete setup guides:

• Jellyfin Docker Installation
• TinyMediaManager Integration
• Arr Stack Setup

Made the switch to Jellyfin? Share your experience on Discord!

What is Tailscale?​

Tailscale is a mesh VPN built on WireGuard that:

• Requires zero configuration - No port forwarding needed
• Punches through NAT - Works behind any router
• Encrypts everything - WireGuard-based security
• Creates a mesh - Devices connect directly
• Free for personal use - Up to 100 devices

How It Works​

1. Devices register with Tailscale's coordination server
2. Coordination server helps devices find each other
3. Actual traffic flows directly between devices (peer-to-peer)
4. All traffic is encrypted with WireGuard

Installation​

On Ubuntu/Debian​

# Add Tailscale repository
curl -fsSL https://tailscale.com/install.sh | sh

# Start Tailscale
sudo tailscale up

# Follow the authentication URL

On Docker​

services:
  tailscale:
    image: tailscale/tailscale:latest
    container_name: tailscale
    hostname: docker-host
    environment:
      - TS_AUTHKEY=tskey-auth-xxxxx  # From Tailscale admin console
      - TS_STATE_DIR=/var/lib/tailscale
      - TS_EXTRA_ARGS=--advertise-exit-node --advertise-routes=192.168.1.0/24
    volumes:
      - tailscale_data:/var/lib/tailscale
      - /dev/net/tun:/dev/net/tun
    cap_add:
      - NET_ADMIN
      - SYS_MODULE
    restart: unless-stopped

volumes:
  tailscale_data:

Subnet Router (Access Entire Network)​

The killer feature for homelabs: subnet routing. Access your entire LAN through Tailscale.

# On your homelab server
sudo tailscale up --advertise-routes=192.168.1.0/24 --accept-routes

Then in the Tailscale admin console:

1. Go to Machines
2. Find your server
3. Enable the route under "Subnets"

Now your phone can access 192.168.1.100:7878 (Radarr) from anywhere!

Exit Node (Route All Traffic)​

Use your homelab as a VPN exit point:

sudo tailscale up --advertise-exit-node

Enable in admin console, then on your mobile device:

1. Open Tailscale
2. Select your homelab as exit node
3. All traffic now routes through home

Great for:

• Accessing geo-restricted content
• Secure browsing on public WiFi
• Appearing to be "at home"

MagicDNS​

Tailscale provides automatic DNS for all your devices:

• homelab.tail12345.ts.net
• laptop.tail12345.ts.net
• phone.tail12345.ts.net

Enable in admin console under DNS settings.

Funnel (Public Endpoints)​

Need to expose a service publicly without port forwarding?

# Share a local service publicly
tailscale funnel 443 --bg

Your service becomes available at https://machine-name.tail12345.ts.net.

ACLs (Access Control)​

Control who can access what:

{
  "acls": [
    // Family can access Jellyfin
    {"action": "accept", "users": ["family"], "ports": ["homelab:8096"]},
    // Only admin can access management interfaces
    {"action": "accept", "users": ["admin@example.com"], "ports": ["homelab:*"]},
  ]
}

Tailscale vs Traditional VPN​

My Tailscale Setup​

Currently running:

• Homelab server - Subnet router + exit node
• Work laptop - Client
• Phone - Client with exit node for travel
• Parents' house - Subnet router (remote support!)

Common Use Cases​

1. Access Plex/Jellyfin remotely - No port forwarding
2. SSH to home server - Secure connection anywhere
3. Access home network cameras - Private surveillance
4. Remote support - Help family without TeamViewer
5. Development - Access home dev environment from anywhere

Learn More​

For the complete guide:

• Tailscale Full Documentation
• Networking Fundamentals

Using Tailscale differently? Share your setup on Discord!

Why VPN for Torrents?​

When torrenting:

• Your IP is visible to everyone in the swarm
• Your ISP can see your traffic
• Copyright trolls actively monitor popular torrents

A VPN:

• Hides your real IP
• Encrypts traffic from ISP
• Provides deniability

The Kill Switch Problem​

A regular VPN connection can drop without warning. If that happens, qBittorrent continues downloading with your real IP exposed.

Solution: Use a container that won't allow any traffic without VPN.

qBittorrent + VPN Docker Setup​

We use binhex's image which integrates OpenVPN/WireGuard:

services:
  qbittorrent:
    image: binhex/arch-qbittorrentvpn
    container_name: qbittorrent
    cap_add:
      - NET_ADMIN
    environment:
      - VPN_ENABLED=yes
      - VPN_PROV=custom
      - VPN_CLIENT=openvpn
      - ENABLE_PRIVOXY=no
      - LAN_NETWORK=192.168.1.0/24
      - NAME_SERVERS=1.1.1.1,8.8.8.8
      - PUID=1000
      - PGID=1000
      - WEBUI_PORT=8080
      - UMASK=022
      - TZ=America/New_York
    volumes:
      - qbit_config:/config
      - /path/to/downloads:/data/downloads
      - /path/to/vpn:/config/openvpn  # VPN config files
    ports:
      - "8080:8080"    # Web UI
      - "6881:6881"    # Torrent port (optional)
      - "6881:6881/udp"
    sysctls:
      - net.ipv4.conf.all.src_valid_mark=1
    restart: unless-stopped

volumes:
  qbit_config:

VPN Provider Setup​

NordVPN​

1. Download OpenVPN config from NordVPN
2. Place .ovpn file in /config/openvpn/
3. Create credentials file:

your_username
your_password

4. Update the .ovpn file to reference credentials:

auth-user-pass /config/openvpn/credentials.conf

ProtonVPN​

1. Download OpenVPN config from account dashboard
2. Note: Use OpenVPN credentials, not account password
3. Same process as NordVPN

Verifying the Kill Switch​

Test that the kill switch works:

# Get container's external IP
docker exec qbittorrent curl -s https://ipinfo.io/ip

# Stop VPN inside container (simulating failure)
docker exec qbittorrent pkill openvpn

# Try to get IP again - should fail
docker exec qbittorrent curl -s --max-time 5 https://ipinfo.io/ip
# No response = kill switch working!

DNS Leak Testing​

Even with VPN, DNS requests can leak. Test with:

1. Go to https://dnsleaktest.com from the container:

docker exec qbittorrent curl -s https://dnsleaktest.com/

2. Or check in qBittorrent's web UI if it shows your location

3. Use our DNS Leak Testing guide

Port Forwarding​

Some VPN providers support port forwarding for better speeds:

• Mullvad - Dynamically assigned ports
• AirVPN - Manual port selection
• Private Internet Access - Port in app settings

Configure in qBittorrent:

1. Settings → Connection
2. Set "Listening Port" to your forwarded port
3. Disable "Use UPnP / NAT-PMP"

Arr Stack Integration​

Connect qBittorrent to Radarr/Sonarr:

1. In Radarr: Settings → Download Clients → Add
2. Select qBittorrent
3. Host: qbittorrent (container name) or 192.168.1.x
4. Port: 8080
5. Username/Password from qBittorrent settings

Category Setup​

Create categories in qBittorrent:

• movies for Radarr
• tv for Sonarr
• music for Lidarr

Set save paths:

• /data/downloads/torrents/movies
• /data/downloads/torrents/tv

Troubleshooting​

VPN won't connect​

docker logs qbittorrent 2>&1 | grep -i vpn

Check credentials and config file paths.

Web UI not accessible​

Verify LAN_NETWORK matches your actual network.

Slow speeds​

• Try different VPN servers
• Enable port forwarding if available
• Check if ISP throttles VPN traffic

My Setup​

Currently using:

• Proton VPN
• OpenVPN protocol
• Port forwarding disabled
• Connected to Radarr, Sonarr, Lidarr

Learn More​

• qBittorrent VPN Deep Dive
• VPN Firewall Rules
• Arr Stack Setup

What VPN do you use for torrenting? Share on Discord!

What is Nextcloud?​

Nextcloud is a self-hosted productivity platform that provides:

• File storage and sync - Like Dropbox, but yours
• Calendar and contacts - Replace Google Calendar
• Collaborative editing - With Collabora or OnlyOffice
• Photo management - With the Memories app
• Video calls - Built-in Talk functionality
• And much more - Through a vast app ecosystem

Choosing Your Installation Method​

We support multiple installation approaches:

For most homelabbers, Docker (Complete) is the sweet spot.

The Complete Docker Stack​

Our recommended setup includes:

• Nextcloud - The main application
• MariaDB - Database backend
• Redis - Caching for performance
• Collabora - Document editing
• Cron - Background job processing

Here's a simplified version of the compose file:

services:
  nextcloud:
    image: nextcloud:production
    container_name: nextcloud
    restart: unless-stopped
    depends_on:
      - mariadb
      - redis
    ports:
      - "8080:80"
    environment:
      - MYSQL_HOST=mariadb
      - MYSQL_DATABASE=nextcloud
      - MYSQL_USER=nextcloud
      - MYSQL_PASSWORD=${DB_PASSWORD}
      - REDIS_HOST=redis
    volumes:
      - nextcloud_data:/var/www/html

  mariadb:
    image: mariadb:10.11
    container_name: nextcloud-db
    restart: unless-stopped
    environment:
      - MYSQL_ROOT_PASSWORD=${DB_ROOT_PASSWORD}
      - MYSQL_DATABASE=nextcloud
      - MYSQL_USER=nextcloud
      - MYSQL_PASSWORD=${DB_PASSWORD}
    volumes:
      - mariadb_data:/var/lib/mysql

  redis:
    image: redis:7-alpine
    container_name: nextcloud-redis
    restart: unless-stopped

volumes:
  nextcloud_data:
  mariadb_data:

Performance Optimization​

Enable Redis Caching​

Add to your Nextcloud config.php:

'memcache.local' => '\OC\Memcache\APCu',
'memcache.distributed' => '\OC\Memcache\Redis',
'memcache.locking' => '\OC\Memcache\Redis',
'redis' => [
    'host' => 'redis',
    'port' => 6379,
],

Background Jobs​

Ensure cron is running properly:

docker exec -u www-data nextcloud php cron.php

Or use our dedicated cron container in the full stack.

Photo Management with Memories​

The Memories app transforms Nextcloud into a Google Photos alternative:

1. Install Memories from the app store
2. Install go-vod for video transcoding
3. Configure the preview generator
4. Run initial indexing

docker exec -u www-data nextcloud php occ memories:index

Backup Strategy​

Critical: Always back up both your files AND your database!

# Database backup
docker exec nextcloud-db mysqldump -u root -p${DB_ROOT_PASSWORD} nextcloud > backup.sql

# Volume backup
docker run --rm -v nextcloud_data:/data -v $(pwd):/backup alpine \
  tar czf /backup/nextcloud-files.tar.gz /data

Check out our comprehensive backup guide for automated solutions.

Common Issues and Solutions​

"Maintenance mode" loops​

docker exec -u www-data nextcloud php occ maintenance:mode --off

Slow initial page loads​

Enable APCu and Redis caching, run cron consistently.

Upload size limits​

Configure PHP limits in your environment:

environment:
  - PHP_UPLOAD_LIMIT=16G

Learn More​

For complete, production-ready configurations:

• Complete Installation Guide
• Collabora Office Setup
• Troubleshooting Guide

Self-hosting your data is a journey. Join us on Discord to share your experiences!

Quick Comparison​

When to Use NFS​

Choose NFS when:

• All clients are Linux
• Performance is critical
• Docker containers need shared storage
• Proxmox/KVM shared storage
• Simple permission model works

When to Use SMB​

Choose SMB when:

• Windows clients exist
• Mixed environment (Windows + Linux + Mac)
• User-based permissions needed
• Media streaming to TVs/devices
• Samba AD integration required

NFS Setup (Server)​

Install NFS Server​

sudo apt install nfs-kernel-server

Create Export​

sudo mkdir -p /srv/nfs/media
sudo chown nobody:nogroup /srv/nfs/media

Configure Exports​

/srv/nfs/media    192.168.1.0/24(rw,sync,no_subtree_check,no_root_squash)

Options explained:

• rw - Read/write access
• sync - Write to disk before confirming
• no_subtree_check - Improves reliability
• no_root_squash - Allow root access (use carefully!)

Apply and Start​

sudo exportfs -a
sudo systemctl restart nfs-kernel-server

NFS Client Setup​

# Install client
sudo apt install nfs-common

# Create mount point
sudo mkdir -p /mnt/media

# Mount
sudo mount -t nfs server-ip:/srv/nfs/media /mnt/media

# Verify
df -h /mnt/media

Persistent Mount (fstab)​

server-ip:/srv/nfs/media  /mnt/media  nfs  defaults,_netdev  0  0

Docker Usage​

services:
  jellyfin:
    volumes:
      - nfs_media:/media

volumes:
  nfs_media:
    driver: local
    driver_opts:
      type: nfs
      o: addr=192.168.1.100,rw,nfsvers=4
      device: ":/srv/nfs/media"

SMB Setup (Server)​

Install Samba​

sudo apt install samba

Create Share Directory​

sudo mkdir -p /srv/samba/media
sudo chown nobody:nogroup /srv/samba/media
sudo chmod 2775 /srv/samba/media

Configure Samba​

[media]
   path = /srv/samba/media
   browseable = yes
   read only = no
   guest ok = no
   valid users = @sambashare
   create mask = 0664
   directory mask = 0775

Create Samba User​

# Add system user to samba group
sudo usermod -aG sambashare your-username

# Set Samba password
sudo smbpasswd -a your-username

Restart Samba​

sudo systemctl restart smbd
sudo systemctl restart nmbd

SMB Client Setup​

Linux​

# Install client
sudo apt install cifs-utils

# Mount
sudo mount -t cifs //server-ip/media /mnt/media -o username=your-username

# Persistent with credentials file
echo "username=your-username" > ~/.smbcredentials
echo "password=your-password" >> ~/.smbcredentials
chmod 600 ~/.smbcredentials

//server-ip/media  /mnt/media  cifs  credentials=/home/user/.smbcredentials,_netdev  0  0

Windows​

# Map network drive
net use M: \\server-ip\media /user:your-username

Or via File Explorer: \\server-ip\media

macOS​

Finder → Go → Connect to Server → smb://server-ip/media

Performance Tips​

NFS Tuning​

# Optimized NFS mount
server:/share  /mnt/share  nfs  rsize=1048576,wsize=1048576,hard,intr,_netdev  0  0

• rsize/wsize - Larger buffer sizes
• hard - Retry indefinitely on failure
• intr - Allow interrupt

SMB Tuning​

[global]
   socket options = TCP_NODELAY IPTOS_LOWDELAY
   read raw = yes
   write raw = yes
   max xmit = 65535

SSHFS Alternative​

For quick, secure mounts:

# Install
sudo apt install sshfs

# Mount
sshfs user@server:/path /mnt/sshfs

# Unmount
fusermount -u /mnt/sshfs

Pros: Encrypted, works through firewalls Cons: Slower, requires SSH access

My Setup​

Current storage shares:

• NFS - Proxmox VM disks, Docker volumes
• SMB - Media library for TVs/clients
• SSHFS - Quick access during development

Learn More​

• NFS Configuration
• CIFS/SMB Configuration
• SSHFS Setup
• MergerFS Pool

What's your storage protocol of choice? Share on Discord!

Why UniFi?​

After years of consumer routers, I switched to UniFi for:

• Unified management - Single interface for all devices
• VLAN support - Proper network segmentation
• Enterprise features - IDS/IPS, traffic analysis, captive portals
• Scalability - Start small, grow without replacing hardware
• No subscription - One-time hardware cost (mostly)

UniFi vs Consumer Routers​

UniFi Product Lines​

Network/Security​

• Dream Machine - All-in-one router + controller
• Security Gateway - Dedicated router/firewall
• Switches - Managed switches with PoE options

Wireless​

• Access Points - Various models for different needs
• In-Wall APs - Combine AP + switch ports

My Recommendations​

Starter setup:

• UDM SE (Dream Machine Special Edition)
• 1-2 U6 Pro access points
• USW-24-PoE switch

Budget conscious:

• USG (Security Gateway)
• USW-Lite-8-PoE
• U6 Lite access point
• Self-hosted controller

Installing UniFi Controller​

You don't need Ubiquiti hardware to run the controller. Self-host it for free!

Using GlennR's Scripts (Recommended)​

The easiest installation method:

# One-liner installation
rm unifi-latest.sh &> /dev/null; \
wget https://get.glennr.nl/unifi/install/install_latest/unifi-latest.sh && \
bash unifi-latest.sh

The script handles:

• MongoDB installation
• Java version management
• Dependencies
• Firewall rules
• Systemd service

Docker Alternative​

services:
  unifi-controller:
    image: lscr.io/linuxserver/unifi-controller:latest
    container_name: unifi-controller
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=America/New_York
    volumes:
      - unifi_config:/config
    ports:
      - "3478:3478/udp"   # STUN
      - "10001:10001/udp" # Device discovery
      - "8080:8080"       # Device communication
      - "8443:8443"       # Web UI
      - "6789:6789"       # Mobile speedtest
    restart: unless-stopped

volumes:
  unifi_config:

Initial Setup​

1. Access controller at https://YOUR-IP:8443
2. Create admin account
3. Set up site name and country
4. Adopt devices (they find the controller automatically)

Adopting Devices​

Devices on the same L2 network find the controller automatically. For remote adoption:

# SSH into UniFi device
ssh ubnt@device-ip

# Set inform URL
set-inform http://controller-ip:8080/inform

VLAN Configuration​

UniFi makes VLANs easy:

1. Settings → Networks → Create New
2. Set VLAN ID
3. Configure DHCP range
4. Apply to switch ports
5. Create corresponding SSID with VLAN tag

Example VLANs:

• VLAN 1: Management (default)
• VLAN 10: Trusted devices
• VLAN 20: IoT devices
• VLAN 30: Guest network

Firewall Rules​

Isolate your IoT devices:

Settings → Firewall & Security → Create Rule

Name: Block IoT to LAN
Type: LAN In
Source: IoT Network
Destination: All Networks except IoT
Action: Drop

Traffic Analytics​

UniFi provides detailed traffic analysis:

• Application identification
• Bandwidth usage per device
• Historical data
• Top clients/applications

Enable Deep Packet Inspection for full details (has performance impact).

Tips from Experience​

1. Backup your controller - Export site backups regularly
2. Stable releases only - Avoid beta firmware for critical infrastructure
3. Plan your VLANs - Changing later is painful
4. PoE budget - Calculate total PoE needs before buying switch
5. Hardwired backhaul - Wi-Fi mesh is good, Ethernet is better

Learn More​

• UniFi Controller Installation
• Network Configuration Basics

What networking gear are you running? Share your setup on Discord!

What is MergerFS?​

MergerFS is a union filesystem that:

• Combines multiple drives into a single mount point
• No reformatting required - Use existing filesystems
• No redundancy overhead - Full capacity available
• Drive independence - Each drive remains accessible individually
• Flexible policies - Choose how files are distributed

MergerFS vs RAID vs ZFS​

*Use SnapRAID alongside MergerFS for parity protection!

Installation​

# Ubuntu/Debian
sudo apt install mergerfs

# Or latest from GitHub
wget https://github.com/trapexit/mergerfs/releases/download/2.38.0/mergerfs_2.38.0.ubuntu-focal_amd64.deb
sudo dpkg -i mergerfs_2.38.0.ubuntu-focal_amd64.deb

Basic Setup​

Prepare Your Drives​

Assuming drives at /mnt/disk1, /mnt/disk2, /mnt/disk3:

# Create mount point for pool
sudo mkdir -p /mnt/storage

# Mount drives (add to fstab for persistence)
sudo mount /dev/sdb1 /mnt/disk1
sudo mount /dev/sdc1 /mnt/disk2
sudo mount /dev/sdd1 /mnt/disk3

Create MergerFS Pool​

# Basic merge
sudo mergerfs /mnt/disk1:/mnt/disk2:/mnt/disk3 /mnt/storage

# With recommended options
sudo mergerfs -o defaults,allow_other,use_ino,cache.files=off,moveonenospc=true,category.create=mfs,dropcacheonclose=true,minfreespace=50G,fsname=mergerfs /mnt/disk*:/mnt/storage

Persistent Mount (fstab)​

# Individual drives
/dev/sdb1 /mnt/disk1 ext4 defaults 0 2
/dev/sdc1 /mnt/disk2 ext4 defaults 0 2
/dev/sdd1 /mnt/disk3 ext4 defaults 0 2

# MergerFS pool
/mnt/disk* /mnt/storage fuse.mergerfs defaults,allow_other,use_ino,cache.files=off,moveonenospc=true,category.create=mfs,dropcacheonclose=true,minfreespace=50G,fsname=mergerfs 0 0

Key Options Explained​

category.create (File Placement Policy)​

For media libraries: mfs or epmfs For general use: mfs

minfreespace​

Stop writing to a drive when it has less than specified free space:

minfreespace=50G  # Leave 50GB free on each drive

moveonenospc​

If a drive fills up during a write, move the file to another drive:

moveonenospc=true

Use with Docker​

Perfect for media stacks!

services:
  jellyfin:
    image: jellyfin/jellyfin
    volumes:
      - /mnt/storage/media:/media:ro
      
  radarr:
    image: lscr.io/linuxserver/radarr
    volumes:
      - /mnt/storage/media/movies:/movies
      - /mnt/storage/downloads:/downloads

All containers see one unified /mnt/storage path.

Monitoring Pool Status​

# Check pool status
df -h /mnt/storage

# See individual drive usage
df -h /mnt/disk*

# Find which drive a file is on
getfattr -n user.mergerfs.fullpath /mnt/storage/somefile

Adding New Drives​

1. Format and mount new drive
2. Add to mergerfs mount options
3. Remount or restart

# Add /mnt/disk4
sudo umount /mnt/storage
sudo mergerfs /mnt/disk*:/mnt/storage -o ...options...

Tips from Experience​

1. Label your drives - Use /dev/disk/by-id/ in fstab
2. Test failover - Unplug a drive, verify others work
3. Monitor health - Use Scrutiny or smartd
4. Regular SnapRAID sync - Cron job daily
5. Backup critical data - SnapRAID isn't instant recovery

My Storage Setup​

Current configuration:

• 3 x 26TB drives in MergerFS pool
• 1 x 24TB drive in MergerFS pool
• 1 x 22TB drive in MergerFS pool
• 1 x 18TB drive in MergerFS pool
• minfreespace: 500GB (per drive)
• Used for Jellyfin media library (Without Parity)

Learn More​

• MergerFS Documentation
• Storage Options Comparison
• NFS Shares

How do you organize your storage? Share your setup on Discord!

What is SMART?​

Self-Monitoring, Analysis, and Reporting Technology (SMART) is built into most storage devices. It tracks:

• Reallocated Sectors - Bad blocks moved to spare area
• Spin Retry Count - Failed spin-up attempts
• Current Pending Sectors - Unstable sectors waiting to be remapped
• Temperature - Operating temperature
• Power On Hours - Total running time
• And many more...

When these metrics go bad, your drive is telling you it's dying.

Why Scrutiny?​

Scrutiny provides:

• Web dashboard - Visual overview of all drives
• Historical data - Track trends over time (via InfluxDB)
• Alerting - Get notified before failures
• Multi-server - Monitor drives across multiple machines

Docker Setup​

Here's a complete stack with InfluxDB for history:

services:
  scrutiny:
    image: ghcr.io/analogj/scrutiny:master-omnibus
    container_name: scrutiny
    cap_add:
      - SYS_RAWIO
    ports:
      - "8080:8080"
      - "8086:8086"  # InfluxDB
    volumes:
      - scrutiny_config:/opt/scrutiny/config
      - scrutiny_influxdb:/opt/scrutiny/influxdb
      - /run/udev:/run/udev:ro
    devices:
      - /dev/sda
      - /dev/sdb
      - /dev/sdc
      # Add all your drives
    restart: unless-stopped

volumes:
  scrutiny_config:
  scrutiny_influxdb:

Finding Your Drives​

# List all block devices
lsblk

# Get detailed drive info
sudo fdisk -l

Add each drive to the devices section.

Distributed Setup (Multiple Servers)​

For monitoring drives across multiple machines:

Hub (Central Server)​

services:
  scrutiny-web:
    image: ghcr.io/analogj/scrutiny:master-web
    container_name: scrutiny-web
    ports:
      - "8080:8080"
    volumes:
      - scrutiny_config:/opt/scrutiny/config
    restart: unless-stopped

  influxdb:
    image: influxdb:2.1
    container_name: scrutiny-influxdb
    ports:
      - "8086:8086"
    volumes:
      - influxdb_data:/var/lib/influxdb2
    restart: unless-stopped

volumes:
  scrutiny_config:
  influxdb_data:

Collector (Each Server with Drives)​

services:
  scrutiny-collector:
    image: ghcr.io/analogj/scrutiny:master-collector
    container_name: scrutiny-collector
    cap_add:
      - SYS_RAWIO
    environment:
      - COLLECTOR_API_ENDPOINT=http://hub-ip:8080
    volumes:
      - /run/udev:/run/udev:ro
    devices:
      - /dev/sda
      - /dev/sdb
    restart: unless-stopped