Server Migration & Modernization Guide

This is an original planning guide. It is not a vendor manual, an official standard, or legal advice. Example addresses use documentation ranges. Review every command before you paste it.

Parallel, proof, then the name change

A migration is a new host or a new software version that takes over a job. The safe shape is parallel: the old service keeps the name and the users, the new service is built from the provisioning guide, and you test it on an address or a name that is not the production name. Cutover is the short window where the name moves. Rollback is moving the name back, which only works if the old host is still up and still has the data.

Web servers have converters on this site: Apache rewrite files to Nginx, virtual hosts to Nginx, Nginx to Caddy, Apache to Caddy, IIS web.config to Nginx, Nginx to Traefik. A converter output is a draft. The web server guide and the vendor pillar still apply. You fetch the test page on the new host before any DNS change. You do not convert and cut over in one motion because the draft looked familiar.

Data moves before the name moves. A file copy, a replica, or a restore from the backup guide lands on the new host and is checked. The last incremental copy happens in the window, with users paused or with a method you tested. A copy you started and never compared is a guess.

DNS and load-balancer names have a TTL. Lower it before the day, to a value you chose, so the cutover is not waiting on yesterday's hour-long cache. Raise it again after the rollback period. The cloud companion on the other desk is the seven-R vocabulary if this move is also a move off a site. This page still wants the old host up.

A lab site moved to a second host

The old lab web host serves the test page on its current address. The new host is built from the provisioning file and the web server guide, on a different address. Copy the document root. Diff it. Fetch the page from the new address. The fetch must match. If a converter produced the new config, the config test passes before that fetch.

Only then, in a lab DNS or a hosts file you control, point the test name at the new address. Fetch by name. Then point it back and fetch again. That is the rehearsal of cutover and rollback. Production is the same two moves with a lower TTL and a person watching the old host.

Write the data that did not move: databases, mail queues, uploaded files, scheduled jobs. Each one is a line. A web config conversion does not move them. The scheduling guide rebuilds the job on the new host, and you disable it on the old host only after the new job has run once.

Keep the old host for the rollback period you named, not forever and not for five minutes. A day or a week is a decision. Backups continue on whichever host holds the live data.

A change you can finish

The production window is: last copy, config test, fetch by address, name change, fetch by name, watch. If the name fetch fails, change the name back. Do not debug the new host while the name points at it and users are the testers.

Rollback is the name change reversed, and it depends on the old host still serving. Do not power the old host off in the window.

Inventory the service, the data, the jobs, and the name.
Build the new host beside the old one.
Copy data and diff or checksum a sample.
Pass the new service's own test and fetch it by address.
Lower TTL before the day if a name will move.
Move the name. Fetch by name. Move it back if that fetch fails.
Leave the old host up for the rollback period, then decommission it in a later ticket.

Mistakes that outlive the command

server migration fails in the same few ways. Each one looks finished on the day you type it. The list is here so the ticket can forbid them before the window, not so you can recognise them in an incident review.

Powering off the old host in the cutover window.
Trusting a converter draft without a fetch.
Moving DNS before the data copy finishes.
Forgetting a cron job or a mailbox.
A TTL you did not lower, then a rollback nobody can see yet.
Two changes, such as a new OS and a new web server and a new domain, in one window.
A hosts-file test called a production proof.
Decommissioning the old host before the rollback period you agreed.

Decisions to write down before the window

One decision for server migration: Old and new run in parallel until the name fetch works. The converter output is a draft. The vendor pillar's config test passed. A sample of the data was compared. TTL was lowered before the window if DNS is the name. Rollback is the name pointed back, and the old host is still serving. Jobs and mailboxes are lines in the inventory, not assumptions. One major change. A new platform and a new application are two migrations. The rollback period is a date. Decommission is after that date. Backups follow the live data. The lab rehearsal of both directions happened. And a second person saw the fetch by name and knows how to point the name back.

Migration checks before the name moves

Confirm this before you call the change done: The inventory lists data, jobs, and names. The new host answers by address. The config test for the new server passed. A data sample matches. Converter output was diffed and secrets were not in it. TTL is the lowered value, if DNS moves. The old host is up and still serving. The rollback is a name change you have rehearsed. Scheduled jobs have an owner on the new host and are not double-running. The rollback period date is written. A second person saw the address fetch. No second major change is hiding in the window. Backups will run against whichever host is live after cutover. The hostname in the prompt matches the hostname in the ticket for server migration. The result line includes the time and the person, not only the command. You can point at the rollback value without searching a chat history. And done is a sentence a second person can repeat: the proof for server migration happened, and the next host is not started early. If one of those fails, stop.

Tools for this guide

These tools run in the browser on this site. They do not log into your machines.

Guides in this cluster

These supporting pages belong to this pillar.

Companion: Cloud: Cloud Migration Strategies (7 Rs).