Docker installation
Docker is the easiest way to get a Funkwhale instance up and running.
We support two types of Docker deployments:
Mono-container: all processes live in the same container (database, nginx, redis, etc.). It’s easier to deploy and to integrate with container management systems like Portainer. However, it’s not possible to scale this type of deployment on multiple servers.
Multi-container: each process lives in a dedicated container. This setup is more involved but also more flexible and scalable.
Warning
The All-In-One-Container or Mono-Container installation is deprecated, don’t use it for new installations. For more information, visit our blog: https://blog.funkwhale.audio/deprecation-all-in-one-container.html
Mono-container installation
Warning
The All-In-One-Container or Mono-Container installation is deprecated, don’t use it for new installations. For more information, visit our blog: https://blog.funkwhale.audio/deprecation-all-in-one-container.html
Note
This installation method was originally contributed by @thetarkus
These are the installation steps:
Install docker
Create
funkwhale
userCreate
.env
fileCreate
docker-compose.yml
fileStart Funkwhale service
Install docker
Ensure you have Docker and docker-compose installed.
Create funkwhale
user
Create the user and the directory:
sudo useradd -r -s /usr/bin/nologin -m -d /srv/funkwhale -U -G docker funkwhale
cd /srv/funkwhale
Log in as the newly created user from now on:
sudo -u funkwhale -H bash
Create .env
file
Create a .env
file to store a few important configuration options:
touch .env
chmod 600 .env # reduce permissions on the .env file since it contains sensitive data
cat > .env << EOF
# Replace 'your.funkwhale.example' with your actual domain
FUNKWHALE_HOSTNAME=your.funkwhale.example
# Protocol may also be: http
FUNKWHALE_PROTOCOL=https
# This limits the upload size
NGINX_MAX_BODY_SIZE=100M
# Bind to localhost
FUNKWHALE_API_IP=127.0.0.1
# Container port you want to expose on the host
FUNKWHALE_API_PORT=5000
# Generate and store a secure secret key for your instance
DJANGO_SECRET_KEY=$(openssl rand -hex 45)
# Remove this if you expose the container directly on ports 80/443
NESTED_PROXY=1
EOF
Create docker-compose.yml
file
Create a docker-compose.yml
file to set up the containers:
version: "3" services: funkwhale: container_name: funkwhale restart: unless-stopped # change version number here when you want to do an upgrade image: funkwhale/all-in-one:1.2.10 env_file: .env environment: # adapt to the pid/gid that own /srv/funkwhale/data - PUID=1000 - PGID=1000 volumes: - /srv/funkwhale/data:/data - /path/to/your/music/dir:/music:ro ports: - "5000:80"
Note
The version can be changed (after
funkwhale/all-in-one:
), select the version you want to deploy.PUID
andPGID
are optional but useful to prevent permission issues with docker volumes/path/to/your/music/dir
should point to a path on your host where music you would like to import is located. You can safely remove the volume if you don’t want to import music that way.
Start Funkwhale service
Start the container:
docker-compose up -d
Your container should start in the background, and your instance be available at yourip:5000
shortly.
You will need an admin account to login and manage your account, create one using the following command: docker exec -it funkwhale manage createsuperuser
Useful commands:
You can start and stop your instance using
docker-compose start
anddocker-compose stop
, respectivelyYou can examine the logs by running
docker logs -f --tail=50 funkwhale
To have a better idea of the resource usage of your instance (CPU, memory), run
docker stats funkwhale
Now, you just need to configure your reverse-proxy. Don’t worry, it’s quite easy.
Multi-container installation
First, ensure you have Docker and docker-compose installed.
Export the version you want to deploy (e.g., 0.21
):
export FUNKWHALE_VERSION="1.2.10"
Download the sample docker-compose file:
mkdir /srv/funkwhale
cd /srv/funkwhale
mkdir nginx
curl -L -o nginx/funkwhale.template "https://dev.funkwhale.audio/funkwhale/funkwhale/raw/${FUNKWHALE_VERSION}/deploy/docker.nginx.template"
curl -L -o nginx/funkwhale_proxy.conf "https://dev.funkwhale.audio/funkwhale/funkwhale/raw/${FUNKWHALE_VERSION}/deploy/docker.funkwhale_proxy.conf"
curl -L -o docker-compose.yml "https://dev.funkwhale.audio/funkwhale/funkwhale/raw/${FUNKWHALE_VERSION}/deploy/docker-compose.yml"
At this point, the architecture of /srv/funkwhale
should look like that:
.
├── docker-compose.yml
└── nginx
├── funkwhale_proxy.conf
└── funkwhale.template
Create your env file:
curl -L -o .env "https://dev.funkwhale.audio/funkwhale/funkwhale/raw/${FUNKWHALE_VERSION}/deploy/env.prod.sample"
sed -i "s/FUNKWHALE_VERSION=latest/FUNKWHALE_VERSION=$FUNKWHALE_VERSION/" .env
chmod 600 .env # reduce permissions on the .env file since it contains sensitive data
sudo nano .env
Ensure to edit it to match your needs (this file is heavily commented), in particular DJANGO_SECRET_KEY
and FUNKWHALE_HOSTNAME
.
You should take a look at the configuration reference for more detailed information regarding each setting.
Then, you should be able to pull the required images:
docker-compose pull
Run the database container and the initial migrations:
docker-compose up -d postgres
docker-compose run --rm api python manage.py migrate
Warning
You may sometimes get the following warning while applying migrations:
"Your models have changes that are not yet reflected in a migration, and so won't be applied."
This is a warning, not an error, and it can be safely ignored.
Never run the makemigrations
command yourself.
Create your admin user:
docker-compose run --rm api python manage.py createsuperuser
Then launch the whole thing:
docker-compose up -d
Now, you just need to configure your reverse-proxy. Don’t worry, it’s quite easy.
About music acquisition
If you want to import music located on the server, you can put it in the data/music
directory and it will become readable by the importer.