diff --git a/compose.docs.yml b/compose.docs.yml index 05393a1b7..41fa8fe32 100644 --- a/compose.docs.yml +++ b/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"] diff --git a/compose.net.yml b/compose.net.yml index dd28b603a..31a722cab 100644 --- a/compose.net.yml +++ b/compose.net.yml @@ -1,4 +1,4 @@ -name: funkwhale-services +name: funkwhale-net include: - path: compose/net.dnsmasq.yml - path: compose/net.traefik.yml diff --git a/compose.yml b/compose.yml index 5b0e065d0..355998790 100644 --- a/compose.yml +++ b/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: diff --git a/compose/etc/traefik/dynamic/api-dashboard.yml b/compose/etc/traefik/dynamic/api-dashboard.yml new file mode 100644 index 000000000..8e1d29a00 --- /dev/null +++ b/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 diff --git a/compose/net.helpers.docs.yml b/compose/net.helpers.docs.yml new file mode 100644 index 000000000..a8134190f --- /dev/null +++ b/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"] diff --git a/compose/net.helpers.yml b/compose/net.helpers.yml index 62f360f68..5820ee023 100644 --- a/compose/net.helpers.yml +++ b/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`)" diff --git a/compose/net.minio.yml b/compose/net.minio.yml index d4917b5d7..d82bf2dd0 100644 --- a/compose/net.minio.yml +++ b/compose/net.minio.yml @@ -11,7 +11,7 @@ services: ports: - "9000:9000" networks: - - federation + - web - internal api: diff --git a/docs/developer/setup/docker.md b/docs/developer/setup/docker.md index 62f0f7717..dec994504 100644 --- a/docs/developer/setup/docker.md +++ b/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} -Federation between Alpine containers in Docker is broken due to upstream errors. +:::{admonition} Running and accessing multiple instances in parallel +: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)