How to Write a Website Migration Specification Without Data Loss

The website migration specification should define not only the migration itself, but also the scope of data to be transferred, requirements for the target environment, synchronization procedure, acceptable downtime, access permissions, backup procedures, restore verification, acceptance criteria, and rollback scenario. The result must be measurable: after the migration, it should be clear which data must be present on the new server, who is responsible for each stage, and which conditions indicate that the migration is complete.

1. Document the Source and Target Infrastructure

Do not use wording such as “move the website to a new server” without a technical description of both environments. The contractor needs to understand which components currently exist and which requirements the target infrastructure must meet.

For the source system, specify:

• the domain and any subdomains in use;
• the hosting type: shared hosting, VPS, dedicated server, containerized environment, or another setup;
• the operating system, if it affects the migration;
• the web server, reverse proxy, or other component that accepts HTTP requests;
• the DBMS in use;
• the application runtime environment;
• application and user file directories;
• background jobs, queues, schedulers, and standalone services;
• external storage systems, CDNs, and integrations;
• how secrets and environment variables are stored, without including the secrets themselves in the specification.

For the target environment, also document compatibility requirements. If they are critical to the application, specify acceptable runtime and DBMS versions, required extensions, system libraries, and services. List resource requirements separately: available disk space, memory, CPU resources, process or container limits, and other constraints that affect website operation.

Do not invent these values in advance. They should be determined from the actual application configuration, existing documentation, and inventory results.

Do not include production passwords, private keys, API tokens, or other secrets in the specification. Specify only the required access permissions, the party responsible for providing them, and the secure delivery channel.

2. Define Access Permissions and Responsibilities

Even a technically correct migration can be blocked if it is not clear in advance who is responsible for providing the required permissions. The specification should contain a dedicated section covering access, deadlines, and responsible parties.

For each type of access, it is useful to specify not only when it must be provided but also the required permission level. If the contractor must not have permission to modify DNS or the production database, state this explicitly.

3. List All Data That Must Be Preserved

The requirement “without data loss” should be defined through a specific list of objects. For a web project, this usually includes the database, application files, user uploads, and configuration, but the final scope depends on the architecture.

If some data will not be migrated, document the exclusion explicitly. For example, a temporary cache may be excluded only if the application can safely recreate it.

4. Define the Data Cutoff Point

If the production website continues to accept orders, requests, comments, or uploads while data is being copied, the initial copy quickly becomes outdated. The specification must therefore define how changes made during the migration are handled.

Possible approaches include:

• temporarily disabling writes on the old server during the final copy;
• performing an initial copy followed by a final synchronization of changes before cutover;
• using a replication or synchronization mechanism supported by the architecture.

Also specify who authorizes the start of the final stage, how much downtime is acceptable, and which user operations must be temporarily restricted. If scheduled downtime is unacceptable, that is a separate technical requirement.

5. Describe Backup and Restore Verification

Before modifying the production system, create a backup of the data that may be affected by the migration. The specification should define the backup contents, storage location, retention period, and verification method.

Before the final cutover, the contractor creates a backup
of the current database and the files required to restore the website.
The backup is stored separately from the application instance being modified.
Before cutover, verify:
the presence of all declared backup components;
that the files can be read;
that the backup matches the agreed data scope.
For critical projects, perform a test restore
in a separate agreed environment and verify that the application starts.
If a test restore is not included in the scope of work, this must be
explicitly documented in the specification as a limitation of the backup
verification procedure.
The backup may be deleted only after the end
of the agreed observation period.

Checking that an archive or dump exists does not prove that it can actually restore a working system. Therefore, for projects where recoverability is a mandatory requirement, a test restore should be included in the acceptance criteria.

6. Divide the Migration Into Controlled Stages

1. Inventory. Confirm the scope of the application, data, integrations, and services.
2. Access provisioning. Verify that all permissions required for the next stages are available.
3. New server preparation. Configure a compatible environment and the required resources.
4. Initial copy. Transfer data that can be copied in advance.
5. Test launch. Verify the new instance without directing primary traffic to it.
6. Cutoff point. Restrict writes or start the agreed synchronization mechanism.
7. Final synchronization. Transfer the latest changes.
8. Traffic cutover. Direct users to the new infrastructure.
9. Acceptance. Verify data, functionality, integrations, and background processes.
10. Observation. Keep the old environment and backups available until the agreed observation period ends.

7. Define Data Checks Before and After Migration

To make acceptance objective, define control metrics in advance. For a database, these may include the presence of required schemas and tables, row counts in critical tables, control records, timestamps, or related datasets, provided such checks are appropriate for the data model in use.

For files, you can verify critical directories, the presence of files created shortly before the cutoff point, the ability to read an existing user file, and the ability to create a new one.

Comparing only the number of files or rows is insufficient: equal object counts do not prove that their contents are identical. Quantitative checks should therefore be supplemented with functional scenarios.

8. Create a Functional Acceptance Scenario

The verification checklist should reflect actual website functionality. It may include:

• opening the home page and critical internal pages;
• verifying HTTPS;
• signing in with a test account;
• creating and then reading a test object;
• uploading and retrieving a file;
• submitting a form;
• checking the administration interface;
• checking the API;
• executing background jobs;
• verifying approved external integrations.

For payment, email, SMS, and other external systems, define a safe verification method in advance. Do not perform real financial transactions solely for acceptance testing unless the project explicitly provides for such a scenario.

9. Describe DNS and Traffic Cutover

If the migration involves DNS changes, specify who is responsible for the DNS zone, which records will be changed, and when the cutover will occur. It is impossible to guarantee identical propagation times for all users because the result depends not only on zone settings but also on resolver-side caching.

If the current DNS configuration and provider rules allow this strategy, the plan may include reducing the TTL of the records to be changed in advance. This should be done ahead of time and only after checking the current TTL value and the behavior of the DNS service in use. Once the new infrastructure is stable, the TTL can be restored to the value adopted for the project.

The acceptance criterion should not be based on a promise such as “the website will work for everyone within N minutes,” but rather on the correctness of DNS records and confirmation that requests are being directed to the new infrastructure from the agreed verification points.

If a CDN, load balancer, or reverse proxy is used, describe the actual cutover mechanism instead of assuming a universal DNS-based scenario.

10. Define the Rollback Scenario

Before work begins, document:

• which events trigger a rollback;
• who makes the rollback decision;
• how traffic is returned to the old system;
• what happens to data created after cutover;
• which backups must be retained;
• how long the old infrastructure must remain available.

Simply directing traffic back to the old server may result in the loss of new records. The reverse synchronization procedure or a temporary write restriction during an emergency rollback must therefore be defined according to the capabilities of the application.

11. Make Acceptance Criteria Measurable

The phrase “the website works without errors” is too vague. The specification should define a specific observation period and a list of events considered critical. The duration of the period and acceptable metrics should be based on project requirements rather than a universal value.

The work is considered complete after the following conditions are confirmed:
The agreed domain directs traffic to the new infrastructure.
HTTPS works with the agreed certificate configuration.
Critical pages and the administration interface are accessible.
Control data recorded before migration is present.
New data can be created successfully and read again.
User files are accessible, and new uploads work.
Agreed integrations pass acceptance checks.
Required background processes execute in the new environment.
During the agreed observation period, application
and infrastructure logs are monitored.
The specification defines in advance a list of critical events, such as
website unavailability, requests that cannot be processed, failure of a required
background process, or errors that result in data loss.
The acceptable level of non-critical errors, if relevant
to the project, is defined as a separate measurable condition.
Rollback conditions and the backup retention period are documented.

Do not define an arbitrary number of acceptable errors solely to create a formal criterion. If the project requires numerical thresholds, they should be agreed based on its operational requirements and existing monitoring system.

Specification Structure Template

1. Objective: migrate the specified website while preserving the agreed data scope.
2. Scope of work: what is and is not included in the migration.
3. Source infrastructure: servers, application, DBMS, storage systems, and integrations.
4. Target infrastructure: component versions, dependencies, resources, and constraints.
5. Access: SSH, control panels, DNS, CDN, repositories, and the parties responsible for providing access.
6. Data scope: databases, files, configuration, and background processes.
7. Backup: contents, storage, verification, and whether a test restore is required.
8. Migration procedure: initial copy, cutoff point, synchronization, and cutover.
9. Acceptable downtime: the agreed limit or a requirement for operation without scheduled downtime.
10. Data verification: control metrics before and after migration.
11. Functional acceptance: specific user and administrative scenarios.
12. Traffic cutover: DNS, CDN, load balancer, or another actual mechanism.
13. Rollback: triggers, responsible parties, and procedures for handling new data.
14. Observation: duration, monitored logs, and critical events.
15. Completion: measurable criteria for a successful migration.

Final Checklist Before Approval

• Project domains and subdomains are listed.
• The source and target infrastructure are described.
• Required versions, dependencies, and resource constraints are documented where critical.
• Responsible parties are assigned for SSH, hosting, DNS, CDN, and repositories.
• Access provisioning deadlines are specified.
• A complete list of data to be migrated and exclusions has been prepared.
• The handling of new data created during migration is defined.
• Backup rules are specified.
• It is stated whether a test restore of the backup is required.
• A test launch before user cutover is included.
• Data control metrics are defined.
• A functional acceptance scenario has been prepared.
• For DNS-based cutover, reducing TTL in advance has been considered where applicable.
• Rollback conditions and procedures are defined.
• An agreed observation period after cutover is specified.
• A list of critical events and, where necessary, an acceptable level of non-critical errors is defined.
• The work is completed only after all measurable acceptance criteria are satisfied.

This type of specification remains applicable across different operating systems, web servers, DBMSs, and hosting platforms. Specific migration commands, replication parameters, software versions, resource values, and DNS settings should be added only after inventorying the actual infrastructure and verifying the requirements of the components in use.