MirrorMirror
/
funkwhale
mirror of https://dev.funkwhale.audio/funkwhale/funkwhale.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

docs(docker): readability, cross-references+ networking details

This commit is contained in:
jon r 2024-10-11 15:36:50 +02:00
parent ac4600cec9
commit 660270e1d3
1 changed files with 45 additions and 22 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

67
docs/developer/setup/docker.md
View File

@ -62,9 +62,8 @@ To set up your Docker environment:
## Set up auxiliary services ## Set up auxiliary services
To support ActivityPub in the local development environment, we use a To support ActivityPub in the local development environment, we use a
combination of auxiliary services that provide DNS-based discovery and web/TLS 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
termination. This also has the benefit that we can talk to our development our development instance(s) with using regular domain names.
instance(s) with using regular domain names.
The needed certificate is generated and installed to system and The needed certificate is generated and installed to system and
browser with `mkcert`. Dynamic DNS resolution of local domain names in the 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 between the containers and between the host and the containers is provided by
Træfik. 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 ```sh
mkcert -install -cert-file compose/var/test.crt -key-file compose/var/test.key "funkwhale.test" "*.funkwhale.test" 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 2. Launch the Træfik web proxy, the dnsmasq resolver and the nullmailer using
the `net` manifest: the `net` manifest:
@ -189,40 +204,39 @@ Then run the network services to access the running containers.
:::: ::::
:::{tip} :::{hint}
You can now reach your Træfik dashboard at [`http://funkwhale.test:8008/dashboard/`](http://funkwhale.test:8008/dashboard/) (note the trailing slash `/`). 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 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/).
[`https://traefik.funkwhale.test/dashboard/`](https://traefik.funkwhale.test/dashboard/).
::: :::
:::{note} :::{note}
If your `docker0` network has running containers not belonging to Funkwhale If your `docker0` network has running containers not belonging to Funkwhale
already attached to it, comment out the `net.helpers.docker0.yml` rule in already attached to it, comment out the `net.helpers.docker0.yml` rule in
`compose.net.yml`. `compose.net.yml`. Then restart the networking stack with
`docker compose -f compose.net.yml up -d`.
Then restart the networking stack with `docker compose -f compose.net.yml up -d`.
::: :::
## Set up application services ## 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 ```sh
docker compose up -d 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} :::{tip}
This gives you access to the following: This gives you access to the following:
- The Funkwhale web app on [`https://funkwhale.funkwhale.test`](https://funkwhale.funkwhale.test) - 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 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 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 ```sh
docker compose run --rm api funkwhale-manage fw users create --superuser docker compose run --rm api funkwhale-manage fw users create --superuser
@ -234,6 +248,8 @@ Review the configuration:
docker compose config docker compose config
``` ```
### Lifecycle
Recycle individual containers: Recycle individual containers:
```sh ```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 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 run --rm api funkwhale-manage fw users create --superuser
COMPOSE_PROJECT_NAME=node2 VUE_PORT=1235 docker compose up -d 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 Proceed freely with different sets of values for `COMPOSE_PROJECT_NAME` and
`VUE_PORT`. `VUE_PORT`.
@ -363,10 +379,17 @@ to learn how else you may interact directly with containers, when needed.
## Local documentation ## Local documentation
To build the documentation locally while watching for changes, run: To build the documentation locally run:
```sh ```sh
docker compose -f compose.docs.yml up -d 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).