Migration Guide¶

This guide covers migrating to HomelabARR CE from other Docker management platforms.

Migrating from Similar Docker Platforms¶

If your existing setup uses /opt/appdata/ for container data and a proxy Docker network with Traefik, the migration is straightforward — HomelabARR CE uses the same structure.

Step 1: Backup Everything¶

Before making any changes:

# Backup your current .env file
cp /opt/appdata/compose/.env /opt/appdata/compose/.env.backup

# Backup your appdata (compress, this may take a while)
sudo tar czf /opt/homelabarr-backup-$(date +%Y%m%d).tar.gz /opt/appdata/

# Note your running containers
docker ps --format "{{.Names}}" > /opt/running-containers.txt

Step 2: Stop Existing Containers¶

# Stop all running containers (your data in /opt/appdata is safe)
docker stop $(docker ps -q)

Step 3: Migrate Environment Variables¶

HomelabARR CE includes a migration tool that converts your existing .env:

git clone https://github.com/smashingtags/homelabarr-ce.git
cd homelabarr-ce
sudo ln -sf "$(pwd)" /opt/homelabarr

# Run the environment migrator
bash apps/.subactions/envmigrate.sh

This reads /opt/appdata/compose/.env and rewrites it with CE-compatible defaults while preserving these standard values:

• Cloudflare credentials (email, API key, Zone ID)
• Domain configuration
• Plex claim tokens
• VPN settings (Gluetun/WireGuard)
• Container image preferences
• Port configurations
• API keys (IMDB, TVDB, TMDB)

If you have custom environment variables not in this list, copy them from your backup after running the migrator.

Step 4: Install HomelabARR CE¶

You have two options:

Option A: Web GUI (Docker Compose)

curl -o homelabarr.yml https://raw.githubusercontent.com/smashingtags/homelabarr-ce/main/homelabarr.yml
export JWT_SECRET=$(openssl rand -base64 32)
export DOCKER_GID=$(getent group docker | cut -d: -f3)
export CORS_ORIGIN=http://$(hostname -I | awk '{print $1}'):8084
docker compose -f homelabarr.yml up -d

Open http://your-server-ip:8084 — you'll see the CE dashboard with 157+ apps ready to deploy. Your existing /opt/appdata data is already there.

http:
  routers:
    homelabarr-ce:
      rule: "Host(`homelabarr.yourdomain.com`)"
      entryPoints:
        - https
      middlewares:
        - chain-authelia@file
      tls:
        certResolver: dns-cloudflare
      service: homelabarr-ce
  services:
    homelabarr-ce:
      loadBalancer:
        servers:
          - url: "http://homelabarr-ce-frontend:8080"

Option B: CLI Menu

chmod +x install.sh
find . -name "*.sh" -exec chmod +x {} \;
sudo ./install.sh

The interactive menu lets you:

• Option 1: Set up Traefik + Authelia (if not already running)
• Option 2: Install/Remove/Backup/Restore apps via the terminal menu

Step 5: Redeploy Your Apps (One at a Time)¶

Your app data is already in /opt/appdata. You need to stop each old container and redeploy it through CE. Do this one app at a time — not all at once.

For each app (e.g., Sonarr):

# 1. Stop and remove the OLD container
docker stop sonarr && docker rm sonarr

# 2. Redeploy through CE
#    Via Web GUI: Browse catalog → find Sonarr → Deploy (Standard mode)
#    Via CLI: Option 2 → Install Apps → mediamanager → sonarr

# 3. Verify it starts and loads your existing config
docker logs sonarr --tail 20

The new container will mount /opt/appdata/sonarr (your existing config) and /mnt (your media) using Docker's native bind mounts — no plugins needed.

Suggested order:

1. Non-critical apps first (Tautulli, Heimdall, Dozzle)
2. Download clients (NZBGet, qBittorrent, SABnzbd)
3. Media managers (Sonarr, Radarr, Lidarr, Prowlarr)
4. Media servers (Jellyfin, Plex — these have the biggest configs)

After each app, verify:

• Sonarr/Radarr: Series/movies listed in Mass Editor
• qBittorrent: Torrents resume, download path is correct
• Jellyfin/Plex: Libraries intact, playback works
• Authelia: Users and 2FA preserved (/opt/appdata/authelia/)

Step 6: Clean Up Legacy Components¶

Once all apps are redeployed through CE:

# Stop the old mount container (it's been failing anyway if you're not using cloud storage)
docker stop mount && docker rm mount

# Stop restic and vnstat if you no longer need them
docker stop restic vnstat && docker rm restic vnstat

# Remove the old local-persist volume (data is safe — it just pointed at /mnt)
docker volume rm compose_unionfs 2>/dev/null

# Remove the local-persist plugin/binary
sudo rm /usr/bin/docker-volume-local-persist 2>/dev/null
sudo rm /run/docker/plugins/local-persist.sock 2>/dev/null

# Clean up old images
docker image prune -a

# Remove your backup if everything works (or keep it!)
# rm /opt/homelabarr-backup-*.tar.gz

docker inspect traefik --format '{{json .Args}}' | grep docker.network

Migrating from PGBlitz / PTS / PlexGuide¶

If you're running PGBlitz, PTS (MHA-Team fork), or the original PlexGuide — your setup is older but the migration is straightforward. Your Plex libraries, Sonarr configs, and all your app data will survive the move.

What's Different¶

Step-by-Step Migration¶

1. Backup your configs¶

# Backup your rclone config (you may need this later)
cp ~/.config/rclone/rclone.conf ~/rclone.conf.backup

# Backup all app data
sudo tar czf ~/pgblitz-appdata-backup-$(date +%Y%m%d).tar.gz /opt/appdata/

2. Document your current setup¶

Before changing anything, note what you're running:

# List all running containers
docker ps --format "{{.Names}}\t{{.Image}}\t{{.Ports}}" > ~/my-containers.txt
cat ~/my-containers.txt

Save this list — you'll use it to know what to redeploy.

3. Decide: keep cloud storage or go local?¶

If you're keeping cloud storage (Google Drive + rclone): Your rclone mounts at /mnt/unionfs or /mnt will continue working. CE's app templates mount /mnt the same way. Skip to Step 4.

If you're moving to local NAS (recommended): See the Cloud to Local Migration section below for how to download your media and set up NAS mounts. Do this BEFORE proceeding.

4. Install HomelabARR CE¶

# One-line install
sudo wget -qO- https://raw.githubusercontent.com/smashingtags/homelabarr-ce/main/install-remote.sh | sudo bash

# Or Docker Compose for the web GUI
curl -o homelabarr.yml https://raw.githubusercontent.com/smashingtags/homelabarr-ce/main/homelabarr.yml
export JWT_SECRET=$(openssl rand -base64 32)
export DOCKER_GID=$(getent group docker | cut -d: -f3)
export CORS_ORIGIN=http://$(hostname -I | awk '{print $1}'):8084
docker compose -f homelabarr.yml up -d

5. Create the proxy network¶

PGBlitz uses plexguide network. CE uses proxy. Create it:

docker network create proxy 2>/dev/null || true

6. Redeploy apps one at a time¶

For each app in your my-containers.txt list, stop the old container and redeploy through CE:

# Example: migrate Sonarr
docker stop sonarr && docker rm sonarr

# Redeploy via CE web GUI (http://your-ip:8084) or CLI
sudo homelabarr-cli -i
# → Option 2 → Install Apps → mediamanager → sonarr

The new Sonarr container will: - Mount your existing /opt/appdata/sonarr config (series, settings, history — all preserved) - Mount /mnt for media access - Use Traefik v2/v3 labels (if you set up Traefik) - Work with the proxy network

7. Handle Traefik¶

PGBlitz uses Traefik v1. CE uses Traefik v2/v3. You have two options:

Option A: Fresh Traefik (recommended) Stop the old Traefik and let CE deploy a new one:

docker stop traefik && docker rm traefik
# Via CLI: Option 1 → Traefik + Authelia

Option B: Keep existing Traefik If you've customized your Traefik v1 setup and don't want to change it, you can keep it — but CE's app templates use v2 labels which won't work with Traefik v1. You'd need to add v1 labels manually to each container.

8. Verify Plex¶

This is the one everyone worries about. After redeploying Plex through CE:

1. Open Plex Web (your existing URL or http://your-ip:32400/web)
2. Check Settings → Libraries — all libraries should be listed
3. Play something — verify transcoding works
4. Check Settings → Server → General — your Plex claim token and server name should be intact

Your Plex database, watch history, posters, metadata — everything lives in /opt/appdata/plex and was never touched during the migration.

9. Clean up PGBlitz/PTS¶

Once everything is verified through CE:

# Remove old PGBlitz/PTS installation
sudo rm -rf /opt/plexguide 2>/dev/null
sudo rm -rf /opt/pgblitz 2>/dev/null
sudo rm -rf /opt/pts 2>/dev/null
sudo rm -rf /opt/coreapps 2>/dev/null
sudo rm -rf /opt/communityapps 2>/dev/null

# Remove old plexguide network (after all containers are on proxy)
docker network rm plexguide 2>/dev/null

# Remove old cron jobs
crontab -l | grep -v "plexguide\|pgblitz\|pts" | crontab -

# Clean up old images
docker image prune -a

Migrating from Saltbox¶

Saltbox is the actively maintained successor to Cloudbox. It's a solid platform, but it's Ansible-based with no GUI — every change requires editing YAML files and running playbooks. If you want a web dashboard to manage your containers or you're tired of Ansible complexity, CE is a straightforward alternative.

What's Different¶

Step-by-Step Migration¶

1. Backup your Saltbox¶

# Use Saltbox's own backup
cd ~/saltbox && sudo ansible-playbook backup.yml

# Also backup manually
cp ~/saltbox/accounts.yml ~/accounts.yml.backup
cp -r /opt/saltbox ~/saltbox-opt-backup
sudo tar czf ~/saltbox-appdata-$(date +%Y%m%d).tar.gz /opt/

2. Move app data to CE's path¶

Saltbox stores configs at /opt/<app>/. CE expects /opt/appdata/<app>/:

sudo mkdir -p /opt/appdata

# Move each app's config
for app in sonarr radarr lidarr readarr prowlarr bazarr plex jellyfin tautulli nzbget sabnzbd qbittorrent overseerr; do
  if [ -d "/opt/$app" ]; then
    sudo mv /opt/$app /opt/appdata/$app
    echo "Moved $app"
  fi
done

sudo chown -R 1000:1000 /opt/appdata

3. Handle media paths¶

Saltbox uses /mnt/unionfs/ for combined local + cloud media. If you're keeping this mount structure, create a symlink:

# If /mnt/unionfs already exists and has your media
sudo ln -sf /mnt/unionfs /mnt/media 2>/dev/null || true

If moving to local NAS, see the Cloud to Local Migration section.

4. Create the proxy network¶

docker network create proxy 2>/dev/null || true

5. Install HomelabARR CE¶

# One-line CLI install
sudo wget -qO- https://raw.githubusercontent.com/smashingtags/homelabarr-ce/main/install-remote.sh | sudo bash
sudo homelabarr-cli -i

# Or Docker Compose for web GUI
curl -o homelabarr.yml https://raw.githubusercontent.com/smashingtags/homelabarr-ce/main/homelabarr.yml
export JWT_SECRET=$(openssl rand -base64 32)
export DOCKER_GID=$(getent group docker | cut -d: -f3)
export CORS_ORIGIN=http://$(hostname -I | awk '{print $1}'):8084
docker compose -f homelabarr.yml up -d

6. Redeploy apps one at a time¶

For each app, stop the Saltbox container and redeploy through CE:

# Example: migrate Sonarr
docker stop sonarr && docker rm sonarr

# Redeploy via CE web GUI or CLI
# Your existing /opt/appdata/sonarr config is picked up automatically

7. Update root folders in media apps¶

After redeploying, check the media root folders in each app. Saltbox maps internal paths differently:

The paths inside the container may differ from Saltbox's mapping. Update them to match CE's volume mounts if needed.

8. Clean up Saltbox (optional)¶

If you're fully committed to CE:

# Remove Saltbox installation
sudo rm -rf ~/saltbox 2>/dev/null
sudo rm -rf /opt/saltbox 2>/dev/null
sudo rm -rf /srv/git/saltbox 2>/dev/null

# Remove Ansible (if nothing else uses it)
sudo apt remove ansible -y 2>/dev/null

# Remove old network (after all containers are on proxy)
docker network rm saltbox 2>/dev/null

# Clean up
docker image prune -a

Migrating from Cloudbox¶

Cloudbox was one of the most popular Ansible-based media server solutions. The project was archived in March 2025 and is no longer maintained. If you're still running it, migrating to HomelabARR CE gives you a modern, actively maintained platform with a web GUI.

What's Different¶

Step-by-Step Migration¶

1. Backup everything¶

# Backup rclone config
cp ~/.config/rclone/rclone.conf ~/rclone.conf.backup

# Backup Cloudbox settings
cp ~/cloudbox/accounts.yml ~/accounts.yml.backup

# Backup all app data
sudo tar czf ~/cloudbox-backup-$(date +%Y%m%d).tar.gz /opt/

2. Move app data to CE's expected path¶

Cloudbox stores configs at /opt/<app>/ (e.g., /opt/sonarr/). CE expects /opt/appdata/<app>/. Create the new structure and move:

sudo mkdir -p /opt/appdata

# Move each app's config
for app in plex sonarr radarr lidarr tautulli jackett nzbget sabnzbd ombi; do
  if [ -d "/opt/$app" ]; then
    sudo mv /opt/$app /opt/appdata/$app
    echo "Moved $app"
  fi
done

sudo chown -R 1000:1000 /opt/appdata

3. Handle media paths¶

Cloudbox uses a specific media structure:

/mnt/unionfs/Media/Movies/
/mnt/unionfs/Media/TV/
/mnt/unionfs/Media/Music/

CE mounts /mnt directly. If your media is at /mnt/unionfs/Media/, you have two options:

Option A: Symlink (quickest)

# If your media is still at /mnt/unionfs/Media
sudo ln -sf /mnt/unionfs/Media /mnt/Media

Option B: Move to local NAS (recommended) See the Cloud to Local Migration section below. Point your NAS mount at /mnt and organize as you like.

4. Create the proxy network¶

docker network create proxy 2>/dev/null || true

5. Install HomelabARR CE¶

# One-line CLI install
sudo wget -qO- https://raw.githubusercontent.com/smashingtags/homelabarr-ce/main/install-remote.sh | sudo bash
sudo homelabarr-cli -i

# Or Docker Compose for web GUI
curl -o homelabarr.yml https://raw.githubusercontent.com/smashingtags/homelabarr-ce/main/homelabarr.yml
export JWT_SECRET=$(openssl rand -base64 32)
export DOCKER_GID=$(getent group docker | cut -d: -f3)
export CORS_ORIGIN=http://$(hostname -I | awk '{print $1}'):8084
docker compose -f homelabarr.yml up -d

6. Redeploy apps one at a time¶

# Stop old Cloudbox container
docker stop sonarr && docker rm sonarr

# Redeploy through CE (web GUI or CLI)
# The new container mounts /opt/appdata/sonarr:/config — your existing data

After redeploying each media app, update the media root folders:

7. Clean up Cloudbox¶

# Remove Cloudbox installation
sudo rm -rf ~/cloudbox 2>/dev/null
sudo rm -rf /opt/cloudbox 2>/dev/null

# Remove old network
docker network rm cloudbox 2>/dev/null

# Remove old Ansible
sudo apt remove ansible -y 2>/dev/null

# Clean up old images
docker image prune -a

Migrating from Cloud-Based Setups¶

If you're moving from a cloud-dependent system (Google Drive mounts, rclone cloud storage) to local NAS storage:

Prerequisites¶

• NAS System: UnRAID, TrueNAS, Synology, or local drives
• Network Share: SMB or NFS configured
• Storage: Enough space for your media library

Download Media from Cloud¶

Before switching, get your media local:

# Example: rclone sync from Google Drive to local NAS
rclone sync gdrive:media /mnt/nas/media --progress --transfers 8

Set Up Local Storage¶

# Create mount points for NAS shares
sudo mkdir -p /mnt/nas/{media,downloads,appdata}

# Mount via SMB
sudo mount -t cifs //nas.local/media /mnt/nas/media -o uid=1000,gid=1000,username=user,password=pass

# Or mount via NFS
sudo mount -t nfs nas.local:/volume1/media /mnt/nas/media

Add to /etc/fstab for persistence:

//nas.local/media  /mnt/nas/media  cifs  uid=1000,gid=1000,username=user,password=pass,_netdev  0  0

Update Application Paths¶

After installing CE and redeploying apps, update media paths:

Benefits of Local Storage¶

• No API rate limits — process unlimited files simultaneously
• No cloud subscription costs — your storage, your hardware
• Better performance — local I/O is faster than cloud transfers
• Privacy — data stays on your network
• Simpler setup — no rclone configs, mount scripts, or cloud auth

Compatibility Reference¶

HomelabARR CE is compatible with setups that use:

If your existing setup matches these conventions, the migration is essentially a drop-in replacement.

Support¶

Having trouble migrating?

• Discord — Ask in the #support channel
• GitHub Issues — Report migration bugs
• Email — michael@mjashley.com