|
|
|
|
@ -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)
|
|
|
|
|
|
jon r