upgrading.rst 7.04 KB
Newer Older
Reg's avatar
Reg committed
1
Upgrading your Funkwhale instance to a newer version
2
3
4
5
====================================================

.. note::

6
7
8
9
    Before upgrading your instance, we strongly advise you to make at least a database backup. Ideally, you should make a full backup, including
    the database and the media files.

    We're commited to make upgrade as easy and straightforward as possible,
Reg's avatar
Reg committed
10
    however, Funkwhale is still in development and you'll be safer with a backup.
11

12

13
14
15
Reading the release notes
-------------------------

16
Please take a few minutes to read the :doc:`../changelog`: updates should work
17
18
19
20
similarly from version to version, but some of them may require additional steps.
Those steps would be described in the version release notes.


21
22
23
24
25
26
27
28
29
30
31
32
Insights about new versions
---------------------------

Some versions may be bigger than usual, and we'll try to detail the changes
when possible.

.. toctree::
   :maxdepth: 1

   0.17


33
Docker setup
34
------------
35

36
If you've followed the setup instructions in :doc:`../installation/docker`, upgrade path is
37
38
easy:

39
40
41
42
43
44
Mono-container installation
^^^^^^^^^^^^^^^^^^^^^^^^^^^

Basically, you need to pull the new container image, stop and delete your existing container,
and relaunch a new one:

Creak's avatar
Creak committed
45
46
47
48
49
50
51
52
53
To upgrade your service, change the version number of the image in ``docker-compose.yml`` with the latest release (i.e. |version|).

Pull the new images:

.. code-block:: shell

    docker-compose pull

Restart the service:
54
55
56

.. code-block:: shell

Creak's avatar
Creak committed
57
    docker-compose up -d
58
59
60
61

Multi-container installation
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

62
.. parsed-literal::
63
64
65
66
    # this assumes you want to upgrade to version "|version|"
    export FUNKWHALE_VERSION="|version|"

.. code-block:: shell
67
68
69
70
71

    cd /srv/funkwhale
    # hardcode the targeted version your env file
    # (look for the FUNKWHALE_VERSION variable)
    nano .env
72
73
74
    # Load your environment variables
    source .env
    # Download newest nginx configuration file
75
76
    curl -L -o nginx/funkwhale.template "https://dev.funkwhale.audio/funkwhale/funkwhale/raw/$FUNKWHALE_VERSION/deploy/docker.nginx.template"
    curl -L -o nginx/funkwhale_proxy.conf "https://dev.funkwhale.audio/funkwhale/funkwhale/raw/$FUNKWHALE_VERSION/deploy/docker.funkwhale_proxy.conf"
77
78
79
80
81
82
83
    # Pull the new version containers
    docker-compose pull
    # Apply the database migrations
    docker-compose run --rm api python manage.py migrate
    # Relaunch the containers
    docker-compose up -d

84
85
86
87
88
89
90
91
.. warning::

    You may sometimes get the following warning while applying migrations::

        "Your models have changes that are not yet reflected in a migration, and so won't be applied."

    This is a warning, not an error, and it can be safely ignored.
    Never run the ``makemigrations`` command yourself.
92

93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
Upgrading the Postgres container
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

With some Funkwhale releases, it is recommended to upgrade the version of the
Postgres database server container. For example, Funkwhale 0.17 recommended
Postgres 9.4, but Funkwhale 0.18 recommends Postgres 11. When upgrading
Postgres, it is not sufficient to change the container referenced in
``docker-compose.yml``. New major versions of Postgres cannot read the databases
created by older major versions. The data has to be exported from a running
instance of the old version and imported by the new version.

Thankfully, there is a Docker container available to automate this process. You
can use the following snippet to upgrade your database in ``./postgres``,
keeping a backup of the old version in ``./postgres-old``:

108
.. code-block:: shell
109
110
111
112
113
114

    # Replace "9.4" and "11" with the versions you are migrating between.
    export OLD_POSTGRES=9.4
    export NEW_POSTGRES=11
    docker-compose stop postgres
    docker run --rm \
115
116
      -v $(pwd)/data/postgres:/var/lib/postgresql/${OLD_POSTGRES}/data \
      -v $(pwd)/data/postgres-new:/var/lib/postgresql/${NEW_POSTGRES}/data \
117
118
      tianon/postgres-upgrade:${OLD_POSTGRES}-to-${NEW_POSTGRES}
    # Add back the access control rule that doesn't survive the upgrade
119
    echo "host all all all trust" | sudo tee -a ./data/postgres-new/pg_hba.conf
120
121
122
    # Swap over to the new database
    mv ./data/postgres ./data/postgres-old
    mv ./data/postgres-new ./data/postgres
123
124


125
Non-docker setup
126
127
----------------

128
129
130
131
If you installed Funkwhale using the install script, upgrading is done using ``sh -c "$(curl -sSL https://get.funkwhale.audio/upgrade.sh)"``. Make sure to run this command with root permissions.

If you manually installed Funkwhale, please use the following instructions.

132
133
134
135
136
137
138
139
140
141
142
143
144
145
Upgrade the static files
^^^^^^^^^^^^^^^^^^^^^^^^

On non-docker setups, the front-end app
is updated separately from the API. This is as simple as downloading
the zip with the static files and extracting it in the correct place.

The following example assume your setup match :ref:`frontend-setup`.

.. parsed-literal::

    # this assumes you want to upgrade to version "|version|"
    export FUNKWHALE_VERSION="|version|"
    cd /srv/funkwhale
Eliot Berriot's avatar
Eliot Berriot committed
146
    sudo -u funkwhale curl -L -o front.zip "https://dev.funkwhale.audio/funkwhale/funkwhale/builds/artifacts/$FUNKWHALE_VERSION/download?job=build_front"
147
148
    sudo -u funkwhale unzip -o front.zip
    sudo -u funkwhale rm front.zip
149
150
151

Upgrading the API
^^^^^^^^^^^^^^^^^
152

153
On non-docker, upgrade involves a few more commands. We assume your setup
154
match what is described in :doc:`/installation/debian`:
155
156
157
158

.. parsed-literal::

    # this assumes you want to upgrade to version "|version|"
159
    export FUNKWHALE_VERSION="|version|"
160
161
162
    cd /srv/funkwhale

    # download more recent API files
Eliot Berriot's avatar
Eliot Berriot committed
163
    sudo -u funkwhale curl -L -o "api-$FUNKWHALE_VERSION.zip" "https://dev.funkwhale.audio/funkwhale/funkwhale/-/jobs/artifacts/$FUNKWHALE_VERSION/download?job=build_api"
164
    sudo -u funkwhale unzip "api-$FUNKWHALE_VERSION.zip" -d extracted
165
    sudo -u funkwhale rm -rf api/ && sudo -u funkwhale mv extracted/api .
166
    sudo -u funkwhale rm -rf extracted
167
    sudo -u funkwhale rm api-$FUNKWHALE_VERSION.zip
168
169
170

    # update os dependencies
    sudo api/install_os_dependencies.sh install
171
    sudo -u funkwhale -H -E /srv/funkwhale/virtualenv/bin/pip install -r api/requirements.txt
172
173

    # collect static files
174
    sudo -u funkwhale -H -E /srv/funkwhale/virtualenv/bin/python api/manage.py collectstatic --no-input
175
176
177
178
179

    # stop the services
    sudo systemctl stop funkwhale.target

    # apply database migrations
180
    sudo -u funkwhale -H -E /srv/funkwhale/virtualenv/bin/python api/manage.py migrate
181
182

    # restart the services
183
    sudo systemctl start funkwhale.target
184

185
186
187
188
189
190
.. note::
    If you see a PermissionError when running the ``migrate`` command, try running the following commands by hand, and relaunch the migrations::

        sudo -u postgres psql funkwhale -c 'CREATE EXTENSION IF NOT EXISTS "citext";'
        sudo -u postgres psql funkwhale -c 'CREATE EXTENSION IF NOT EXISTS "unaccent";'

191
192
193
194
195
196
197
198
.. warning::

    You may sometimes get the following warning while applying migrations::

        "Your models have changes that are not yet reflected in a migration, and so won't be applied."

    This is a warning, not an error, and it can be safely ignored.
    Never run the ``makemigrations`` command yourself.