Tutorial: Migrate your home server from CasaOS to ZimaOS (data + apps, no data loss)

Insight & Feedback
, , ,
1

This is a step-by-step guide to moving your home server from CasaOS to ZimaOS, based on
my own migration (~800 GB). The built-in migration tool failed for me midway (a download
error, because my data disk wasn’t mounted the way it expected), so I did it manually —
which turned out to be the more reliable path. This tutorial follows that manual process.

Why migrate?
• Free upgrade — ZimaOS is the evolution of CasaOS, same open-source roots
• Redesigned App Store, native Docker Compose support, and a mobile app (Zima Client)
• Your apps, storage and data stay with you; nothing is re-downloaded

The migration has two parts: move your data, then move your apps.

STEP 1 — Move your data (disk-to-disk)

  1. On the old server, create an SMB share (CasaOS side) and connect to it from ZimaOS.
  2. From the ZimaOS/proxmox host, expose and mount the old data disk.
  3. Copy the data with rsync (disk-to-disk, no network transfer, ~800 GB in my case).
  4. Verify the copy with a size report before touching anything.

STEP 2 — Move your apps (Docker Compose)

  1. Your composes live at /var/lib/casaos/apps — one folder per app with its docker-compose.yml.
  2. Copy that folder over through the SMB share.
  3. In the ZimaOS App Store, open “Install a customized app”, switch to the YAML tab and paste.
    → Note on x-casaos: deleting that section isn’t strictly necessary, but in some imports it
    causes problems — it may be why an import fails.
  4. ZimaOS fills the form for you: title, image, ports, volumes. Hit install.
  5. Optional: for apps that need manual setup, the same panel works as a form.

Before you import everything:
• Open any app and check its volumes point at your new migrated folders (AppData, Downloads,
etc.) — so any future service saves everything in the same place.

Mistakes that cost me hours (avoid these):

  1. Never use the command that deletes an unused disk in Proxmox — it erases the physical drive.
  2. List what’s inside a folder before deleting anything ZimaOS creates.
  3. Always import your original compose file instead of reinstalling from scratch, or your
    existing config gets ignored.

I documented everything with every command and exact path, plus a video walkthrough.

Useful references:
:open_book: Full written guide with every command: HOMELAB/Migraciones/CasaOS_to_ZimaOS at main · mateorzan/HOMELAB · GitHub

:video_camera: Video-walkthrough: https://www.youtube.com/watch?v=lFB07rQOISU&t=6s

My setup: ZimaBlade N100 cluster (Proxmox + Proxmox Backup), ZimaOS VM, Raspberry Pi 5.
Happy to answer questions in the comments

1 Like