From 660270e1d348f85db47bf1b460282b84bb9d24fb Mon Sep 17 00:00:00 2001 From: jon r Date: Fri, 11 Oct 2024 15:36:50 +0200 Subject: [PATCH] docs(docker): readability, cross-references+ networking details --- docs/developer/setup/docker.md | 67 +++++++++++++++++++++++----------- 1 file changed, 45 insertions(+), 22 deletions(-) diff --git a/docs/developer/setup/docker.md b/docs/developer/setup/docker.md index 894e83830..2d97757a6 100644 --- a/docs/developer/setup/docker.md +++ b/docs/developer/setup/docker.md @@ -62,9 +62,8 @@ 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. +combination of auxiliary services that provide DNS-based discovery, local email delivery 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 @@ -72,12 +71,28 @@ browser with `mkcert`. Dynamic DNS resolution of local domain names in the 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: +The services bind to the following ports on the default Docker bridge network: + +| Service | Description | Protocol | Port(s) | +| ---------------------------------------------------- | ------------------------------------- | -------- | --------------- | +| [dnsmasq](https://dnsmasq.org/docs/dnsmasq-man.html) | Name server and recursive resolver | DNS | 172.17.0.1:53 | +| [Træfik v2](https://doc.traefik.io/traefik/v2.11/) | TLS offloader and web proxy | HTTP | 172.17.0.1:80 | +|   |   | HTTPS | 172.17.0.1:443 | +|   | API dashboard | HTTP | 172.17.0.1:8008 | +| [Mailpit](https://mailpit.axllent.org/docs/) | Mail-delivery agent (MDA), Nullmailer | SMTP | 172.17.0.1:1025 | +|   |   | HTTP | 172.17.0.1:8025 | + +1. Create a wildcard certificate for the Common Name (CN) `funkwhale.test` and + the Subject Alternative Name (SAN) `*.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" ``` + It will be used by Træefik to secure connections, which is needed for + ActivityPub to work locally. -Then run the network services to access the running containers. +Then run the network services used for convenient access to application +containers. 2. Launch the Træfik web proxy, the dnsmasq resolver and the nullmailer using the `net` manifest: @@ -189,40 +204,39 @@ Then run the network services to access the running containers. :::: -:::{tip} -You can now reach your Træfik dashboard at [`http://funkwhale.test:8008/dashboard/`](http://funkwhale.test:8008/dashboard/) (note the trailing slash `/`). +:::{hint} +You can now reach your Træfik dashboard at [http://172.17.0.1:8008/dashboard/](http://172.17.0.1:8008/dashboard/). The DNS server will answer requests to `172.17.0.1:53`. The SMTP MDA listens on `172.17.0.1:1025` and has a web interface at +[http://172.17.0.1:8025/](http://172.17.0.1:8025/) -When everything works as expected, you can also access it at -[`https://traefik.funkwhale.test/dashboard/`](https://traefik.funkwhale.test/dashboard/). +When all works as expected, you can also access [https://traefik.funkwhale.test/dashboard/](https://traefik.funkwhale.test/dashboard/) and [https://mailpit.funkwhale.test/](https://mailpit.funkwhale.test/). ::: :::{note} If your `docker0` network has running containers not belonging to Funkwhale already 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`. +`compose.net.yml`. Then restart the networking stack with +`docker compose -f compose.net.yml up -d`. ::: ## Set up application services -Once you have set up the dependencies, launch all services to start working: +Once you have set up the dependencies, launch all services to start developing: ```sh docker compose up -d ``` -Find instructions for starting multiple instances further below. +Find instructions for [starting multiple instances for federation](#running-multiple-instances) further below. :::{tip} This gives you access to the following: -- The Funkwhale web app on [`https://funkwhale.funkwhale.test`](https://funkwhale.funkwhale.test) -- The Funkwhale API on [`https://funkwhale.funkwhale.test/api/v1`](https://funkwhale.funkwhale.test/api/v1) -- The Django admin interface on [`https://funkwhale.funkwhale.test/api/admin`](https://funkwhale.funkwhale.test/api/admin) +- The Funkwhale web app on [https://funkwhale.funkwhale.test](https://funkwhale.funkwhale.test) +- The Funkwhale API on [https://funkwhale.funkwhale.test/api/v1](https://funkwhale.funkwhale.test/api/v1) +- The Django admin interface on [https://funkwhale.funkwhale.test/api/admin](https://funkwhale.funkwhale.test/api/admin) ::: -Create a local superuser to be able to login: +Create a local superuser to be able to login and to manage the service: ```sh docker compose run --rm api funkwhale-manage fw users create --superuser @@ -234,6 +248,8 @@ Review the configuration: docker compose config ``` +### Lifecycle + Recycle individual containers: ```sh @@ -291,14 +307,14 @@ COMPOSE_PROJECT_NAME=node1 VUE_PORT=1234 docker compose run --rm api funkwhale-m 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). +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). +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`. @@ -363,10 +379,17 @@ to learn how else you may interact directly with containers, when needed. ## Local documentation -To build the documentation locally while watching for changes, run: +To build the documentation locally run: ```sh docker compose -f compose.docs.yml up -d ``` -The documentation is then accessible at [`https://docs.funkwhale.test`](https://docs.funkwhale.test) +The documentation is then accessible at [https://docs.funkwhale.test](https://docs.funkwhale.test). The OpenAPI schema is available at [https://openapi.funkwhale.test](https://openapi.funkwhale.test). + +Fallback ports are available for the documentation at +[http://localhost:8001/](http://localhost:8001/) and for the OpenAPI schema at +[http://localhost:8002/](http://localhost:8002/). + +Maintain their life cycle with similar commands to those used to +[set up auxiliary services (point 2.)](#set-up-auxiliary-services).