Funkwhale

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

Ingredients

Already deployed:

Docker swarm cluster with persistent shared storage
Traefik configured per design
DNS entry for the hostname you intend to use (or a wildcard), pointed to your keepalived IP

Traefik Forward Auth or Authelia to secure your Traefik-exposed services with an additional layer of authentication

Preparation

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 'funkwhale.example.com' with your actual domain
FUNKWHALE_HOSTNAME=funkwhale.example.com
# Protocol may also be: http
FUNKWHALE_PROTOCOL=https
# This limits the upload size
NGINX_MAX_BODY_SIZE=100M
# Bind to localhost
FUNKWHALE_API_IP=127.0.0.1
# Container port you want to expose on the host
FUNKWHALE_API_PORT=80
# 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
NESTED_PROXY=1
# adapt to the pid/gid that own /var/data/funkwhale/
PUID=1000
PGID=1000
EOF
# 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! 🚀

"Premix" is a git repository which includes necessary docker-compose and env files for all published recipes. This means that you can launch any recipe with just a git pull and a docker stack deploy 👍.

🚀 Update: Premix now includes an ansible playbook, enabling you to deploy an entire stack + recipes, with a single ansible command! (more here)

version: "3.2" # https://docs.docker.com/compose/compose-file/compose-versioning/#version-3

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

        # traefikv1
        - "traefik.frontend.rule=Host:funkwhale.example.com"
        - "traefik.port=80"

        # traefikv2
        - "traefik.http.routers.linx.rule=Host(`funkwhale.example.com`)"
        - "traefik.http.routers.linx.entrypoints=https"
        - "traefik.http.services.linx.loadbalancer.server.port=80" 
    networks:
      - traefik_public

networks:
  traefik_public:
    external: true

Serving

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.

Tip

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 \
  --email admin@funkypenguin.co.nz
2021-01-27 22:44:01,953 funkwhale_api.config INFO     Running with the following plugins enabled: funkwhale_api.contrib.scrobbler
Password:
Password (again):
Superuser created successfully.
root@swarm:~#

Chef's notes 📓

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. ↩
These instructions are an opinionated simplication of the official instructions found at https://docs.funkwhale.audio/installation/docker.html ↩
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! ↩
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! ↩

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.

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.