Migrating to a new server

This guide describes how to migrate your PeerTube instance from one server to
another. It assumes you have root access to both servers. The process takes
some time - so you may want a caffeinated beverage of your choice - and there
will be a short period of downtime between when you shut down the old server
and point DNS at the new one.

Note: do not modify anything on the old server until you have successfully migrated the instance.

Copy storage/ files

This will probably take a long time! We recommend using rsync to avoid
unnecesary copies, but scp or any other file-copying utility is fine too.

On your old machine, as the peertube user, run:

sudo-u peertube rsync -avz ~/storage/ peertube@example.com:~/storage/

or

sudo-u peertube scp -r ~/storage peertube@example.com:~/storage

You will need to re-run this if any of the files on the old server change. That’s
why it’s better to use rsync.

(¹) To minimize downtime, you may want to finish an rsync run while the old server is still
running, and then re-synchronize after shutting down PeerTube to capture the last few changes. It’s
also possible to avoid this copying step by configuring PeerTube’s storage directory to live
on an external storage drive, and then just moving the external storage drive and configuring its mount
point in fstab.

This is a good time to copy over any configuration files you wish to use on the
new server, such as config/, or the nginx/systemd configuration files or startup
scripts.

(²) Let’s Encrypt

It’s a good idea to copy the Let’s Encrypt certs over from the old server
instead of requesting a new cert. Requesting new certs takes longer, and might
fail for some reason, so it’s better to avoid that additional source of complication
during the migration process.

During the migration

You may want to configure nginx to send a 503 (service unavailable)
instead of a 501 (bad gateaway), and answer with a custom 500.html.

You will probably want to set the DNS TTL to the lowest possible value about a
day in advance. Set it to a few minutes if you can. This ensures the DNS update
propagates as quickly as possible once you point it to the new IP address,
resulting in less downtime.

After the migration

You can check whatsmydns.net to see the progress
of DNS propagation. To jumpstart the process, you can always edit your own
/etc/hosts file to point to your new server so you can start playing around
with it early and check if all is all right.

If everything is alright, you can safely shut down the old server.

Acknowledgements

Thanks to the Mastodon team for their migration guide, which largely inspired this guide.