Add Funkwhale (#168)

Add "Funkwhale", the "Mastodon of Music Federation"

manuscript/CHANGELOG.md

@@ -8,6 +8,7 @@ hide:
 
 Recipe                             | Description                                                                         | Date
 -----------------------------------|-------------------------------------------------------------------------------------|--------------
+[Funkwhale](/recipes/funkwhale/) | Enjoy, share, and federate your music in your own funky "pod". Think "Mastodon for Music" :whale: :musical_note: | _28 Jan 2021_
 [CyberChef](/recipes/cyberchef/) | A web-based collection of useful tools for INFOSEC work, by the [GCHQ](https://en.wikipedia.org/wiki/GCHQ) | _19 Jan 2021_
 [Linx](/recipes/linx/)             | Quickly and securely share media/files with optional password-protection and expiry | _13 Jan 2021_
 [Komga](/recipes/komga/)           | Beautiful interface to manage and enjoy your comics / graphic novels                | _5 Jan 2021_

manuscript/recipes/funkwhale.md

@@ -0,0 +1,138 @@
+# Funkwhale
+
+[Funkwhale](https://funkwhale.audio) is a decentralized, federated, and open music streaming / sharing platform. Think of it as "Mastodon for music". Here's a nifty online [demo](https://demo.funkwhale.audio/) :musical_note:
+
+![Funkwhale Screenshot](../images/funkwhale.jpg)
+
+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.
+
+--8<-- "recipe-standard-ingredients.md"
+
+## Preparation
+
+### Setup data locations
+
+First we create a directory to hold our funky data:
+
+```
+mkdir /var/data/funkwhale
+```
+
+### Prepare environment
+
+Funkwhale is configured using environment variables. Create `/var/data/config/funkwhale/funkwhale.env`, by running something like this:
+
+```bash
+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  
+```
+
+### Setup Docker Swarm
+
+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:
+
+--8<-- "premix-cta.md"
+
+```yaml
+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:
+
+```bash
+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:
+
+```bash
+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:~#
+```
+
+
+[^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](/ha-docker-swarm/traefik-forward-auth/).
+[^2]: These instructions are an opinionated simplication of the official instructions found at https://docs.funkwhale.audio/installation/docker.html
+[^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!
+[^5]: 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!
+[^4]: If the funky whale is "playing your song", note that the funkwhale project is [looking for maintainers](https://blog.funkwhale.audio/~/Announcements/funkwhale-is-looking-for-new-maintainers/).
+
+--8<-- "recipe-footer.md"

mkdocs.yml

@@ -45,7 +45,8 @@ nav:
         - Docker Swarm Mode: ha-docker-swarm/docker-swarm-mode.md
         - Traefik: ha-docker-swarm/traefik.md
         - Traefik Forward Auth: 
-            - Start: ha-docker-swarm/traefik-forward-auth.md      
+            - Start: ha-docker-swarm/traefik-forward-auth.md 
+            - Google: ha-docker-swarm/traefik-forward-auth/google.md      
             - KeyCloak: ha-docker-swarm/traefik-forward-auth/keycloak.md
         - Registry: ha-docker-swarm/registry.md
         - Mail Server: recipes/mail.md
@@ -63,7 +64,6 @@ nav:
           - Headphones: recipes/autopirate/headphones.md
           - Lidarr: recipes/autopirate/lidarr.md
           - NZBHydra: recipes/autopirate/nzbhydra.md
-          - NZBHydra 2: recipes/autopirate/nzbhydra2.md
           - Ombi: recipes/autopirate/ombi.md
           - Jackett: recipes/autopirate/jackett.md
           - Heimdall: recipes/autopirate/heimdall.md
@@ -97,6 +97,7 @@ nav:
         - CyberChef: recipes/cyberchef.md
         - Duplicati: recipes/duplicati.md
         - ElkarBackup: recipes/elkarbackup.md
+        - Funkwhale: recipes/funkwhale.md
         - Ghost: recipes/ghost.md
         - GitLab: recipes/gitlab.md
         - GitLab Runner: recipes/gitlab-runner.md