migration.rst 3.93 KB
Newer Older
1
2
3
4
5
6
7
8
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.

jovuit's avatar
jovuit committed
9
10
In this guide, the existing Funkwhale setup is called the origin server, and the new setup the destination server.

11
12
13
14
15
16
17
18
19
20
21
22
Requirements
------------

To get started with your new setup, you will need to have the
following:

- `rsync <https://linux.die.net/man/1/rsync>`_ installed on the **destination** server
- SSH access set up between the two servers

Non-Docker
----------

jovuit's avatar
jovuit committed
23
24
25
26
27
28
29
On the destination server, run through the :doc:`installation steps<../installation/debian>` with the exception of the following points:

- Do not enable the extensions ``unaccent`` and ``citext`` when setting up the database;
- Do not initialize the database by applying the migrate command;
- Do not create an admin account.

Stop all funkwhale related services on the destination server:
30
31
32

.. code-block:: shell

jovuit's avatar
jovuit committed
33
    sudo systemctl stop funkwhale.target
34

jovuit's avatar
jovuit committed
35
On the origin server, create a database backup:
36
37
38

.. code-block:: shell

jovuit's avatar
jovuit committed
39
    sudo -u funkwhale pg_dump -d funkwhale > "db.dump"
40

jovuit's avatar
jovuit committed
41
On the destination server, use rsync to fetch the contents of ``/srv/funwkhale/data/media/music/`` and ``/srv/funkwhale/data/media/`` from the origin server, as well as the database dump and the ``.env`` file:
42
43
44

.. code-block:: shell

jovuit's avatar
jovuit committed
45
46
47
48
49
    origin = <origin server IP/hostname>
    username = <your username>

    rsync -a $username@$origin:/srv/funkwhale/data/media/ /srv/funkwhale/data/media/
    rsync -a $username@$origin:/srv/funkwhale/data/music/ /srv/funkwhale/data/music/
50

jovuit's avatar
jovuit committed
51
52
53
54
    rsync -a $username@$origin:/srv/funkwhale/config/.env /srv/funkwhale/config/
    rsync -a $username@$origin:/srv/funkwhale/db.dump /srv/funkwhale/

On the destination server, restore the database dump:
55
56
57

.. code-block:: shell

jovuit's avatar
jovuit committed
58
59
60
    sudo psql -d funkwhale db.dump

Once the database has been restored, follow the database migration steps from the non-docker installation guide to complete the installation on the destination server.
61

jovuit's avatar
jovuit committed
62
63
64
65
66
Ensure that all DNS changes have been made and start the services:

.. code-block:: shell

    sudo systemctl start funkwhale.target
67
68
69
70

Docker
------

jovuit's avatar
jovuit committed
71
72
73
74
75
On the destination 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 origin server, create a database backup:
76
77
78
79
80

.. code-block:: shell

    docker exec -t funkwhale_postgres_1 pg_dumpall -c -U postgres > "db.dump"

jovuit's avatar
jovuit committed
81
On the destination server, use rsync to fetch the contents of ``/srv/funwkhale/data/media/music`` and ``/srv/funkwhale/data/media`` from the origin server, as well as the database dump nd the ``.env`` file:
82
83
84

.. code-block:: shell

jovuit's avatar
jovuit committed
85
86
    origin = <origin server IP/hostname>
    username = <your username>
87

jovuit's avatar
jovuit committed
88
89
    rsync -a $username@$origin:/srv/funkwhale/data/media/ /srv/funkwhale/data/media/
    rsync -a $username@$origin:/srv/funkwhale/data/music/ /srv/funkwhale/data/music/
90

jovuit's avatar
jovuit committed
91
92
    rsync -a $username@$origin:/srv/funkwhale/.env /srv/funkwhale/
    rsync -a $username@$origin:/srv/funkwhale/db.dump /srv/funkwhale/
93

94
Initialize the Postgres container with the funkwhale database and its user. For easier, we create a db init dump file than we import in the postgres container:
95
96
97

.. code-block:: shell

98
99
100
101
102
103
104
105
106
107
108
109
    echo "CREATE DATABASE "funkwhale"
  WITH ENCODING 'utf8';
  CREATE USER funkwhale;
  GRANT ALL PRIVILEGES ON DATABASE funkwhale TO funkwhale;" > init.dump

    docker exec -i funkwhale_postgres_1 psql -U postgres -d postgres < "init.dump"

After that, we can restore the database dump:

.. code-block:: shell

    docker exec -i funkwhale_postgres_1 psql -U postgres -d postgres < "db.dump"
110

jovuit's avatar
jovuit committed
111
112
Once the database has been restored, run the migrations following the docker installation guide. 

113
Ensure that all DNS changes have been made and start the services.