docs(docker): readability, cross-references+ networking details
This commit is contained in:
jon r
parent
ac4600cec9
commit
660270e1d3
|
|
@ -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).
|
||||
|
|
|
|||
Loading…
Reference in New Issue