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:

## Prerequisites

1. [Install Docker](https://docs.docker.com/install)
2. [Install Docker Compose](https://docs.docker.com/compose/install)
3. [Install mkcert](https://github.com/FiloSottile/mkcert#installation)
4. [Install pre-commit](https://pre-commit.com/#install)
5. 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
   ```

   :::

   ::::

6. Activate the pre-commit hook:
   ```sh
   pre-commit install
   ```
7. Finally, initialise the environment:
   ```sh
   cp .env.example .env
   ```

## Set up the 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 network for federation support:
   ```sh
   docker network create federation
   ```
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.

   ```sh
   docker compose build
   ```

## Set up auxiliary services

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"
   ```

Then run the network services to access the running containers.

2. Launch Træfik and dnsmasq using the bundled configuration:

   ```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`.

   ::::{tab-set}

   :::{tab-item} Linux

   ```sh
   sudo resolvectl dns docker0 172.17.0.1
   sudo resolvectl domain docker0 '~funkwhale.test.'
   ```

   :::

   :::{tab-item} Mac
   Follow the instructions at [macOS: Using Custom DNS Resolvers · vNinja.net] (https://vninja.net/2020/02/06/macos-custom-dns-resolvers/)
   :::

   ::::

:::{tip}
You can now reach your Træfik dashboard at [`http://funkwhale.test:8008/dashboard/#/http/routers`](http://funkwhale.test:8008/dashboard/#/http/routers).
:::

:::{note}
If your `docker0` network has no running containers presently attached to it, uncomment the `net.helpers.docker0.yml` rule in `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:

```sh
docker compose up -d
```

Find instructions for starting 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)
  :::

Create a local superuser to be able to login:

```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
```

Destroy the state of your containers:

```sh
docker compose down --volumes
rm -rf .state/
```

### Set up local data for development

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
```

### 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

```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`.

:::{warning}
Federation between Alpine containers in Docker is broken due to upstream errors.

- [Error while fetching the library: musl + getaddrinfo()](https://docs.allmende.io/s/03534f44-9514-40b8-a40a-df4a027b908b) (German)
  :::