How to Move CasaOS to New Hardware Safely

Best migration strategy: treat CasaOS as three layers—host OS, app definitions, and persistent data. Reinstalling CasaOS is the easy part. The important work is preserving the folders and configuration your containers actually use, then recreating the same paths on the new machine.

Inventory before copying

CasaOS and base Linux versions;
container images, ports, and environment variables;
all bind-mount source paths;
/DATA/AppData and custom app folders;
media/data disk mount points;
UID/GID ownership;
static IP, DNS, proxy, VPN, and firewall rules.

CasaOS store apps commonly persist data under /DATA/AppData/$AppID. The CasaOS AppData pattern shows why copying a Docker container alone is not a migration.

Stop write-heavy apps before final copy

Databases and app state can change while you copy. Stop the relevant containers—or Docker for the final sync—before taking the last backup.

sudo systemctl stop casaos-app-management
sudo systemctl stop docker

Then copy with a metadata-preserving tool such as rsync -aHAX when your filesystems support it.

Inventory named volumes too

Some apps use Docker volumes instead of host bind mounts. Docker's persistent Docker volumes outlive containers but still need to be migrated intentionally.

Recreate storage paths first

On the new host, mount disks before launching apps. If Jellyfin previously used /DATA/Media/Movies, restoring that same path avoids broken libraries. If paths change, edit container mappings before first start.

Preserve numeric ownership

Containers care about numeric UID/GID. Compare important directories on old and new systems:

stat -c '%u:%g %a %n' /DATA/AppData/*

Bring services back in stages

Install a supported Linux base.
Install CasaOS.
Mount all data disks.
Restore persistent data.
Recreate/import app definitions.
Start stateful apps one by one.
Validate databases, media, permissions, and schedules.
Switch IP/DNS only after tests pass.

The CasaOS Docker structure explains why app data and containers are separate concerns. The self-hosted app platform is relevant if you are migrating to ZimaOS rather than rebuilding CasaOS.

For a compact x86 replacement, ZimaBoard 2 can fit smaller deployments.

Classify every app by state type

Not all containers are migrated the same way:

Stateless: configuration can be recreated from compose/environment.
File-based: copy bind-mounted folders.
SQLite: stop the app before copying the database file.
PostgreSQL/MySQL: use an application/database backup when possible rather than relying only on a live filesystem copy.
Named-volume apps: export or copy the Docker volume intentionally.

Capture the current Docker configuration

For each important container, save:

docker inspect <container> > container-inspect.json

This is not a ready-to-import compose file, but it records mounts, ports, environment, networks, and devices so you can verify that the rebuilt service matches the old one.

Plan IP and hostname cutover

If clients use a server hostname, migration is easier: point DNS to the new IP after validation. If every app is hard-coded to the old IP, you may prefer assigning the old static address to the new host after the old one is offline.

Keep the old server untouched until rollback is unnecessary

Do not wipe the source immediately after the first successful login. Keep it powered off but intact through at least one backup cycle and one period of normal usage. That gives you a known-good rollback if a scheduled job, database, or remote client was missed.

Validate data, not just containers

A green Docker status only proves the process is running. Validate:

Jellyfin library and watch state;
Syncthing folder health;
backup jobs and restore tests;
database applications;
external drive paths;
reverse proxy certificates;
remote VPN/tunnel access.

FAQ

Can I clone the boot disk?

Sometimes, but a clone carries hardware-specific networking, boot, and mount assumptions. A clean host plus restored data is often easier to validate.

When can I retire the old server?

Only after app logins, databases, media paths, permissions, scheduled jobs, backups, and remote access all work on the new host.