Migrating a Node to a New Server

This guide walks node operators through migrating a Core Channel Node (CCN) to new physical hardware while minimising downtime, preserving on-chain identity, and protecting node score and rewards.

CRN migration

A dedicated guide for migrating a Compute Resource Node (CRN) is in progress and will be published in a future update.

Plan for downtime

Migration will cause a brief interruption. Schedule it during a low-activity window and monitor your node score before and after. Some score recovery time is normal after any restart.

General Principles

• On-chain identity does not move with the server. A node's identity is its Ethereum address registered in the node registry — that stays the same. What changes is the underlying machine serving traffic for that identity.
• Keep the same public IP when possible. Other nodes' P2P trust is tied to the IPv4 address and node keys. Migrating to the same IP is the smoothest path.
• Always back up before you migrate. Treat the migration as a backup/restore exercise. See the Backups guide first.

---

Migrating a Core Channel Node (CCN)

1. Prepare backups on the old server

Follow the Backups guide to capture what you need. There are two supported migration strategies — pick the one that fits your situation:

Required (minimal migration)

At a minimum, you must migrate:

• pyaleph P2P keys — pyaleph/keys/* (critical: other nodes trust these keys; losing them is equivalent to creating a new node identity)
• config.yml — your pyaleph configuration file
• docker-compose.yml — and any customised overrides you maintain

With only these files, the new node will come up with the correct identity and resynchronise all state from the network from scratch.

• Pros: much smaller transfer; no risk of carrying over a corrupted database or stale file storage.
• Cons: full resync typically takes 24 hours to one week depending on CPU, disk, and network throughput. During resync the node is not serving fully, but this does not impact your node score — the score only penalises unresponsive or misconfigured nodes, not a node that is legitimately catching up.

Recommended (fast recovery)

For the shortest downtime, also back up the data volumes in addition to the files above:

• PostgreSQL database — Docker volume pyaleph-postgres
• pyaleph local storage — Docker volume pyaleph-local-storage
• IPFS (Kubo) data — Docker volume pyaleph-ipfs

With a recent, consistent copy of these volumes the new node can resume in minutes to hours rather than days. Ensure backups are consistent: either stop the node before snapshotting, or use a filesystem with atomic snapshots (BTRFS/ZFS/QCOW).

IPFS identity (Kubo) — when to keep or regenerate

The IPFS daemon (Kubo) has its own identity key, stored in the Kubo config file inside the pyaleph-ipfs volume, typically at:

/var/lib/docker/volumes/pyaleph_pyaleph-ipfs/_data/config

Whether you should migrate this file depends on the new IP address:

• Same public IP on the new server — back up and restore the Kubo config file so the IPFS peer ID stays the same. Other IPFS peers will continue to recognise your node without rebuilding connectivity.
• New public IP on the new server — you can still keep the Kubo config if you want to, but it is not required. If the file is not migrated, Kubo will generate a fresh identity on first start. This is harmless: the IPFS network will discover your new peer ID automatically.

2. Provision the new server

On the destination machine, install Docker and pyaleph following the CCN installation guide, but do not start the node yet.

3. Stop the old node

cd /path/to/pyaleph
docker compose down

Take a final incremental snapshot of the database and file storage at this point — this is the cleanest state to restore from.

4. Transfer data to the new server

Copy the required files to the new machine. The P2P keys and configuration are mandatory:

rsync -av /path/to/pyaleph/keys/ user@new-server:/path/to/pyaleph/keys/
rsync -av /path/to/pyaleph/config.yml user@new-server:/path/to/pyaleph/config.yml
rsync -av /path/to/pyaleph/docker-compose.yml user@new-server:/path/to/pyaleph/docker-compose.yml

If you chose the recommended (fast recovery) path, also transfer the data volumes:

rsync -av /var/lib/docker/volumes/pyaleph_pyaleph-postgres/ \
  user@new-server:/var/lib/docker/volumes/pyaleph_pyaleph-postgres/
rsync -av /var/lib/docker/volumes/pyaleph_pyaleph-local-storage/ \
  user@new-server:/var/lib/docker/volumes/pyaleph_pyaleph-local-storage/
rsync -av /var/lib/docker/volumes/pyaleph_pyaleph-ipfs/ \
  user@new-server:/var/lib/docker/volumes/pyaleph_pyaleph-ipfs/

Volume paths may differ depending on your Docker installation; verify with docker volume inspect.

If you're keeping the same public IP and want to preserve the IPFS peer identity, the Kubo config file is already included when you rsync the whole pyaleph-ipfs volume — no extra step needed.

If you're using a new IP and want Kubo to regenerate its identity instead, exclude the config file during the rsync:

rsync -av --exclude='_data/config' \
  /var/lib/docker/volumes/pyaleph_pyaleph-ipfs/ \
  user@new-server:/var/lib/docker/volumes/pyaleph_pyaleph-ipfs/

Kubo will write a fresh config with a new identity the first time it starts on the new server.

5. Network considerations

• Same IPv4: if you can keep the same public IPv4 (e.g. by moving the address), the other nodes on the network will continue trusting your peer without rebuilding reputation. This is the smoothest path.
• New IPv4: your node will still work, but other peers need to re-establish trust, which can take hours to days. Expect a temporary score dip during this period.

If you use a DNS name, update the A/AAAA records to point to the new server and wait for propagation before starting.

6. Start the new node

On the new server:

cd /path/to/pyaleph
docker compose up -d

Verify:

• docker compose logs -f pyaleph shows normal P2P activity
• The node catches up with recent messages
• Your node appears healthy on the Node Operator Dashboard

7. Update the on-chain registration (multiaddress)

A CCN is registered on-chain with a multiaddress that includes its public IP and libp2p peer ID. If the new server has a different IP, or you let the P2P identity change, you must update the registered multiaddress so other nodes and the network can reach you — otherwise your node will look unreachable and your score will drop.

When you must update the multiaddress:

• The new server has a different public IPv4 than the old one, or
• You did not migrate pyaleph/keys/* and the peer ID changed.

When you can skip this step:

• Same public IPv4 and the P2P keys were migrated — the multiaddress is unchanged.

Retrieve the new multiaddress by querying the running node (replace NODE_IP_ADDRESS with the new public IP):

curl -s http://NODE_IP_ADDRESS:4024/api/v0/info/public.json | jq -r .node_multi_addresses[0]

The output looks like /ip4/1.2.3.4/tcp/4025/p2p/Qm....

Update the registration:

1. Open the Node Operator Dashboard.
2. Connect the wallet that owns the node registration.
3. Locate your node in the list and open its settings.
4. Replace the multiaddress with the new value retrieved above and save.

Changes propagate within a few minutes. Monitor your node's score on the dashboard to confirm it recovers.

8. Decommission the old server

Only after the new node is confirmed synced and healthy:

1. Confirm the old server is fully stopped (docker compose ps shows nothing running).
2. Keep the old backups for at least a few days in case you need to roll back.
3. Wipe or repurpose the old machine.

---

---

Post-Migration Checklist

• New node is running and healthy
• On-chain registration updated if the multiaddress changed
• Node appears on the official monitoring dashboard
• Score is stable (monitor for 24–48 hours)
• Old server is fully stopped to prevent double-running
• Backups from the migration are kept until the new node is confirmed stable
• Any firewall, reverse proxy, and DNS changes are documented for future reference

Troubleshooting

If the new node fails to sync or appears unhealthy:

• Check firewall rules — CCN requires ports 4001 (IPv4 and IPv6) and 4025.
• Verify the P2P keys were copied correctly and have the right ownership/permissions.
• Review logs with docker compose logs.
• See the Node Troubleshooting guide for common issues.