Skip to content
Snippets Groups Projects
Select Git revision
  • develop default protected
  • 2405-front-buttont-trigger-third-party-hook
  • 2452-fetch-third-party-metadata
  • 2448-complete-tags
  • renovate/front-major-all-dependencies
  • renovate/front-all-dependencies
  • chore/2406-compose-modularity-scope
  • fix-schema-channel-metadata-choices
  • feat/2091-improve-visuals
  • stable protected
  • tempArne
  • 1.4.1-upgrade-release
  • 2416-revert-library-drop
  • 2408-troi-create-missing-tracks
  • wip/2091-improve-visuals
  • pin-mutagen-to-1.46
  • 2395-far-right-filter
  • fix-amd64-docker-build-gfortran
  • fix-plugins-dev-setup
  • flupsi/2804-new-upload-process
  • 2.0.0-alpha.2 protected
  • 2.0.0-alpha.1 protected
  • 1.4.1 protected
  • 1.4.0 protected
  • 1.4.0-rc2 protected
  • 1.4.0-rc1 protected
  • 1.3.4 protected
  • 1.3.3 protected
  • 1.3.2 protected
  • 1.3.1 protected
  • 1.3.0 protected
  • 1.3.0-rc6 protected
  • 1.3.0-rc5 protected
  • 1.3.0-rc4 protected
  • 1.2.10 protected
  • 1.3.0-rc3 protected
  • 1.3.0-rc2 protected
  • 1.3.0-rc1 protected
  • 1.2.9 protected
  • 1.2.8 protected
40 results

upgrading.rst

Blame
  • upgrading.rst 7.01 KiB

    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.

    Insights about new versions

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

    Docker setup

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

    Mono-container installation

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

    # this assumes you want to upgrade to version "|version|"
    export FUNKWHALE_VERSION="|version|"
    docker pull funkwhale/all-in-one:$FUNKWHALE_VERSION
    docker stop funkwhale
    docker rm funkwhale
    docker run \
        --name=funkwhale \
        --restart=unless-stopped \
        --env-file=/srv/funkwhale/.env \
        -v /srv/funkwhale/data:/data \
        -v /path/to/your/music/dir:/music:ro \
        -e PUID=$UID \
        -e PGID=$GID \
        -p 5000:80 \
        -d \
        funkwhale/all-in-one:$FUNKWHALE_VERSION

    If you are not managing the container directly by hand, but use a third party tool such as Portainer, instructions will vary, but, as a rule of thumb, pulling the new version of the image, and relaunch a new container with the same arguments as the previous one (except for the image version) is enough.

    Multi-container installation

    # this assumes you want to upgrade to version "|version|"
    export FUNKWHALE_VERSION="|version|"
    cd /srv/funkwhale
    # hardcode the targeted version your env file
    # (look for the FUNKWHALE_VERSION variable)
    nano .env
    # Load your environment variables
    source .env
    # Download newest nginx configuration file
    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"
    # 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

    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.

    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:

    # 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 \
      -v $(pwd)/data/postgres:/var/lib/postgresql/${OLD_POSTGRES}/data \
      -v $(pwd)/data/postgres-new:/var/lib/postgresql/${NEW_POSTGRES}/data \
      tianon/postgres-upgrade:${OLD_POSTGRES}-to-${NEW_POSTGRES}
    # Add back the access control rule that doesn't survive the upgrade
    echo "host all all all trust" | sudo tee -a ./data/postgres-new/pg_hba.conf
    # Swap over to the new database
    mv ./data/postgres ./data/postgres-old
    mv ./data/postgres-new ./data/postgres

    Non-docker setup

    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`.

    # this assumes you want to upgrade to version "|version|"
    export FUNKWHALE_VERSION="|version|"
    cd /srv/funkwhale
    sudo -u funkwhale curl -L -o front.zip "https://dev.funkwhale.audio/funkwhale/funkwhale/builds/artifacts/$FUNKWHALE_VERSION/download?job=build_front"
    sudo -u funkwhale unzip -o front.zip
    sudo -u funkwhale rm front.zip

    Upgrading the API

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

    # this assumes you want to upgrade to version "|version|"
    export FUNKWHALE_VERSION="|version|"
    cd /srv/funkwhale
    
    # download more recent API files
    sudo -u funkwhale curl -L -o "api-$FUNKWHALE_VERSION.zip" "https://dev.funkwhale.audio/funkwhale/funkwhale/-/jobs/artifacts/$FUNKWHALE_VERSION/download?job=build_api"
    sudo -u funkwhale unzip "api-$FUNKWHALE_VERSION.zip" -d extracted
    sudo -u funkwhale rm -rf api/ && sudo -u funkwhale mv extracted/api .
    sudo -u funkwhale rm -rf extracted
    
    # update os dependencies
    sudo api/install_os_dependencies.sh install
    sudo -u funkwhale -H -E /srv/funkwhale/virtualenv/bin/pip install -r api/requirements.txt
    
    # collect static files
    sudo -u funkwhale -H -E /srv/funkwhale/virtualenv/bin/python api/manage.py collectstatic --no-input
    
    # stop the services
    sudo systemctl stop funkwhale.target
    
    # apply database migrations
    sudo -u funkwhale -H -E /srv/funkwhale/virtualenv/bin/python api/manage.py migrate
    
    # restart the services
    sudo systemctl start funkwhale.target

    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.