From 3af3327311af2d9bf5cc9756fc63d4b9b01df49e Mon Sep 17 00:00:00 2001 From: Eliot Berriot Date: Thu, 22 Mar 2018 14:18:55 +0100 Subject: [PATCH 1/5] Added missing choice of version in the docker deployment guide --- docs/installation/docker.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/installation/docker.rst b/docs/installation/docker.rst index 34e8187c5..dc031caed 100644 --- a/docs/installation/docker.rst +++ b/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) From 2cfe4fa3a12d12c1b285e80856350d92eb82a4fb Mon Sep 17 00:00:00 2001 From: Eliot Berriot Date: Thu, 22 Mar 2018 14:19:26 +0100 Subject: [PATCH 2/5] Fixed wrong mv command in debian guide --- docs/installation/debian.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/installation/debian.rst b/docs/installation/debian.rst index 86ccb4dd3..c4e54218d 100644 --- a/docs/installation/debian.rst +++ b/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. From 1c251ac7c7ffbbef4b202c6903a8875bd8ff91ad Mon Sep 17 00:00:00 2001 From: Eliot Berriot Date: Thu, 22 Mar 2018 14:22:39 +0100 Subject: [PATCH 3/5] Fix #127: Added upgrade documentation --- changes/changelog.d/127.doc | 0 docs/index.rst | 1 + docs/upgrading.rst | 88 +++++++++++++++++++++++++++++++++++++ 3 files changed, 89 insertions(+) create mode 100644 changes/changelog.d/127.doc create mode 100644 docs/upgrading.rst diff --git a/changes/changelog.d/127.doc b/changes/changelog.d/127.doc new file mode 100644 index 000000000..e69de29bb diff --git a/docs/index.rst b/docs/index.rst index 17e9fe7f0..f5acecce5 100644 --- a/docs/index.rst +++ b/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 diff --git a/docs/upgrading.rst b/docs/upgrading.rst new file mode 100644 index 000000000..24f5502a6 --- /dev/null +++ b/docs/upgrading.rst @@ -0,0 +1,88 @@ +Upgrading your funkwhale instance to a newer version +==================================================== + +.. note:: + + Before upgrading your instance, we strongly advise you to make a database + backup. 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:: + + # 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/|version|/download?job=build_api" + unzip "api-|version|.zip" -d extracted + mv extracted/api/* 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 From a890bc490bf1a2a5906948277462fe77ddb258b5 Mon Sep 17 00:00:00 2001 From: Eliot Berriot Date: Fri, 23 Mar 2018 12:10:18 +0100 Subject: [PATCH 4/5] Ensure we update all requirements when installing from pip/requirements.txt --- api/requirements.txt | 1 + 1 file changed, 1 insertion(+) diff --git a/api/requirements.txt b/api/requirements.txt index d1197135e..00be27c53 100644 --- a/api/requirements.txt +++ b/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 From e3fc33a2c425a7862576316bce3afd4802039d96 Mon Sep 17 00:00:00 2001 From: Eliot Berriot Date: Fri, 23 Mar 2018 12:15:21 +0100 Subject: [PATCH 5/5] Minor tweaks to upgrade documentation --- docs/upgrading.rst | 16 +++++++++++----- 1 file changed, 11 insertions(+), 5 deletions(-) diff --git a/docs/upgrading.rst b/docs/upgrading.rst index 24f5502a6..674878ba7 100644 --- a/docs/upgrading.rst +++ b/docs/upgrading.rst @@ -3,10 +3,13 @@ Upgrading your funkwhale instance to a newer version .. note:: - Before upgrading your instance, we strongly advise you to make a database - backup. We're commited to make upgrade as easy and straightforward as possible, + 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 ------------------------- @@ -62,14 +65,17 @@ 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/|version|/download?job=build_api" - unzip "api-|version|.zip" -d extracted - mv extracted/api/* api/ + 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