English

Français

English

Français

Appearance

PeerTube platform migration ​

This guide describes how to migrate your PeerTube platform 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.

WARNING

Do not modify anything on the old server until you have successfully migrated the platform.

Basic steps ​

  1. Setup a new PeerTube server using the production guide
  2. Stop PeerTube on the old server
  3. Dump and load the PostgreSQL database using the instructions below
  4. Copy or synchronize the storage/ files using the instructions below
  5. Copy or synchronize the config/ files using the instructions below
  6. Update or copy your nginx configuration, Let's Encrypt certificates, systemd configuration files as necessary
  7. Start PeerTube on the new server
  8. Update your DNS settings to point to the new server
  9. Enjoy your new PeerTube server!

Detailed steps ​

You may want to configure nginx to send a 503 (service unavailable) instead of a 502 (bad gateway), 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.

Create a migration user on both servers ​

The peertube system user usually has no shell login (/usr/sbin/nologin), so you generally cannot use peertube@server over SSH for transfer commands.

Create a temporary user (for example migration) on both servers and use it for SSH transport:

bash
sudo useradd -m -s /bin/bash migration

On the old server, generate a dedicated SSH key for the transfer:

bash
sudo -u migration ssh-keygen -t ed25519 -C "peertube-migration" -f /home/migration/.ssh/id_migration -N ""

Copy the public key of the old server

bash
cat /home/migration/.ssh/id_migration.pub

Then authorize it on the new server:

bash
mkdir -p ~/.ssh && chmod 700 ~/.ssh
vim ~/.ssh/authorized_keys # Paste the public key copied from the old server
chmod 600 ~/.ssh/authorized_keys

What data needs to be migrated ​

At a high level, you will need to copy over the following:

  • The /var/www/peertube/storage directory, which contains videos, thumbnails, previews, and so on
  • The /var/www/peertube/config file, which contains the configuration
  • The PostgreSQL database (using pg_dump)

You might also want to copy the following configuration items, if the new server is configured similarly to the old one:

  • The peertube-specific nginx configuration (by default found at /etc/nginx/sites-available/peertube)
  • The systemd config files or startup scripts, which may contain tweaks and customizations specific to your server
  • Let's Encrypt certificates

Dump and load PostgreSQL ​

Once you have stopped your PeerTube platform, run the following command as the peertube user on the old server, to generate a text dump of the database:

bash
sudo -u peertube pg_dump -Fc peertube_prod > /tmp/peertube_prod-dump.db

Copy the /tmp/peertube_prod-dump.db file over to the new server by running the following command on your old server

bash
scp -i /home/migration/.ssh/id_migration /tmp/peertube_prod-dump.db migration@new.server:/tmp

Then on the new server, run the following command to restore the database on the new server to the same state as on the old one:

bash
sudo -u postgres pg_restore -c -C -d postgres /tmp/peertube_prod-dump.db

You might see warnings that you can safely ignore.

Copy storage/ files ​

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

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.

Before copying files, temporarily change ownership of the PeerTube directory on both servers so this user can read and write files directly:

bash
sudo chown -R migration: /var/www/peertube

On your old server, as the migration user, run:

bash
sudo -u migration rsync -avz -e "ssh -i /home/migration/.ssh/id_migration" /var/www/peertube/storage/ migration@new.server:/var/www/peertube/storage/

Copy config/ files ​

On your old server, as the migration user, run:

bash
sudo -u migration rsync -avz -e "ssh -i /home/migration/.ssh/id_migration" /var/www/peertube/config/ migration@new.server:/var/www/peertube/config/

After the migration is complete, restore ownership to peertube on both servers:

bash
sudo chown -R peertube: /var/www/peertube

Copy certificates/nginx/systemd files ​

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

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.

After the migration ​

Remove the temporary migration user if you no longer need it on both servers:

bash
sudo userdel -r 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.
  • Thanks to @Nutomic for his comments.