Something wrong with the translation?

Help us to improve it on our translation platform

Upgrade your Docker Funkwhale installation

If you installed Funkwhale following the Docker guide, follow these steps to upgrade.

Upgrade Funkwhale

  1. SSH into your server

  2. Log in as your funkwhale user.

    su funkwhale
  3. Navigate to your Funkwhale directory.

    cd /srv/funkwhale
  4. Export the Funkwhale version you want to update to. You’ll use this in the rest of the commands in this guide.

    export FUNKWHALE_VERSION=1.4.0
  5. Change the version number in your .env file. Update this to the same version number you exported in step 4.

    nano .env
  6. Log in as su to load the configuration from your .env file.

    sudo su
    source .env
  7. Pull the updated containers.

    docker compose pull
  8. Apply the database migrations.

    docker compose run --rm api funkwhale-manage migrate
  9. Relaunch your containers.

    docker compose up -d
  10. Exit the root shell.


That’s it! You’ve updated your Funkwhale pod. You should now see the new version running in your web browser.

Update your reverse proxy configuration

To ensure your reverse proxy is up-to-date with changes, you should regenerate your Nginx configuration with each upgrade. To do this:

  1. Log in to a root shell to make changes to the config files

    $ sudo su
  2. Download the new Nginx templates from Funkwhale

    # curl -L -o /etc/nginx/funkwhale_proxy.conf "$FUNKWHALE_VERSION/deploy/funkwhale_proxy.conf"
    # curl -L -o /etc/nginx/sites-available/funkwhale.template "$FUNKWHALE_VERSION/deploy/docker.proxy.template"
  3. Update the Nginx configuration with details from your .env file

    # set -a && source /srv/funkwhale/config/.env && set +a
    envsubst "`env | awk -F = '{printf \" $%s\", $$1}'`" \
       < /etc/nginx/sites-available/funkwhale.template \
       > /etc/nginx/sites-available/funkwhale.conf
  4. Check the configuration file to make sure the template values have been updated properly

    # grep '${' /etc/nginx/sites-available/funkwhale.conf

Once you’ve updated your configuration, reload Nginx.

# systemctl reload nginx

Upgrade the Postgres container

Funkwhale depends on Postgres for its database container. To upgrade Postgres, you need to export your database and import it into a new container to update the schema.

To update your Postgres container, follow these steps:

  1. Stop all Funkwhale services

    # docker compose down
  2. Create a backup of your Funkwhale database. We will import this into the new postgres container later.

    # docker compose run --rm postgres pg_dump -U postgres postgres > db_dump.sql
  3. Move the data/postgres directory to another location to back it up

    $ mv data/postgres data/postgres.bak
  4. Create a new data/postgres directory to house your data

    $ mkdir data/postgres
  5. Edit the docker-compose.yml file in an editor of your choice.

    $ nano docker-compose.yml
  6. Update the version number in the image section of the postgres service to the major version you want to use. In this example, Postgres version 15 is used.

    version: "3"
      restart: unless-stopped
      env_file: .env
      image: postgres:15-alpine
        - ./data/postgres:/var/lib/postgresql/data
  7. Save the file and close your editor

Once you’ve updated your Postgres containers, you need to migrate your database. To do this:

  1. Start up your new database container.

    # docker compose up -d postgres
  2. Import your database dump into the new container.

    # cat db_dump.sql | docker compose exec -T postgres psql -U postgres
  3. Run the database migrations.

    # docker compose run --rm api funkwhale-manage migrate

Start your Funkwhale instance

Once you have imported your database and run migrations, you can start all containers.

# docker compose up -d

See also

You can use the postgres-upgrade container to automate some of the upgrade procedure on AMD64 Docker deployments.

That’s it! Your Funkwhale pod is now running the new version of Postgres. The old database is available in /srv/funkwhale/data/postgres-old. You can back this up and remove it from your server once you’ve confirmed everything is working.