Migration Guide¶

Moving to HomelabARR CE from another platform? This guide walks you through it step by step. Your app data (Plex database, Sonarr configs, everything in /opt/appdata/) carries over — we use the same paths.

Before You Start¶

Figure out which platform you're coming from, because the migration steps are slightly different:

# Back up ALL your app data — this may take 10-30+ minutes depending on library size
sudo tar czf /opt/homelabarr-backup-$(date +%Y%m%d).tar.gz /opt/appdata/

# Save a list of what's running right now
docker ps --format "{{.Names}}" > ~/my-running-containers.txt

# Back up your .env if you have one
cp /opt/appdata/compose/.env ~/env-backup.txt 2>/dev/null

ls -lh /opt/homelabarr-backup-*.tar.gz

Step 1: Install HomelabARR CE¶

Don't stop your old containers yet. Install CE alongside them first so you can verify it works.

# Get the code
git clone https://github.com/smashingtags/homelabarr-ce.git /opt/homelabarr
cd /opt/homelabarr

# Set required environment variables
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

# Start the CE dashboard
docker compose -f homelabarr.yml up -d

Open http://your-server-ip:8084 in your browser. You should see the dashboard with 100+ apps.

Step 2: Migrate Apps (One at a Time)¶

This is the important part. Do NOT stop everything at once. Migrate one app, verify it works, then move to the next.

Suggested order (least risky first):

1. Monitoring apps (Tautulli, Dozzle, Uptime Kuma) — ~2 min each
2. Download clients (NZBGet, qBittorrent, SABnzbd) — ~3 min each
3. Media managers (Sonarr, Radarr, Lidarr, Prowlarr) — ~3-5 min each
4. Media servers (Plex, Jellyfin — save these for last) — 10-30+ min if your library is large

For each app:

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

# 2. Open the CE dashboard → find Sonarr → click Deploy
#    Pick your deployment mode:
#    - Standard = no reverse proxy, access via IP:port
#    - Traefik = SSL + custom domain (sonarr.yourdomain.com)
#    - Traefik + Authelia = SSL + custom domain + login protection

# 3. Check that it started and loaded your config
docker logs sonarr --tail 20

The new container mounts /opt/appdata/sonarr automatically — your series, settings, history, everything is already there.

After each app, verify:

• Sonarr/Radarr: Open the web UI → check that your series/movies are listed
• qBittorrent: Check that torrents are still there and paths are correct
• Plex/Jellyfin: Check libraries → play something → confirm watch history survived
• NZBGet/SABnzbd: Check download queue and completed folder path

Step 3: Handle Network Differences¶

Different platforms use different Docker network names. CE uses a network called proxy. If your old platform used a different name, you may need to update Traefik.

Create the CE network if it doesn't exist:

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

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

Platform-Specific Notes¶

Click your platform to expand the instructions:

sudo mkdir -p /opt/appdata

for app in sonarr radarr lidarr readarr prowlarr bazarr plex jellyfin tautulli nzbget sabnzbd qbittorrent; 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

docker stop traefik && docker rm traefik

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

sudo ln -sf /mnt/unionfs/Media /mnt/Media

Moving from Cloud to Local Storage¶

If you're leaving Google Drive / rclone behind for local NAS storage:

1. Download your media¶

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

This can take days depending on library size. Start it in a tmux or screen session.

2. Set up NAS mounts¶

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

Add to /etc/fstab so it survives reboots:

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

3. Update app paths¶

After mounting your NAS, update the root folders in each media app:

Why go local?¶

• No API rate limits — Google limits how fast you can read files
• No cloud subscription costs — your hardware, your storage
• Better performance — local I/O is way faster than cloud transfers
• Simpler setup — no rclone configs, mount scripts, or token refreshes

Step 4: Clean Up¶

Once all your apps are running through CE and verified:

# Remove old platform files (pick the one that applies)
sudo rm -rf ~/cloudbox ~/saltbox /opt/plexguide /opt/pgblitz 2>/dev/null

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

# Clean up unused Docker images (frees disk space)
docker image prune -a

# Remove old cron jobs from previous platforms
crontab -l | grep -v "plexguide\|pgblitz\|saltbox\|cloudbox" | crontab -

Quick Reference¶

CE expects these paths and settings:

If your existing setup already matches these, migration is basically just "install CE and redeploy through the dashboard."

Need Help?¶

• Discord — Ask in #help, someone's usually around
• GitHub Discussions — For longer questions
• FAQ — Common issues and fixes