Commit ace31204 authored by Rigel Kent's avatar Rigel Kent 💬

Merge branch 'master' into 'master'

Some wording changes to the migration docs

See merge request !11
parents fa954882 c891574a
Pipeline #99108 passed with stage
in 59 seconds
......@@ -6,8 +6,10 @@ timer: false
---
This guide describes how to migrate your PeerTube instance from one server to
another. It assumes you have root access to both servers, and some coffee. It
may result in some downtime.
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.
<div class="alert alert-warn" role="alert">
<strong>Note:</strong> do not modify anything on the old server until you have successfully migrated the instance.
......@@ -21,7 +23,7 @@ may result in some downtime.
4. Copy or synchronize the `storage/` files using the instructions below (¹)
5. Start PeerTube on the new server
6. Update your DNS settings to point to the new server
7. Update or copy your Nginx configuration, re-run LetsEncrypt as necessary (²)
7. Update or copy your Nginx configuration, re-run Let's Encrypt as necessary (²)
8. Enjoy your new PeerTube server!
## Detailed steps
......@@ -30,25 +32,26 @@ may result in some downtime.
At a high level, you will need to copy over the following:
- The `/var/www/peertube/storage`, which contains videos, thumbnails, previews…
- 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](https://www.postgresql.org/docs/9.6/static/backup-dump.html))
Less crucially, you will probably also want to copy the following for convenience:
You might also want to copy the following configuration items, if the new server is configured similarly to the old one:
- The nginx configuration (under `/etc/nginx/sites-available/peertube`)
- The systemd config files or startup scripts, which may contain your server tweaks and customizations
- 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
### Dump and load PostgreSQL
Run this as the `peertube` user on the old server:
Once you have stopped your PeerTube instance, 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, using `scp` or `rsync` at your
convenience:
Copy the `/tmp/peertube_prod-dump.db` file over to the new server, using `scp` or `rsync` or any similar
file-copying tool:
```bash
scp /tmp/peertube_prod-dump.db user@new.server:/tmp
......@@ -60,53 +63,55 @@ Then on the new system, run:
sudo -u postgres pg_restore -c -C -d postgres /tmp/peertube_prod-dump.db
```
to restore the database on the new server to the same state as on the old one.
You might see warnings that you can [safely ignore](https://confluence.atlassian.com/bamkb/errors-or-warnings-appear-when-importing-postgres-database-dump-829036698.html).
### Copy `storage/` files
This will probably take a long time! You want to avoid copying unnecessarily,
so using `rsync` is recommended. But you can use `scp` too.
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:
```bash
rsync -avz ~/storage/ peertube@example.com:~/storage/
sudo -u peertube rsync -avz ~/storage/ peertube@example.com:~/storage/
```
or
```bash
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`.
(¹) you could probably finish an rsync run while the old server is still
running, and then just re-synchronize after shutting it down. Or use external
storage if you can to avoid this step (then you just have to configure the
mount in fstab).
(¹) 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`.
If you still want to use `scp`:
```bash
scp -r ~/storage peertube@example.com:~/storage
```
You can also copy over any other important files, such as `config/` and the
nginx, systemd configuration or startup script.
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
You should copy the Let's Encrypt certs over from the old server instead of
request a new cert.
Requesting new certs takes longer, and might fail for some reason. Better if
you have time to fix that after the migration is complete.
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. That ensures the DNS
update propagates as quickly as possible once you point it to the new IP address,
thus less downtime.
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
......@@ -115,7 +120,7 @@ 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 right, you can safely shut down the old server.
If everything is alright, you can safely shut down the old server.
## Acknowledgements
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment