hermes-skills/skills/devops/infrastructure-automation/references/unms-unifi-migration.md

UNMS & UniFi Migration Pattern

Source servers (discovered Jul 10, 2026):

Service	IP	Hostname	Type	Architecture
UNMS/UISP	5.161.225.131	unms	Hetzner CPX21	Docker stack (16 containers)
UniFi Controller	178.156.131.57	unifi	Hetzner CPX21	Native install (9.5.21)

Destination: app2 (152.53.39.202, netcup RS 4000 G12)

UNMS Migration Pattern

UNMS runs as a Docker stack managed by /home/unms/app/unms-cli. The data directory is /home/unms/data.

Database Backup

# Option A: Native UNMS auto-backup (preferred)
# Backups are at /home/unms/data/unms-backups/backups/*.unms (~139MB each)
# Latest auto-backup runs daily at 04:01 UTC

# Option B: pg_dump (times out on large datasets with TimescaleDB)
docker exec unms-postgres pg_dump -U unms unms > dump.sql

Restore Process

# 1. Copy backup to app2
scp user@5.161.225.131:/home/unms/data/unms-backups/backups/latest.unms .

# 2. Install UNMS on app2
# Follow https://uisp.com/install

# 3. Copy backup to the backups directory (NOT restore/)
sudo cp latest.unms /home/unms/data/unms-backups/backups/
sudo chown unms:unms /home/unms/data/unms-backups/backups/latest.unms

# 4. Run restore (accepts interactive Y/N prompt)
echo Y | sudo /home/unms/app/unms-cli restore-backup \
  --file /home/unms/data/unms-backups/backups/latest.unms

Pitfalls

• The restore/ subdirectory does NOT work. UNMS Docker containers mount /home/unms/data but the restore path inside the container differs from the host. Place backups in backups/ not restore/.
• Docker version mismatch warning is not fatal — detected 29.x vs expected 27.x. The restore still proceeds.
• pg_dump times out on TimescaleDB — the circular foreign key constraints cause it to hang. Use the native .unms auto-backup instead.
• unms-cli wipes and recreates all containers during restore. The Postgres container is recreated with fresh data, then migration scripts run.
• Wait ~2-3 minutes after restore for Postgres migrations and API initialization. unms-api shows (health: starting) during this window.

UniFi Migration Pattern

# 1. Grab latest auto-backup from source
ssh root@178.156.131.57
ls /usr/lib/unifi/data/backup/autobackup_*.unf | tail -1

# 2. Or grab entire MongoDB data directory
scp -r root@178.156.131.57:/usr/lib/unifi/data/db/ .

# 3. Install UniFi on app2 (native or LinuxServer.io Docker image)
# 4. Restore from .unf via controller UI, or restore db/ directory

Pitfalls

• UniFi 9.5.21 uses MongoDB internally. Restoring just the data directory preserves device adoptions.
• The .unf backup file is the preferred method — it includes controller config + device database.
• DNS for unifi is managed at SiteGround (not Cloudflare). A records need updating there.