docs(compose): extend documentation + settle configuration

compose.docs.yml

@@ -1,10 +1,22 @@
-name: funkwhale-development
+name: funkwhale-docs
+networks:
+  web:
+    external: true
 services:
-  poetry:
+  sphinx:
     build:
-      context: "docker/context/docs"
+      context: "compose/context/docs"
     init: true
     ports: ["8001:8001"]
     command: sh -c 'cd /src/docs && make install && make dev'
     volumes:
       - ${PWD}:/src
+    labels:
+      - "traefik.enable=true"
+      - "traefik.http.routers.whoami-web.rule=Host(`docs.funkwhale.test`)"
+      - "traefik.http.routers.whoami-web.entrypoints=web"
+
+      - "traefik.http.routers.whoami-webs.rule=Host(`docs.funkwhale.test`)"
+      - "traefik.http.routers.whoami-webs.entrypoints=webs"
+      - "traefik.http.routers.whoami-webs.tls=true"
+    networks: ["web"]

compose.net.yml

@@ -1,4 +1,4 @@
-name: funkwhale-services
+name: funkwhale-net
 include:
   - path: compose/net.dnsmasq.yml
   - path: compose/net.traefik.yml

compose.yml

@@ -1,6 +1,6 @@
 networks:
   internal:
-  federation:
+  web:
     external: true
 
 x-django: &django
@@ -88,7 +88,7 @@ services:
       - STATIC_ROOT
       - "MEDIA_ROOT=${MEDIA_ROOT:-/data/media}"
     networks:
-      - federation
+      - web
       - internal
 
     labels:

compose/etc/traefik/dynamic/api-dashboard.yml

@@ -0,0 +1,13 @@
+http:
+  routers:
+    dashboard-web:
+      rule: Host(`traefik.funkwhale.test`) && (PathPrefix(`/api`) || PathPrefix(`/dashboard`))
+      service: api@internal
+      entryPoints:
+        - web
+    dashboard-webs:
+      rule: Host(`traefik.funkwhale.test`) && (PathPrefix(`/api`) || PathPrefix(`/dashboard`))
+      service: api@internal
+      entryPoints:
+        - webs
+      tls: true

compose/net.helpers.docs.yml

@@ -0,0 +1,15 @@
+networks:
+  web:
+    external: true
+
+services:
+  sphinx:
+    labels:
+      - "traefik.enable=true"
+      - "traefik.http.routers.whoami-web.rule=Host(`docs.funkwhale.test`)"
+      - "traefik.http.routers.whoami-web.entrypoints=web"
+
+      - "traefik.http.routers.whoami-webs.rule=Host(`docs.funkwhale.test`)"
+      - "traefik.http.routers.whoami-webs.entrypoints=webs"
+      - "traefik.http.routers.whoami-webs.tls=true"
+    networks: ["web"]

compose/net.helpers.yml

@@ -6,14 +6,14 @@ x-busybox: &busybox
   dns_search: funkwhale.test
 
 networks:
-  federation:
+  web:
     external: true
 
 services:
   whoami:
     image: "traefik/whoami"
     networks:
-      - federation
+      - web
     labels:
       - "traefik.enable=true"
       - "traefik.http.routers.whoami-web.rule=Host(`whoami.funkwhale.test`)"

compose/net.minio.yml

@@ -11,7 +11,7 @@ services:
     ports:
       - "9000:9000"
     networks:
-      - federation
+      - web
       - internal
 
   api:

docs/developer/setup/docker.md

@@ -49,9 +49,9 @@ Funkwhale provides a `compose.yml` file following the default file naming conven
 
 To set up your Docker environment:
 
-1. Create a network for federation support:
+1. Create a network for federation support via the web proxy:
    ```sh
-   docker network create federation
+   docker network create web
    ```
 2. Then build the application containers. Run this command any time there are upstream changes or dependency changes to ensure you're up-to-date.
 
@@ -61,6 +61,17 @@ To set up your Docker environment:
 
 ## Set up auxiliary services
 
+To support ActivityPub in the local development environment, we use a
+combination of auxiliary services that provide DNS-based discovery and web/TLS
+termination. This also has the benefit that we can talk to our development
+instance(s) with using regular domain names.
+
+The needed certificate is generated and installed to system and
+browser with `mkcert`. Dynamic DNS resolution of local domain names in the
+`funkwhale.test` zone is provided by dnsmasq. Proxying secure web traffic
+between the containers and between the host and the containers is provided by
+Træfik.
+
 1. Create a wildcard certificate for `funkwhale.test` and `*.funkwhale.test` which will be installed into your system and browser trust stores with:
    ```sh
    mkcert -install -cert-file compose/var/test.crt -key-file compose/var/test.key "funkwhale.test" "*.funkwhale.test"
@@ -68,37 +79,74 @@ To set up your Docker environment:
 
 Then run the network services to access the running containers.
 
-2. Launch Træfik and dnsmasq using the bundled configuration:
+2. Launch the Træfik web proxy and the dnsmasq resolver using the `net` manifest:
 
    ```sh
    docker compose -f compose.net.yml up -d
    ```
 
-3. Add the DNS search domain for `~funkwhale.test` to your system. This allows your system to dereference our domain names `funkwhale.funkwhale.test`, `node2.funkwhale.test`, `node3.…`, `…` to the IP address of the Træfik reverse proxy listening at `172.17.0.1`.
+   Manage the networking services with regular [Compose life cycle commands](https://docs.docker.com/reference/cli/docker/compose/):
+
+   `config`, `ps`, `stop`, `rm`, `down`, …
+
+3. Add the DNS search domain for `~funkwhale.test` to your system. This allows your system to dereference our domain names `funkwhale.funkwhale.test`, `node1.funkwhale.test`, `node2.…`, `…` to the IP address of the Træfik reverse proxy listening at `172.17.0.1`.
 
    ::::{tab-set}
 
    :::{tab-item} Linux
 
+   Considering your Linux uses systemd-resolved for local DNS resolution, apply:
+
    ```sh
    sudo resolvectl dns docker0 172.17.0.1
    sudo resolvectl domain docker0 '~funkwhale.test.'
    ```
 
+   Please refer to the manual of your distribution for other configurations.
+
    :::
 
    :::{tab-item} Mac
-   Follow the instructions at [macOS: Using Custom DNS Resolvers · vNinja.net] (https://vninja.net/2020/02/06/macos-custom-dns-resolvers/)
+
+   To set up `172.17.0.1` as the search domain for the `funkwhale.test` zone of your mac OS system, please follow the instructions at [macOS: Using Custom DNS Resolvers · vNinja.net] (https://vninja.net/2020/02/06/macos-custom-dns-resolvers/).
+
+   For [Docker on Mac](https://docs.docker.com/desktop/install/mac-install/) you
+   will also need to install and use [recap/docker-mac-routes](https://github.com/recap/docker-mac-routes)
+   each time the Docker VM is restarted.
+
+   For [OrbStack]() make sure:
+
+   - to configure the [Container IP ranges](https://docs.orbstack.dev/docker/network#container-ip-ranges)
+     of the Docker daemon to resemble the default Docker configuration. This
+     helps to recreate the expected environment for DNS + HTTPS networking.
+     E.g.:
+
+     ```json
+     {
+       "bip": "172.17.0.1/23",
+       "default-address-pools": [
+         { "base": "172.17.0.0/19", "size": 23 },
+         { "base": "172.18.0.0/19", "size": 23 }
+       ]
+     }
+     ```
+
+   - to disable its [HTTPS for containers](https://docs.orbstack.dev/features/https)
+     function, as we are supplying our own Træfik instance.
+
    :::
 
    ::::
 
 :::{tip}
-You can now reach your Træfik dashboard at [`http://funkwhale.test:8008/dashboard/#/http/routers`](http://funkwhale.test:8008/dashboard/#/http/routers).
+You can now reach your Træfik dashboard at [`http://funkwhale.test:8008/dashboard/`](http://funkwhale.test:8008/dashboard/) (note the trailing slash `/`).
+
+When everything works as expected, you can also access it at
+[`https://traefik.funkwhale.test/dashboard/`](https://traefik.funkwhale.test/dashboard/).
 :::
 
 :::{note}
-If your `docker0` network has no running containers presently attached to it, uncomment the `net.helpers.docker0.yml` rule in `compose.net.yml`.
+If your `docker0` network has running containers presently attached to it, comment out the `net.helpers.docker0.yml` rule in `compose.net.yml`.
 
 Then restart the networking stack with `docker compose -f compose.net.yml up -d`.
 :::
@@ -127,6 +175,18 @@ Create a local superuser to be able to login:
 docker compose run --rm api funkwhale-manage fw users create --superuser
 ```
 
+Review the configuration:
+
+```sh
+docker compose config
+```
+
+Recycle individual containers:
+
+```sh
+docker compose rm -sf api celeryworker; docker compose up -d api celeryworker
+```
+
 Once you're done with the containers, you can stop them all:
 
 ```sh
@@ -139,16 +199,23 @@ If you want to destroy your containers, run the following:
 docker compose down
 ```
 
-Destroy the state of your containers:
+Destroy all state of your containers:
 
 ```sh
 docker compose down --volumes
+```
+
+Remove all state of all Funkwhale-related containers, incl. from additional
+instances:
+
+```sh
 rm -rf .state/
 ```
 
 ### Running multiple instances
 
-Set up as many different projects as you need. Make sure the `COMPOSE_PROJECT_NAME` and `VUE_PORT` variables are unique per instance
+Set up as many different projects as you need. Make sure the
+`COMPOSE_PROJECT_NAME` and `VUE_PORT` variables are unique per instance.
 
 ```sh
 export COMPOSE_PROJECT_NAME=node2
@@ -160,8 +227,93 @@ docker compose up -d
 
 You can access your project at `https://{COMPOSE_PROJECT_NAME}.funkwhale.test`.
 
-:::{warning}
+:::{admonition} Running and accessing multiple instances in parallel
-Federation between Alpine containers in Docker is broken due to upstream errors.
+:class: hint
 
-- [Error while fetching the library: musl + getaddrinfo()](https://docs.allmende.io/s/03534f44-9514-40b8-a40a-df4a027b908b) (German)
+You may as well address the different Compose projects by using ad hoc
-  :::
+environment variables:
+
+```
+COMPOSE_PROJECT_NAME=node1 VUE_PORT=1234 docker compose run --rm api funkwhale-manage fw users create --superuser
+COMPOSE_PROJECT_NAME=node1 VUE_PORT=1234 docker compose up -d
+```
+
+The `node1` instance will be available at [`https://node1.funkwhale.test`](https://node1.funkwhale.test).
+
+```
+COMPOSE_PROJECT_NAME=node2 VUE_PORT=1235 docker compose run --rm api funkwhale-manage fw users create --superuser
+COMPOSE_PROJECT_NAME=node2 VUE_PORT=1235 docker compose up -d
+```
+
+The `node2` instance will be available at [`https://node2.funkwhale.test`](https://node2.funkwhale.test).
+
+Proceed freely with different sets of values for `COMPOSE_PROJECT_NAME` and
+`VUE_PORT`.
+
+:::
+
+::::{tab-set}
+
+:::{tab-item} Stop everything
+
+In case you wanted to stop everything after a day's work, you can remove all
+running containers:
+
+```sh
+docker compose -f compose.docs.yml rm -sf
+docker compose -f compose.net.yml rm -sf
+docker compose rm -sf
+```
+
+Repeat these steps for every additional instance:
+
+```sh
+COMPOSE_PROJECT_NAME=node1 docker compose rm -sf
+COMPOSE_PROJECT_NAME=node2 docker compose rm -sf
+COMPOSE_PROJECT_NAME=… docker compose rm -sf
+```
+
+:::
+
+:::{tab-item} Discover projects and containers
+
+List all currently running Compose projects to get an overview:
+
+```sh
+docker compose ls
+```
+
+Show all projects for which containers exist, including stopped ones:
+
+```sh
+docker compose ls -a
+```
+
+Ultimately Docker gives you an overview what is running:
+
+```sh
+docker ps
+```
+
+And also which containers are not running, but existing:
+
+```sh
+docker ps -a
+```
+
+Refer to the [Docker CLI documentation](https://docs.docker.com/reference/cli/docker/)
+to learn how else you may interact directly with containers, when needed.
+
+:::
+
+::::
+
+## Local documentation
+
+To build the documentation locally while watching for changes, run:
+
+```sh
+docker compose -f compose.docs.yml up -d
+```
+
+The documentation is then accessible at [`https://docs.funkwhale.test`](https://docs.funkwhale.test)