funkwhale/docs/developer/setup/docker.md

# Develop using Docker

Funkwhale can be run in Docker containers for local development. You can work on any part of the Funkwhale codebase and run the container setup to test your changes. To work with Docker:

1. [Install Docker](https://docs.docker.com/install)
2. [Install docker compose](https://docs.docker.com/compose/install)
3. Clone the Funkwhale repository to your system. The `develop` branch is checked out by default

   ::::{tab-set}

   :::{tab-item} SSH

   ```sh
   git clone git@dev.funkwhale.audio/funkwhale/funkwhale.git
   cd funkwhale
   ```

   :::

   :::{tab-item} HTTPS

   ```sh
   git clone https://dev.funkwhale.audio/funkwhale/funkwhale.git
   cd funkwhale
   ```

   :::

   ::::

## Set up your Docker environment

```{note}
Funkwhale provides a `compose.yml` file following the default file naming convention of a Docker Compose manifest. For Linux users, we assume that you finished the post-install steps to [manage Docker as a non-root user](https://docs.docker.com/engine/install/linux-postinstall/#manage-docker-as-a-non-root-user).
```

To set up your Docker environment:

1. Create a `.env` file to enable customization of your setup.

   ```sh
   touch .env
   ```

2. Add the following variables to load images and enable access to Django admin pages:

   ```text
   MEDIA_URL=http://localhost:8000/media/
   STATIC_URL=http://localhost:8000/staticfiles/
   ```

3. Create a network for federation support

   ```sh
   docker network create federation
   ```

Once you've set everything up, you need to build the containers. Run this command any time there are upstream changes or dependency changes to ensure you're up-to-date.

```sh
docker compose build
```

## Manage services

Once you have set up your containers, launch all services to start working on them:

::::{tab-set}

:::{tab-item} Multi node federation testnet (Default)

```sh
docker compose -f compose.net.yml up -d
docker compose up -d
```

This gives you access to the following:

- The Funkwhale web app on `https://funkwhale.funkwhale.test`
- The Funkwhale API on `https://funkwhale.funkwhale.test/api/v1`
- The Django admin interface on `https://funkwhale.funkwhale.test/api/admin`

:::

:::{tab-item} Single node local development

```sh
docker compose -f compose.yml -f compose.local.yml up -d
```

This gives you access to the following:

- The Funkwhale web app on `http://localhost:8000`
- The Funkwhale API on `http://localhost:8000/api/v1`
- The Django admin interface on `http://localhost:8000/api/admin`

:::

::::

To be able to login create a local superuser:

```sh
docker compose run --rm api funkwhale-manage fw users create --superuser
```

Once you're done with the containers, you can stop them all:

```sh
docker compose stop
```

If you want to destroy your containers, run the following:

```sh
docker compose down
```

To also destroy the state of your containers, run:

```sh
docker compose down -v
```

## Set up local data

You can create local data to mimic a live environment.

Add some fake data to populate the database. The following command creates 25 artists with random albums, tracks, and metadata.

```sh
artists=25 # Adds 25 fake artists
command="from funkwhale_api.music import fake_data; fake_data.create_data($artists)"
echo $command | docker compose run --rm -T api funkwhale-manage shell -i python
```

## Set up federation support

Working on federation features requires additional setup. You need to do the following:

1. Update your DNS resolver to resolve all your `.test` hostnames locally
2. Set up a reverse proxy (such as traefik) to catch `.test` requests with a TLS certificate
3. Set up two or more local instances

To resolve hostnames locally, run the following:

::::{tab-set}

:::{tab-item} dnsmasq

```sh
echo "address=/test/172.17.0.1" | sudo tee /etc/dnsmasq.d/test.conf
sudo systemctl restart dnsmasq
```

:::

:::{tab-item} NetworkManager

```sh
echo "address=/test/172.17.0.1" | sudo tee /etc/NetworkManager/dnsmasq.d/test.conf
sudo systemctl restart NetworkManager
```

:::

:::{tab-item} dnsmasq in Docker

```sh
docker compose -f docker/dnsmasq.yml up -d
sudo resolvectl domain docker0 '~funkwhale.test.'
sudo resolvectl dns docker0 172.17.0.1
```

:::

::::

To add a wildcard certificate, copy the test certificate from the `docker/ssl` folder to your system store. This certificate is a wildcard for `*.funkwhale.test`.

For Debian-based systems like Ubuntu, run:

```sh
sudo cp docker/ssl/test.crt /usr/local/share/ca-certificates/
sudo update-ca-certificates
```

For RHEL-based systems like Fedora, run:

```sh
sudo cp docker/ssl/test.crt /etc/pki/ca-trust/source/anchors/
sudo update-ca-trust
```

To run a reverse proxy for your app:

1. Add the following configuration to your `.env` file:

   ```sh
   cat >> .env <<< "
   # Remove any port binding so you can specify this per-instance
   VUE_PORT_BINDING=
   # Disable certificate validation
   EXTERNAL_REQUESTS_VERIFY_SSL=false
   # Ensure all links use https
   FUNKWHALE_PROTOCOL=https
   # Disable host ports binding for the nginx container so that traefik handles everything
   NGINX_PORTS_MAPPING=80"
   ```

2. Launch traefik using the bundled configuration:

   ```sh
   docker compose -f docker/traefik.yml up -d
   ```

   Your previous instance is now reachable at https://funkwhale.funkwhale.test

3. 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
   # VUE_PORT this has to be unique for each instance
   export VUE_PORT=1234
   docker compose run --rm api funkwhale-manage fw users create --superuser
   docker compose up -d
   ```

   You can access your project at `https://{COMPOSE_PROJECT_NAME}.funkwhale.test`.

## Known issues and workarounds

- (systemd-resolved) Under certain conditions the `docker0` bridge does not stay up, which in turn deactivates any DNS configuration associated to the interface. Uncomment the prepared resolved helper in line #6 of `compose.net.yml` to fix this issue and restart the networking stack. `docker compose -f compose.net.yml up -d`
- Broken federation on Alpine containers