Merge branch '127-upgrade-doc' into 'develop'

Resolve "Document the upgrade process"

Closes #127 and #105

See merge request funkwhale/funkwhale!100

api/requirements.txt

@@ -1,3 +1,4 @@
 # This file is here because many Platforms as a Service look for
 #	requirements.txt in the root directory of a project.
+-r requirements/base.txt
 -r requirements/production.txt

docs/index.rst

@@ -15,6 +15,7 @@ Funkwhale is a self-hosted, modern free and open-source music server, heavily in
    installation/index
    configuration
    importing-music
+   upgrading
    changelog
 
 Indices and tables

docs/installation/debian.rst

@@ -89,7 +89,7 @@ First, we'll download the latest api release.
 
     curl -L -o "api-|version|.zip" "https://code.eliotberriot.com/funkwhale/funkwhale/-/jobs/artifacts/|version|/download?job=build_api"
     unzip "api-|version|.zip" -d extracted
-    mv extracted/api api
+    mv extracted/api/* api/
     rmdir extracted
 
 
@@ -100,7 +100,7 @@ Then we'll download the frontend files:
     curl -L -o "front-|version|.zip" "https://code.eliotberriot.com/funkwhale/funkwhale/-/jobs/artifacts/|version|/download?job=build_front"
     unzip "front-|version|.zip" -d extracted
     mv extracted/front .
-    rmdir extracted
+    rm -rf extracted
 
 You can leave the ZIP archives in the directory, this will help you know
 which version you've installed next time you want to upgrade your installation.

docs/installation/docker.rst

@@ -17,7 +17,9 @@ Create your env file:
 
 .. parsed-literal::
 
+    export FUNKWHALE_VERSION="|version|"
     curl -L -o .env "https://code.eliotberriot.com/funkwhale/funkwhale/raw/|version|/deploy/env.prod.sample"
+    sed -i "s/FUNKWHALE_VERSION=latest/FUNKWHALE_VERSION=$FUNKWHALE_VERSION/" .env
 
 Ensure to edit it to match your needs (this file is heavily commented)
 

docs/upgrading.rst

@@ -0,0 +1,94 @@
+Upgrading your funkwhale instance to a newer version
+====================================================
+
+.. note::
+
+    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,
+    however, funkwhale is still in development and you'll be safer with a backup.
+
+
+Reading the release notes
+-------------------------
+
+Please take a few minutes to read the :doc:`changelog`: updates should work
+similarly from version to version, but some of them may require additional steps.
+Those steps would be described in the version release notes.
+
+Upgrade the static files
+------------------------
+
+Regardless of your deployment choice (docker/non-docker) 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
+    curl -L -o front.zip "https://code.eliotberriot.com/funkwhale/funkwhale/builds/artifacts/$FUNKWHALE_VERSION/download?job=build_front"
+    unzip -o front.zip
+    rm front.zip
+
+Upgrading the API
+-----------------
+
+Docker setup
+^^^^^^^^^^^^
+
+If you've followed the setup instructions in :doc:`Docker`, upgrade path is
+easy:
+
+.. parsed-literal::
+
+    cd /srv/funkwhale
+    # hardcode the targeted version your env file
+    # (look for the FUNKWHALE_VERSION variable)
+    nano .env
+    # 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
+
+Non-docker setup
+^^^^^^^^^^^^^^^^
+
+On non docker-setup, upgrade involves a few more commands. We assume your setup
+match what is described in :doc:`debian`:
+
+.. parsed-literal::
+
+    # stop the services
+    sudo systemctl stop funkwhale.target
+
+    # this assumes you want to upgrade to version "|version|"
+    export FUNKWALE_VERSION="|version|"
+    cd /srv/funkwhale
+
+    # download more recent API files
+    curl -L -o "api-|version|.zip" "https://code.eliotberriot.com/funkwhale/funkwhale/-/jobs/artifacts/$FUNKWALE_VERSION/download?job=build_api"
+    unzip "api-$FUNKWALE_VERSION.zip" -d extracted
+    rm -rf api/ && mv extracted/api .
+    rm -rf extracted
+
+    # update os dependencies
+    sudo api/install_os_dependencies.sh install
+    # update python dependencies
+    source /srv/funkwhale/load_env
+    source /srv/funkwhale/virtualenv/bin/activate
+    pip install -r api/requirements.txt
+
+    # apply database migrations
+    python api/manage.py migrate
+    # collect static files
+    python api/manage.py collectstatic --no-input
+
+    # restart the services
+    sudo systemctl restart funkwhale.target