Skip to content

Migrate from Uberspace 7 to 8

Move an existing Asteroid in stages: inventory its resources, prepare a separate Uberspace 8 destination, test a restore, pause writers, transfer the final changes, and switch traffic. Keep the source until you have verified the destination and finished collecting mail that still arrives on the old host.

Uberspace can run many kinds of software. This Howto provides a migration workflow, not an application compatibility list or a command that converts an entire Asteroid. Use your application's backup and restore instructions alongside it. Read the platform changes first.

Before you start

You need SSH access to both Asteroids, enough destination and backup storage, control of your DNS, and a maintenance window. Verify both SSH host keys against the dashboard; use the Asteroid accounts, not root. The SSH Howto explains the connection setup.

Examples use these different accounts:

Role Example
Source, U7 isabell@stardust.uberspace.de
Destination, U8 isabell8@moondust.uberspace.de
Website to retain app.example
Local private backup u7-u8/ on your computer

Replace all names, paths, database names, and connection settings with your own. Command output below is illustrative and sometimes shortened. A migration between different usernames also changes home paths, database namespaces, and the default .uber.space address. Establish how existing addresses will be handled before scheduling the move; a new Asteroid does not inherit the old Asteroid's name or DNS records.

Choose success criteria and a return plan now. For example: users can log in, existing uploads download correctly, database contents match the snapshot, mail arrives at the right mailbox, and each scheduled job runs on exactly one host. A backup becomes useful evidence only after a successful restore test.

1. Inventory the source

Keep a private worksheet with a row for each resource. Record its source, destination, dependencies, transfer method, verification, and whether you will move, replace, or retire it. Include disabled services and resources outside the web directory. Do not omit a resource just because no Lab Guide describes it.

Resource What to record
Application files Code, uploads, hidden configuration, repositories, symlink targets, permissions, and files outside the DocumentRoot
Databases Server and client versions, connection endpoints, names, engines, encodings, collations, roles, grants, extensions, and sizes
Runtimes Language versions, package manifests and lockfiles, native libraries, build steps, and global tools
Processes Supervisor configurations, manually started services, workers, queues, cronjobs, mail fetchers, and their environments
Web Domains, backend paths, listeners, ports, headers, WebSockets, redirects, and certificates
Mail Domains, mailbox mappings, aliases, forwards, catchall, filters, qmail files, and the system Maildir
Integrations SMTP, API credentials, webhooks, callback URLs, remote storage, allowlists, and other external writers

Use the move for spring cleaning

Thinking in inventoried directories gives each file transfer a clear purpose. For each application directory, identify what it contains, which service uses it, where its persistent data lives, and where it belongs on U8. This makes transfers smaller and easier to verify, helps you spot missing uploads or configuration, and avoids overwriting destination settings with an old home directory. One application may span several directories, and several applications may share one: record those relationships before deciding what to move.

A move is also a good opportunity for spring cleaning. Old release directories, abandoned experiments, obsolete backups, and caches can accumulate over years. Decide which directories to migrate, which dependencies or caches to rebuild, and which material to archive separately or retire. You save transfer time and storage, and the destination becomes easier to understand and maintain.

Keep that cleanup separate from deleting the source. An unfamiliar directory or an old modification date does not mean its contents are unused. Check service configurations, scheduled jobs, and symlinks for references; retain a private backup of anything you are unsure about until the restored application has been verified. Record deliberate omissions in your worksheet so you can distinguish cleanup from a missed transfer.

Useful read-only checks on U7 include:

[isabell@stardust ~]$ uberspace web backend list
/ apache (default)
[isabell@stardust ~]$ supervisorctl status
my-app                           RUNNING   pid 12345, uptime 1:00:00
[isabell@stardust ~]$ crontab -l
*/5 * * * * /home/isabell/my-app/sync

These commands are starting points, not a complete inventory. Inspect the application's configuration and the Supervisor configuration files too. A stopped service may still contain data you need. Cron definitions and command lines can contain secrets; keep collected output private.

2. Prepare the destination

Create a separate U8 Asteroid and check its available runtime versions and storage limits. Allow space for the application, initial and final database restores, temporary archives, dependency builds, and backups.

Initially keep the application version compatible with the source. If U8 requires an application upgrade, test that upgrade on the restored copy before changing the source. Treat a database-engine conversion as another migration, not an incidental part of moving hosts.

Map source paths and credentials explicitly. Keep U8's own ~/.my.cnf, ~/.pgpass, SSH access, and platform-managed files. Do not replace them with a copy of the source home directory. Retain application secrets needed to decrypt existing data or validate sessions, while changing database credentials and other host-specific settings to their destination values.

Keep staging files private and prevent test workers, webhooks, and mailers from performing production actions. A restored scheduler can start writing to the original API even when the restored website is isolated.

Rebuild runtime dependencies

U7 and U8 use different operating-system environments. Copy source code and manifests, then rebuild the dependencies that depend on the operating system or runtime. Keep the dependency versions controlled by the application's lockfile.

  • Node.js: reinstall packages on U8. Do not reuse node_modules from U7. Rebuild native addons and application assets; account for global packages too. Use the package manager matching the project's lockfile. See the Node.js Manual.
  • Python: create a new virtual environment with a supported Python version and reinstall dependencies. An old virtual environment is not a portable application backup. See the Python Manual.
  • PHP: check the selected PHP version, extensions, Composer requirements, and application compatibility. Rebuild caches after changing paths or secrets. See the PHP Manual.
  • Other runtimes and binaries: rebuild or obtain compatible releases for U8, including native gems, libraries, and command-line tools. Check the language overview.

For an npm project with a committed package-lock.json, run in the restored project on U8 after selecting a compatible Node.js version:

[isabell8@moondust my-app]$ npm ci
added 42 packages, and audited 43 packages in 2s

Install scripts can execute code and contact other systems. Check the project's build steps before running them with production credentials. Do not omit build dependencies until the required build has completed.

3. Transfer a first copy

Files

Use a new, private destination for each snapshot. For example, on your computer:

[localuser@localhost ~]$ mkdir -m 700 u7-u8
[localuser@localhost ~]$ ls -ld u7-u8
drwx------ 2 localuser localuser 4096 Nov 17 12:00 u7-u8

The following example copies one inventoried directory, ~/my-app, from U7. Choose its real application root, not just a symlink to its public directory. Transfer other data directories separately. Preview the selection first:

[localuser@localhost ~]$ rsync --archive --no-owner --no-group --itemize-changes --dry-run isabell@stardust.uberspace.de:my-app/ u7-u8/app-initial/
created directory u7-u8/app-initial
>f+++++++++ package.json
>f+++++++++ package-lock.json

After reviewing the paths, run the command without --dry-run. Copy the staged files to a new private directory on U8 using SFTP or rsync over SSH, and verify the transfer. Do not publish the staging directory or upload your local backup folder into the DocumentRoot.

Rsync's archive mode preserves symlinks instead of copying their targets. Record and separately transfer data behind links when needed, and adapt absolute links that still point to the source username. This example does not preserve source ownership, ACLs, extended attributes, or hardlink relationships. Handle these explicitly when an application needs them.

Check content checksums, sizes, permissions, and links. A live file copy is not an application-consistent snapshot. Exclude caches only when you know how to regenerate them; use runtime-specific exclusions for dependencies you will reinstall. Database data directories and Unix sockets are not ordinary application files to copy into service.

MariaDB / MySQL

Use a logical dump and a new destination database. Record the source's charset, collation, table engines, triggers, routines, events, and grants first. The MariaDB Manual explains U8's account credentials and database namespace.

For a database whose tables are all InnoDB, with no concurrent schema changes, an example export on U7 is:

[isabell@stardust ~]$ mkdir -m 700 ~/migration-private
[isabell@stardust ~]$ umask 077
[isabell@stardust ~]$ mysqldump --single-transaction --quick --hex-blob --routines --events --triggers isabell_app > ~/migration-private/app-initial.sql && printf 'Export completed\n'
Export completed

For nontransactional tables, use an appropriate lock or application write-stop strategy. A transaction-consistent SQL dump still does not synchronize uploads with their database records. Keep schema-changing jobs stopped during export. A failed command may leave a partial dump; do not import it as a completed backup.

Transfer the successful dump privately to U8. Check for database-selection statements, source-specific DEFINER values, and stored programs needing privileges or changes. Resolve those deliberately instead of globally replacing text in the SQL. Adapt the database charset and collation to the source; the following example assumes utf8mb4 and utf8mb4_unicode_ci:

[isabell8@moondust ~]$ mariadb -e 'CREATE DATABASE isabell8_app CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci' && printf 'Destination database created\n'
Destination database created
[isabell8@moondust ~]$ mariadb isabell8_app < ~/migration-private/app-initial.sql && printf 'Import completed\n'
Import completed

Update the application's database name and credentials. Compare table contents, row counts, relationships, constraints, and application behavior. Row counts alone do not prove that the data matches. If the import fails, preserve the failure evidence and use another fresh database for the corrected attempt.

PostgreSQL

Move from your own U7 instance to U8's managed PostgreSQL using logical dumps. Do not copy the U7 database directory or start a replacement server over U8's managed instance. See the U7 setup and U8 PostgreSQL Manual.

Use the source instance's actual host or socket, port, database, and credentials. Configure PGHOST, PGPORT, PGUSER, and a private password file for that connection before the source example below. Use a pg_dump client that supports the source server version, and check the application's target-version support. Record database locale/collation, extensions, owners, roles, and grants.

On U7, create a private ~/migration-private directory with mode 0700 if you have not already done so. Then export:

[isabell@stardust ~]$ umask 077
[isabell@stardust ~]$ pg_dump --format=custom --file="$HOME/migration-private/app-initial.pgdump" isabell_app && printf 'Export completed\n'
Export completed

Transfer the dump privately. On U8, use its own connection settings and ~/.pgpass, not the source instance's environment. Create a database in the destination namespace:

[isabell8@moondust ~]$ uberspace tool postgresql database add isabell8_app
OK: Added PostgreSQL database 'isabell8_app' to your Asteroid

Inspect the destination's existing schemas and extensions and review the dump's contents before restoring. A new U8 database may already include extension objects. Do not drop the public schema or installed extensions to make an import appear clean. Resolve conflicting objects with a reviewed restore plan; keep application data and platform-provided objects distinct.

For a dump without conflicting preinstalled objects, an example restore is:

[isabell8@moondust ~]$ pg_restore --exit-on-error --single-transaction --no-owner --no-acl --dbname=isabell8_app ~/migration-private/app-initial.pgdump && printf 'Import completed\n'
Import completed

The ownership and ACL options deliberately leave out the old ownership and grants. Recreate the required access, including read-only roles, explicitly. Verify sequences, large objects, constraints, and the extensions your application actually uses, as well as row contents. Locale or collation changes can affect sorting and uniqueness even when the import succeeds. A dump from a newer major version is not a guaranteed downgrade path.

SQLite and other stores

Follow the store's consistent-backup procedure. For SQLite, use its backup facility or stop all writers and handle WAL/journal state correctly; copying only a live main database file may omit committed data. Treat search indexes, object storage, queue state, and encryption keys as separate inventory entries.

WordPress

For WordPress, inventory the database and the full installation, especially wp-content (uploads, plugins, themes, and must-use plugins), wp-config.php, and .htaccess. Include any uploads stored outside the installation. Preserve the table prefix and authentication salts; adapt database credentials and host-specific paths on U8. Check PHP compatibility for plugins and themes as well as WordPress itself.

Use the U8 WordPress Guide for destination PHP, web, and cache settings. Restore the existing installation and database instead of running wp core install or generating a replacement configuration. Keep WP-Cron, system cronjobs, automatic updates, and plugin workers from changing the snapshot or sending production notifications during rehearsal. During the final write-stop, also block comments, uploads, API writes, and shop orders.

If the public URL stays the same, retain it. If it changes, review home, siteurl, configuration overrides, and URLs stored by plugins. Use WP-CLI search-replace for serialized data rather than replacing strings in an SQL dump. For a single-site destination copy, preview a URL change like this:

[isabell8@moondust html]$ wp search-replace 'https://old.example' 'https://app.example' --all-tables-with-prefix --skip-columns=guid --dry-run
...
Success: 42 replacements to be made.

Review the affected tables and take a destination backup before running without --dry-run. Multisite needs its own network/domain mapping plan; follow the WordPress migration documentation. Test login, media, permalinks, forms, and important plugin workflows. Recreate any Redis service and clear application caches after adapting their settings.

Nextcloud

Inventory Nextcloud's database, application and custom-app directories, config/config.php, and complete data directory, including hidden files. Record external storage, encryption keys, Redis, SMTP, and background jobs. Preserve the instance identity and secrets; copying users' visible files alone does not preserve shares, calendars, contacts, or file metadata.

Use the U8 Nextcloud Guide for destination PHP and service settings. Restore the existing version with compatible apps; do not run occ maintenance:install. Follow the Nextcloud server migration instructions for your installed version.

At the final write-stop, enable maintenance mode on U7, from the existing Nextcloud installation directory:

[isabell@stardust html]$ php occ maintenance:mode --on
Maintenance mode enabled

Allow clients to notice the pause, stop background jobs and remaining requests, then capture matching database, configuration, and file snapshots. Preserve file timestamps. Keep the destination in maintenance mode during restoration.

Plan the data-directory path before moving

Nextcloud discourages changing its data-directory location: database references can depend on it. Different Asteroid usernames may force a path change. Resolve this using Nextcloud's version-specific guidance and a tested restore; changing only datadirectory in config.php is insufficient.

Adapt database, trusted-domain, URL, cache, and SMTP settings. Verify login, WebDAV sync, downloads, shares, calendars, contacts, and encrypted files where applicable. Release maintenance mode on U8 at cutover and enable its background jobs only once the source jobs are stopped.

Hugo

A Hugo site has two inventories: its editable project and its generated website. Preserve content, configuration, layouts, themes and submodules, assets, static files, and module or package lockfiles. An HTML-only copy can keep the website online, but does not preserve the project needed to publish future changes.

Use the U8 Hugo Guide to prepare the build environment, initially matching the source Hugo version and required variant. Keep the project outside the DocumentRoot. If builds happen on your computer or in CI, keep that workflow and change its deployment destination; Hugo does not need to run on the Asteroid just to serve the generated files.

Check baseURL, language paths, aliases, and deployment scripts. Create a new, empty output directory and build into it before copying its contents to the intended U8 DocumentRoot. Example, from the restored project:

[isabell8@moondust my-site]$ hugo --destination "$HOME/migration-private/hugo-preview"
Start building sites …
...
Total in 120 ms

Follow the Hugo build documentation for the installed version. Avoid pointing a cleanup build at a shared webroot; it can delete unrelated files. Pause publishing during the final copy, then verify assets, old deep links, redirects, feeds, and sitemap URLs. Resume the publisher against U8 only after cutover. Migrate separately any dynamic form handler or other backend the static pages use.

Joomla

Back up the full Joomla installation and a matching database snapshot. Include configuration.php, .htaccess, uploaded media, templates, and extensions; check for custom storage outside the webroot. Follow Joomla's backup instructions and use a PHP version supported by the installed Joomla release and extensions. Keep upgrades separate from the initial host move.

Before the final snapshot, take the site offline and stop scheduled tasks, queues, and any other writers. Offline mode alone is not a guarantee that administrator sessions or integrations have stopped writing. Restore into a fresh U8 database and the intended DocumentRoot; do not run a new installation wizard against the restored data.

Update the database host, name, user, and password in configuration.php. Review the table prefix, log and temporary paths, cookie settings, and any explicit live_site value. Keep the existing site secret. Configure mail sending for U8 and remove stale filesystem paths from extension settings.

Test administrator login, articles, media, search-friendly URLs, menus, forms, and extension-specific data on the isolated copy. Clear application caches after adapting the configuration. At cutover, bring the destination online and activate its scheduled work while the source remains paused. Keep backup archives and any restoration scripts outside publicly reachable directories.

DokuWiki

DokuWiki's standard storage is file-based. Inventory the full installation, including conf, data, lib/plugins, lib/tpl, and hidden files. Preserve page and media revisions, metadata, user accounts, and access-control rules, not just the current page text. Check savedir and other path overrides for data outside the installation. Plugins or an external authentication backend may introduce databases or services that need separate migration.

Stop edits, uploads, administrative changes, and plugin jobs for the final snapshot. Restore the files with the existing DokuWiki, plugin, and template versions on a compatible U8 PHP version. Keep backup archives outside the DocumentRoot. Review conf/local.php, URL rewriting, authentication settings, and absolute paths; do not run the installer over the restored wiki.

Preserve DokuWiki's access-protection files. In particular, the supplied data/.htaccess blocks direct access to stored files. Confirm on your destination that private configuration and raw page data cannot be fetched directly, even if they live under the web tree. A working wiki login does not prove that these files are protected. Consult the DokuWiki security guidance for your web-server layout.

Verify login as both a reader and an editor, restricted namespaces, older page revisions, media downloads, search, and plugin features. Test an edit and upload on the isolated destination and check permissions. Re-enable production writes only at cutover, leaving the source paused. Follow DokuWiki's server-move guidance for additional version-specific steps.

4. Recreate services and schedules

Replace Supervisor-managed services with systemd user services. Compare the actual behavior, not only the command line:

U7 setting or behavior What to check on U8
Command, directory, environment New paths, executable, working directory, secrets, and runtime selection
Autostart and autorestart Enablement, restart policy, failure behavior, and restart delay
Stop signal and timeout Graceful shutdown and whether child processes stop too
Multiple processes and groups Number of instances, dependencies, and startup ordering
Log files Journal or application logs, access permissions, and retention

Prepare the settings before cutover, but keep production workers, mail fetchers, and schedulers stopped. The systemd Manual explains the service CLI and custom units.

Creating a service starts it

uberspace service add starts and enables the service immediately. Use it during staging only when the command is isolated from production writes and external effects. Otherwise defer creation until the source writers are stopped and the destination is ready. For more complex requirements, prepare inactive user-unit files as described in the Manual.

Example: migrate a Node.js service

Assume your existing application runs in the foreground with node server.js, reads HOST and PORT from its environment, and exposes /health. Its U7 Supervisor file, ~/etc/services.d/my-app.ini, might contain:

[program:my-app]
directory=/home/isabell/my-app
command=node server.js
environment=NODE_ENV="production",HOST="0.0.0.0",PORT="3000"
autostart=true
autorestart=true
stopsignal=TERM
stopwaitsecs=30
stopasgroup=true
killasgroup=true

First transfer the application to ~/my-app on U8, select a compatible Node.js version, and reinstall its dependencies with npm ci as described above. Adapt its database connection and other private configuration to the destination. Keep the application in your home directory: this HTTP service uses a web backend rather than Apache's DocumentRoot.

During the final write-stop, stop the service on U7:

[isabell@stardust ~]$ supervisorctl stop my-app
my-app: stopped

Also set autostart=false in its source Supervisor configuration and apply the change so a Supervisor restart cannot start the old writer again. Keep the source configuration for your return plan. Complete the final data transfer before starting the destination service.

Once the destination is ready to run, create the replacement on U8:

[isabell8@moondust ~]$ uberspace service add my-app "node server.js" --workdir /home/isabell8/my-app --env NODE_ENV=production --env HOST=0.0.0.0 --env PORT=3000 --directive Restart=always --directive RestartSec=5 --directive KillSignal=SIGTERM --directive TimeoutStopSec=30 --directive KillMode=control-group
...
[isabell8@moondust ~]$ systemctl --user show my-app.service -p ActiveState -p UnitFileState
ActiveState=active
UnitFileState=enabled

Here --workdir replaces Supervisor's directory, and --env supplies the application environment. Restart=always preserves the intent of autorestart=true; an explicit stop still stops the service. The stop signal, 30-second timeout, and control-group cleanup provide graceful termination followed by cleanup of remaining child processes. The service CLI enables startup automatically. Keep secrets out of command-line arguments; use your application's protected configuration or a private systemd environment file.

Verify the listener and inspect the journal on U8. Example output for this application:

[isabell8@moondust ~]$ curl --fail --silent --show-error http://127.0.0.1:3000/health
{"status":"ok"}
[isabell8@moondust ~]$ journalctl --user -u my-app.service -n 10 --no-pager
Nov 17 12:00:00 moondust systemd[1234]: Started my-app.service.
Nov 17 12:00:00 moondust node[5678]: Listening on 0.0.0.0:3000

Use your application's actual health endpoint and expected response. Recreate its web backend for port 3000 and the intended domain/path, then verify it through the test hostname before switching production traffic. A local health response does not verify the public route or application data. If startup itself triggers production jobs, keep those disabled until the cutover conditions in the following sections are met.

Systemd commands are not implicitly shell scripts: shell expansion, redirection, and pipelines need deliberate handling. During rehearsal, test start, stop, failure recovery, and child-process cleanup with isolated data; a successful startup alone is not sufficient.

Scheduled jobs

Transfer cronjobs explicitly or convert them to timers. Preserve timezone, working directory, environment, locking, and overlap behavior. Decide whether a timer should catch up after downtime. Do not enable a destination job while its source counterpart still runs. See cron and systemd timers.

5. Prepare mail and application sending

Follow Migrate mail addresses for ownership validation, mailbox creation, IMAP copies, and the later MX switch. U7 domains may share a mailbox; U8 addresses need an explicit mapping. Copying ~/Maildir or ~/users into the U8 home directory does not populate U8's centrally managed mailboxes. Include the old system Maildir in your inventory and arrange an IMAP or supported mail import if it contains messages you need to keep.

Inspect qmail configuration on U7:

[isabell@stardust ~]$ uberspace migration qmail check --assist
...
.qmail-postmaster
  error: The file contains a username that is not the current user
...

Work through each finding using the qmail migration reports. The checker identifies configuration problems; it does not migrate messages or prove that your destination routing works. Map aliases, forwards, catchall, subaddressing, rejection/discard rules, Maildir destinations, maildrop filters, and command pipes to explicit destination behavior. Arbitrary qmail programs are not automatically translated into Sieve or a service. Avoid removing a working source rule before its replacement has been tested.

Configure applications to use the destination's SMTP hostname, TLS settings, and an authorized mailbox identity. The U8 system mailbox can be used for application sending once its credentials and sender address are configured; retain its intended forwarding behavior. Do not leave a hidden SMTP dependency on the old host. Check authentication and send to and from an external mailbox you control. See mail access, mail addresses, and Sieve filters.

Mailman installations

Treat Mailman Core, Postorius/HyperKitty, databases, archives, attachments, configuration secrets, queued messages, and incoming/outgoing delivery as one application. A list-members export is not a complete backup.

Compare the U7 Mailman Guide with the U8 Mailman Guide. Their database and delivery setups can differ. Preserve compatible database engines for the host move when possible; a change from SQLite or MariaDB to PostgreSQL needs a separately tested data conversion. Do not feed a SQL dump to a different database engine and assume it is a migration.

Pause ingestion, Core/Web workers, and scheduled tasks for a coordinated final snapshot. Retain queues without replaying already delivered messages. Verify list identities and members, archive links and privacy, attachments, moderation, subscriptions, bounces, and envelope-recipient handling on the new delivery path. Keep external delivery isolated during rehearsal and activate only one production delivery chain. The U8 installation Guide is a reference for the destination, not proof that an existing Mailman installation has been migrated.

6. Verify the restored application

Use an isolated test hostname or controlled name resolution.

Check the DocumentRoot

The DocumentRoot is the directory Apache exposes as your website. On U8, the standard location is /var/www/virtual/<username>/html; ~/www points to /var/www/virtual/<username>, not directly to html. Use the destination username when adapting paths and symlinks.

Each added web domain has a directory at /var/www/virtual/<username>/<domain>, initially a symlink to html. Inventory any separate DocumentRoots on U7 and recreate the intended mapping on U8; otherwise domains that should serve different sites may show the same content. Do not remove a shared target while other domains still point to it.

Apache cannot access directories in /home, so a DocumentRoot symlink into your home directory will not work. For a PHP application with a public directory, place the application under the destination's web tree, for example /var/www/virtual/isabell8/my-app, and point the intended DocumentRoot only at my-app/public. Keep configuration, database dumps, and other nonpublic files outside every published directory. Follow the DocumentRoot Manual for the layout and permissions, and verify each domain separately. Applications served by their own HTTP process also need the correct backend mapping and their own static-file settings.

Test application behavior

A rehearsal should cover:

  • Content checksums, database contents and relationships, and required file permissions.
  • Login, uploads and downloads, authenticated APIs, and relevant write operations against isolated data.
  • Services, their shutdown/restart behavior, queues, and schedules.
  • Mail folders, dates, flags, attachments, address mappings, and delivery.
  • Canonical URLs, cookies, callbacks, redirects, WebSockets, and external integrations.

A process marked active or an HTTP 200 response is not a complete application test. Write down remaining gaps. Do not disable certificate checking to make a failed HTTPS check pass. Certificates for the final domain may only become available after DNS points at the destination; include that check in cutover.

7. Freeze writers and transfer the final state

Agree on the maintenance window with whoever changes DNS. If reducing TTLs, change them early enough for the previous TTL to expire before cutover. Save the original DNS and routing settings.

  1. Pause source web/API writes, workers, cronjobs, mail fetchers, and external writers. Keep administrative access and backups available.
  2. Wait for in-flight requests, transactions, and jobs to finish. Record how incoming messages and queue items will be retained during the pause.
  3. Capture application-consistent final file and database snapshots. Use new backup paths and new destination databases; retain the initial restore.
  4. Reconcile changed and deleted files, not only newly uploaded ones. Repeating the earlier rsync copy without deletion can leave stale files. A fresh final staging tree is easier to review than an unexamined --delete operation.
  5. Restore the final state, update destination configuration, rebuild caches, and compare the result while writers are still stopped. Verify file content and database data as well as object and row counts.
  6. Prepare the destination's public backend. Keep schedulers and consumers stopped until their cutover conditions are met.

Incoming mail needs a separate final and follow-up sync; it cannot generally be frozen in the same way as an application's writers.

8. Switch traffic and resume work

Register the final web domain and backend on U8 using the domain and backend instructions. Resolve any domain ownership or platform restriction before cutover. Do not delete the source Asteroid to try to free a name.

Use the destination's actual proposed addresses. On U8, for example:

[isabell8@moondust ~]$ uberspace web domain show app.example
Domain: app.example

Use the following values for your DNS:

$ORIGIN app.example.
@  IN  A     192.0.2.20
@  IN  AAAA  2001:db8:2::20

The IPs above are documentation examples, not Uberspace addresses. Change both A and AAAA to the values returned for your destination. Account for CNAMEs, proxies, and CDN routing if used. Switch MX and mail-related records separately as described in the mail migration Howto.

Check authoritative DNS answers and ordinary resolver answers, then make real HTTPS requests under the final name. Verify the certificate and data that identify the destination, not only the response status. Different resolvers can temporarily reach different hosts. Keep source writes blocked throughout this period, including writes from clients holding old connections.

Once the final hostname and application checks succeed, activate destination workers and schedules. Confirm one normal run and inspect its effects. Keep source jobs stopped. Redirect old web addresses only where appropriate; a redirect is not a universal replacement for POST requests or WebSockets, and redirecting a stale request to the same hostname can create a loop.

For mail, test an external delivery path. Sending from the old host to a domain it still considers local may bypass the changed MX and give a misleading result. Use an independent sender you control, check the destination mailbox, and repeat the source-to-destination sync for late arrivals. Preserve new mail already on U8. Do not delete a U8 mail domain as a routing rollback: that also removes its associated addresses and mailboxes.

9. Observe and decide when to retire U7

Watch application errors, queue progress, scheduled runs, mail delivery, and new data on U8. Check the source for remaining traffic and late messages. Confirm that application SMTP, APIs, file paths, and callbacks no longer depend on the old host. Keep backups and the source for the agreed retention period. An old .uber.space redirect or another remaining dependency may still need that source account.

Before destination writes begin, returning to the preserved source may be straightforward. After U8 has accepted new writes, switching DNS back is not sufficient. Stop destination writers, retain both data sets, and plan a tested return transfer or conflict resolution. Include new uploads, database changes, mail, and queued work. Do not replay external effects such as notifications or payments. A schema upgrade or database-version change may prevent a direct return; repairing the destination can be the safer option.