5.5 KiB
title | description | menu | ||||||
---|---|---|---|---|---|---|---|---|
Migrating to a new machine | Copying your Mastodon installation to a new server without losing anything. |
|
Sometimes, for various reasons, you may want to migrate your Mastodon instance from one server to another. Fortunately this is not too difficult of a process, although it may result in some downtime.
{{< hint style="info" >}} This guide was written with Ubuntu Server in mind; your mileage may vary for other setups. {{< /hint >}}
Basic steps
- Set up a new Mastodon server using the [Production Guide]({{< relref "install" >}}) (however, don’t run
mastodon:setup
). - Stop Mastodon on the old server (e.g.
systemctl stop 'mastodon-*.service'
). - Dump and load the Postgres database using the instructions below.
- Copy the
system/
files using the instructions below. (Note: if you’re using S3, you can skip this step.) - Copy the
.env.production
file. - Run
RAILS_ENV=production bundle exec rails assets:precompile
to compile Mastodon - Run
RAILS_ENV=production ./bin/tootctl feeds build
to rebuild the home timelines for each user. - Start Mastodon on the new server.
- Update your DNS settings to point to the new server.
- Update or copy your Nginx configuration, re-run LetsEncrypt as necessary.
- Enjoy your new server!
Detailed steps
What data needs to be migrated
At a high level, you’ll need to copy over the following:
- The
~/live/public/system
directory, which contains user-uploaded images and videos (if using S3, you don’t need this) - The Postgres database (using pg_dump)
- The
~/live/.env.production
file, which contains server config and secrets
Less crucially, you’ll probably also want to copy the following for convenience:
- The nginx config (under
/etc/nginx/sites-available/
) - The systemd config files (
/etc/systemd/system/mastodon-*.service
), which may contain your server tweaks and customizations - The pgbouncer configuration under
/etc/pgbouncer
(if you’re using it)
Dump and load Postgres
{{< hint style="info" >}}
Before you start, note that both pg_dump
and pg_restore
can take a long time. (As in, hours for a ~15GB backup file.) You may want to temporarily tune Postgres's performance just for dumping/restoring.
{{< /hint >}}
Instead of running mastodon:setup
, we’re going to create an empty Postgres database using the template0
database (which is useful when restoring a Postgres dump, as described in the pg_dump documentation).
Run this as the mastodon
user on your old system:
pg_dump -Fc mastodon_production -f backup.dump
Copy the backup.dump
file over, using rsync
or scp
. Then on the new system, create an empty database as the mastodon
user:
createdb -T template0 mastodon_production
Then import it:
pg_restore -Fc -U mastodon -n public --no-owner --role=mastodon \
-d mastodon_production backup.dump
{{< hint style="info" >}}
Note that if the username is not mastodon
on the new server, you should change the -U
AND --role
values above. It’s okay if the username is different between the two servers.
{{< /hint >}}
Copy files
This will probably take some time, and you’ll want to avoid re-copying unnecessarily, so using rsync
is recommended. On your old machine, as the mastodon
user, run:
rsync -avz ~/live/public/system/ mastodon@example.com:~/live/public/system/
You’ll want to re-run this if any of the files on the old server change.
You should also copy over the .env.production
file, which contains secrets.
Optionally, you may copy over the nginx, systemd, and pgbouncer config files, or rewrite them from scratch.
Certbot
Copying your Nginx config files will not be sufficient to re-run letsencrypt. You'll need to copy the certificate files referenced by ssl_certificate
and ssl_certificate_key
(in /etc/nginx/sites-available/mastodon
) to the new machine and update the path in the new machine's nginx config. (Don't use letsencrypt's own live
folder for this, or else letsencrypt will complain when you try to re-generate the certificate. Just use any temporary directory for this, since re-running letsencrypt will overwrite the config anyway.)
Migrate Redis (optional)
As mentioned in the [Backup Guide]({{< relref "backups" >}}), losing the Redis database is almost harmless. But if you want to migrate Redis data, you can shut down both Redis services, copy the /var/lib/redis/dump.rdb
to the new machine (ensuring the permissions and ownership are correct), and then restart Redis.
During migration
You can edit the ~/live/public/500.html
page on the old machine if you want to show a nice error message to let existing users know that a migration is in progress.
You’ll probably also want to set the DNS TTL to something small (30-60 minutes) about a day in advance, so that DNS can propagate quickly once you point it to the new IP address.
After migrating
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.