diff --git a/docs/admin/index.rst b/docs/admin/index.rst index fa66eeca6..3ce9683c6 100644 --- a/docs/admin/index.rst +++ b/docs/admin/index.rst @@ -15,6 +15,7 @@ Setup Guides configuration importing-music external-storages + migration Administration -------------- diff --git a/docs/admin/migration.rst b/docs/admin/migration.rst new file mode 100644 index 000000000..09d7efeca --- /dev/null +++ b/docs/admin/migration.rst @@ -0,0 +1,84 @@ +Migrating to a New Server +========================= + +Sometimes, it may be necessary or desirable to migrate your +existing Funkwhale setup to a new server. This can be helpful +if you need to boost resources or if you wish to use a different +hosting platform. + +Requirements +------------ + +To get started with your new setup, you will need to have the +following: + +- `rsync `_ installed on the **destination** server +- SSH access set up between the two servers + +Non-Docker +---------- + +- On the target server, run through the :doc:`installation steps<../installation/debian>` but skip the Database setup steps +- Stop all funkwhale related services on the destination server +- On the original server, create a database backup + +.. code-block:: shell + + sudo -u funkwhale pg_dump -d funkwhale > "db.dump" + +- On the destination server, use rsync to copy the contents of `/srv/funwkhale/data/media/music` and `/srv/funkwhale/data/music` from the original server + +.. code-block:: shell + + rsync -a @:/srv/funkwhale/data/media/ /srv/funkwhale/data/media/ + rsync -a @:/srv/funkwhale/data/music/ /srv/funkwhale/data/music/ + +- Copy your .env file and database backup from your original server + +.. code-block:: shell + + rsync -a @:/srv/funkwhale/config/.env /srv/funkwhale/config/ + rsync -a @:/srv/funkwhale/db.dump /srv/funkwhale/ + +- Restore the database dump + +.. code-block:: shell + + sudo -u funkwhale pg_restore -d funkwhale db.dump + +- Once the database has been restored, follow the database migration steps from the guide to complete the installation +- Ensure that all DNS changes have been made and start the services + +Docker +------ + +- On the target server, run through the :doc:`installation steps<../installation/docker>` but skip the `docker-compose run --rm api python manage.py migrate` step +- Stop all funkwhale related containers on the destination server +- On the original server, create a database backup + +.. code-block:: shell + + docker exec -t funkwhale_postgres_1 pg_dumpall -c -U postgres > "db.dump" + +- On the destination server, use rsync to copy the contents of `/srv/funwkhale/data/media/music` and `/srv/funkwhale/data/music` from the original server + +.. code-block:: shell + + rsync -a @:/srv/funkwhale/data/media/ /srv/funkwhale/data/media/ + rsync -a @:/srv/funkwhale/data/music/ /srv/funkwhale/data/music/ + +- Copy your .env file and database backup from your original server + +.. code-block:: shell + + rsync -a @:/srv/funkwhale/.env /srv/funkwhale/ + rsync -a @:/srv/funkwhale/db.dump /srv/funkwhale/ + +- Restore the database dump + +.. code-block:: shell + + docker exec -i funkwhale_postgres_1 pg_restore -c -U postgres -d postgres < "db.dump" + +- Once the database has been restored, run the migrations +- Ensure that all DNS changes have been made and start the services \ No newline at end of file