Migrate
Migrate a service from one node to another while preserving data integrity. The migration task orchestrates backup, stop, restore, start, and DNS update steps across source and target nodes.
Configuration
Data items carried during migration must have both a backup and a restore action in data_protect. Declare them in migrate:
name: my-app
nodes:
- main
data_protect:
data:
- name: uploads
backup:
strategy: files.copy
include:
- ./data/uploads
restore:
strategy: files.copy
include:
- ./data/uploads
migrate:
data:
- name: uploads| Key | Type | Required | Description |
|---|---|---|---|
name | string | Yes | Must reference a data_protect.data[].name with both backup and restore actions. |
enabled | bool | No | Enable or disable migration for this item. |
Execute migration
Web UI:
- Open the service detail page.
- Use the migration controls to select source and target nodes.
- Click Migrate.
CLI:
composia service my-app migrate --source main --target edge-1 --wait --follow --timeout 30mMigration steps
- Stop source instance — run
docker compose down, remove Caddy configuration. - Export data — run a backup task on the source node for each configured data item.
- Reload Caddy on source — remove the proxy entry from the source Caddy instance.
- Restore data on target — run a restore task on the target node for each data item.
- Deploy on target — run
docker compose up -d, sync Caddy configuration. - Reload Caddy on target — apply the proxy entry on the target Caddy instance.
- Update DNS — update DNS records to point to the target node.
- Write configuration — update
nodesincomposia-meta.yaml, commit to Git.
Considerations
- The service must be deployed on the source node and the target node must be online.
- Before starting migration, provision matching business-service and Rustic configuration on the target agent, and ensure the source files also match the controller. Backup and Restore verify local files without installing bundles. A missing or divergent target configuration will fail the Restore step after the source has already stopped; do not rely on migration to bootstrap those files.
- Configuration checks do not require target containers. Prepare file-based restore targets before migration; they must already exist. Keep persistent data outside directories replaced by Deploy/Update, which retain their existing bundle-installation behavior.
- Migration causes brief downtime. Perform during off-peak hours.
- Source instance is stopped before data transfer to ensure consistency.
- For databases, use export strategies (
database.pgdumpall/database.pgimport).
Rollback
State rollback is currently available in the Web UI only. Open the migration task details, choose the recovery actions that match the failed step, and start rollback there.
| Action | Description |
|---|---|
deploy_source | Redeploy the service on the original source node. |
stop_target | Stop and clean up the service on the target node. |
rollback_dns | Sync DNS records back to the source node. |
The CLI does not have a task rollback command yet. You can still inspect and follow the migration task with:
composia task wait --follow --timeout 30m <task-id>See also
- Backups — Rustic setup and backup configuration.
- Service Configuration —
data_protectandmigratefield reference.
Last updated on • alexma233