Skip to content


Funkwhale is a decentralized, federated, and open music streaming / sharing platform. Think of it as "Mastodon for music".

Funkwhale Screenshot

The idea is that you run a "pod" (just like whales, Funkwhale users gather in pods). A pod is a website running the Funkwhale server software. You join the network by registering an account on a pod (sometimes called "server" or "instance"), which will be your home.

You will be then able to interact with other people regardless of which pod they are using.

Funkywhale Requirements


Already deployed:



Setup data locations

First we create a directory to hold our funky data:

mkdir /var/data/funkwhale

Prepare Funkywhale environment

Funkwhale is configured using environment variables. Create /var/data/config/funkwhale/funkwhale.env, by running something like this:

mkdir -p /var/data/config/funkwhale/
cat > /var/data/config/funkwhale/funkwhale.env << EOF
# Replace '' with your actual domain
# Protocol may also be: http
# This limits the upload size
# Bind to localhost
# Container port you want to expose on the host
# Generate and store a secure secret key for your instance
DJANGO_SECRET_KEY=$(openssl rand -hex 45)
# Remove this if you expose the container directly on ports 80/443
# adapt to the pid/gid that own /var/data/funkwhale/
# reduce permissions on the .env file since it contains sensitive data
chmod 600 /var/data/funkwhale/funkwhale.env  

Funkywhale Docker Swarm config

Create a docker swarm config file in docker-compose syntax (v3) (I store all my config files as /var/data/config/<stack name\>/<stack name\>.yml), something like this:

Fast-track with premix! 🚀

I automatically and instantly share (with my sponsors) a private "premix" git repository, which includes necessary docker-compose and env files for all published recipes. This means that sponsors can launch any recipe with just a git pull and a docker stack deploy 👍.

🚀 Update: Premix now includes an ansible playbook, so that sponsors can deploy an entire stack + recipes, with a single ansible command! (more here)

version: "3.2" #

    image: funkwhale/all-in-one:1.0.1
    env_file: /var/data/config/funkwhale/funkwhale.env
      - /var/data/funkwhale/:/data/
      - /path/to/your/music/dir:/music:ro
        # traefik common
        - "traefik.enable=true"
        - ""

        # traefikv1
        - ""
        - "traefik.port=80"

        # traefikv2
        - "traefik.http.routers.linx.rule=Host(``)"
        - "traefik.http.routers.linx.entrypoints=https"
        - "" 
      - traefik_public

    external: true


Unleash the Whale! 🐳

Launch the Funkwhale stack by running docker stack deploy funkwhale -c <path -to-docker-compose.yml>, and then watch the container logs using docker stack logs funkywhale_funkywhale<tab-completion-helps>.

You'll know the container is ready when you see an ascii version of the Funkwhale logo, followed by:

[2021-01-27 22:52:24 +0000] [411] [INFO] ASGI 'lifespan' protocol appears unsupported.
[2021-01-27 22:52:24 +0000] [411] [INFO] Application startup complete.

The first time we run Funkwhale, we need to setup the superuser account.


If you're running a multi-node swarm, this next step needs to be executed on the node which is currently running Funkwhale. Identify this with docker stack ps funkwhale

Run something like the following:

docker exec -it funkwhale_funkwhale.1.<tab-completion-helps-here\> \
  manage createsuperuser \
  --username admin \
  --email <your admin email address\>

You'll be prompted to enter the admin password - here's some sample output:

root@swarm:~# docker exec -it funkwhale_funkwhale.1.gnx96tfr0lgmx5u3e8x4tkags \
  manage createsuperuser \
  --username admin \
2021-01-27 22:44:01,953 funkwhale_api.config INFO     Running with the following plugins enabled: funkwhale_api.contrib.scrobbler
Password (again):
Superuser created successfully.

Chef's notes 📓

  1. Since the whole purpose of media sharing is to share publically, and Funkwhale includes robust user authentication, this recipe doesn't employ traefik-based authentication using Traefik Forward Auth

  2. These instructions are an opinionated simplication of the official instructions found at 

  3. It should be noted that if you import your existing media, the files will be copied into Funkwhale's data folder. There doesn't seem to be a way to point Funkwhale at an existing collection and have it just play it from the filesystem. To this end, be prepared for double disk space usage if you plan to import your entire music collection! 

  4. No consideration is given at this point to backing up the Funkwhale data. Post a comment below if you'd like to see a backup container added! 

Tip your waiter (sponsor) 👏

Did you receive excellent service? Want to compliment the chef? (..and support development of current and future recipes!) Sponsor me on Github / Ko-Fi / Patreon, or see the contribute page for more (free or paid) ways to say thank you! 👏

Employ your chef (engage) 🤝

Is this too much of a geeky PITA? Do you just want results, stat? I do this for a living - I'm a full-time Kubernetes contractor, providing consulting and engineering expertise to businesses needing short-term, short-notice support in the cloud-native space, including AWS/Azure/GKE, Kubernetes, CI/CD and automation.

Learn more about working with me here.

Flirt with waiter (subscribe) 💌

Want to know now when this recipe gets updated, or when future recipes are added? Subscribe to the RSS feed, or leave your email address below, and we'll keep you updated.

Your comments? 💬