A practical migration recipe for Nextcloud AIO (with common pitfalls per phase)

[harryv1]

Hi,

during a recent real-world migration of a Nextcloud All-in-One (AIO) instance,
we went through several migration attempts and explored different approaches
before arriving at a stable and reproducible solution.

Along the way, a number of incorrect assumptions and small deviations from the
expected AIO workflow caused failed restores, inconsistent states, and many
hours spent on troubleshooting and unnecessary repair attempts.

Based on this experience, we documented a phased migration recipe that strictly
follows the official AIO documentation, with short notes about common pitfalls
per phase that can easily break an otherwise supported setup.

This is not an alternative guide and does not introduce unsupported workflows.
Its sole intention is to help others avoid the same mistakes and save time
during migrations or restores.

The process was tested during an ARM64 → x86_64 migration, but the steps
themselves are architecture-agnostic as long as official AIO images are used.

If this is useful, feel free to link or reference it from the FAQ or other
“helpful resources” sections.

Cheers Harry

A practical migration recipe for Nextcloud AIO

(with common pitfalls per phase)

This document describes a compact, reproducible migration workflow for
Nextcloud All-in-One (AIO), based on a real-world migration using Borg backups.

The migration was performed and validated using a recent Nextcloud All-in-One
(AIO) release from the 12.x series. The described workflow relies only on
documented and supported AIO behavior and should remain valid across minor
updates within the same major version.

It is intended as a practical recipe, not a replacement for the official
documentation. Each phase includes notes on common pitfalls that can break an
otherwise supported setup.

The process was tested during an ARM64 → x86_64 migration, but the steps are
architecture-agnostic as long as official AIO images are used.

Always follow the official AIO documentation first.

---

Phase 1 – Prepare OS, network, and base system

Goal: Provide a clean, predictable host environment.

• Install a supported Linux distribution
• Configure IPv4/IPv6, DNS, and firewall
• Ensure stable hostname and domain configuration
• Install Docker from the official Docker repository
• Do not install additional container runtimes or orchestration layers

Pitfalls in this phase:

• Mixing distro Docker packages with upstream Docker packages
• Changing hostname or domain later during the migration
• Leaving old container runtimes or previous Nextcloud installations in place

---

Phase 2 – Prepare storage and backup locations

Goal: Ensure all persistent data is clearly located outside containers.

• Decide on the final Nextcloud data directory on the host
• Prepare the Borg backup repository location on the host
• Verify permissions and ownership
• Ensure sufficient free disk space before starting

Pitfalls in this phase:

• Letting data fall back to container-internal volumes unintentionally
• Changing the data directory after production use
• Using ambiguous or temporary mount paths

---

Phase 3 – Start the AIO mastercontainer (final configuration only)

Goal: Initialize AIO exactly once with the final configuration.

• Start the mastercontainer with:
  • final domain
  • final ports
  • final data directory
  • final volume mappings
• Do not use a “temporary” or “minimal” startup

Pitfalls in this phase:

• Starting the mastercontainer with incomplete parameters
• Planning to “fix” ports, domains, or volumes later
• Restarting from scratch instead of correcting configuration early

The initial startup defines internal configuration state that is hard to
safely change later.

---

Phase 4 – Access the AIO interface safely

Goal: Ensure reliable administrative access.

• Access the AIO interface on port 8080 using an IP address
• Complete initial setup steps
• Store generated passwords and recovery information securely

Pitfalls in this phase:

• Accessing port 8080 via a domain name
• Running into browser HSTS issues later
• Locking yourself out of the AIO interface unintentionally

---

Phase 5 – Restore from Borg backup using AIO

Goal: Restore the previous instance exactly as intended.

• Use only the AIO restore function
• Provide the correct host path containing the Borg repository
• Enter the correct encryption passphrase
• Follow all restore instructions shown by AIO

Pitfalls in this phase:

• Attempting manual Borg restores outside AIO
• Selecting the wrong directory level for the Borg repository
• Assuming a restore failed because containers are stopped afterwards

---

Phase 6 – Handle community containers and second restore pass

Goal: Ensure all optional containers are restored correctly.

• If AIO indicates that a second restore is required, perform it
• This commonly applies to community containers

Pitfalls in this phase:

• Skipping the second restore because the first one “looked fine”
• Manually intervening instead of following AIO instructions

---

Phase 7 – Start containers and validate functionality

Goal: Bring the system into production state.

• Start containers via the AIO interface
• Verify that all containers are healthy
• Log into Nextcloud
• Check files, calendars, contacts, and apps

Pitfalls in this phase:

• Interpreting stopped containers after restore as an error
• Restarting or recreating the mastercontainer
• Making manual changes before validation is complete

---

Phase 8 – Post-migration checks and hardening

Goal: Stabilize and secure the system.

• Run occ maintenance:repair
• Verify backups and backup scheduling
• Configure SSH key-based access
• Enable unattended OS security updates
• Take a full system snapshot

Pitfalls in this phase:

• Skipping validation because the UI “looks fine”
• Delaying backups until later changes are made
• Hardening too early before functionality is verified

---

Final notes

Nextcloud AIO is reliable and robust when used as designed, but it is sensitive
to deviations from its expected workflow.

Following a clear, phased migration approach and avoiding the pitfalls noted
above leads to reproducible and stable results.