Funkwhale is an audio hosting and streaming platform, similar to Soundcloud. It allows you to upload and publish audio, create libraries and share them with friends or family, and connect with other artists or creators who publish their own work. Unlike Soundcloud, Funkwhale allows you to own and control your own content, free from the control of any corporation or other entity.
NOTE: the following install instructions draw from the official Funkwhale documentation, particularly the Debian installation guide. We've made every effort to make sure our guides are accurate, but if the 10friends guide ever contradicts the official docs, you should defer to the latter. If you find any such contradictions, please contact us so we can fix them.
¶ DOCKER GUIDE
Those interested in installing Funkwhale via Docker instead can find instructions in the official documentation here:
https://docs.funkwhale.audio/installation/docker.html
¶ REQUIREMENTS
According to the hardware requirements listed in official documentation, Funkwhale is not especially CPU hungry, and should run fine on small hosting services. For a small number of users, the following minimums should be sufficient:
- CPU: 2 cores
- RAM: 1 GB (around ~500 MB may be enough, but it never hurts to have extra if possible).
- Storage: Varies depending on the number and size of files uploaded
If you can't meet the above listed hardware requirements, you can still attempt to run Funkwhale, but you should probably read the Optimization Guide in the official documentation to learn how to tune Funkwhale for lower performance.
NOTE: As of version 1.0, Funkwhale requires Python 3.6 or higher. As long as you're using at least Debian 10 ("buster") or Ubuntu 18.04 ("bionic") as your server's OS, this shouldn't be a problem. If you have any difficulties during installation, however, you can confirm your Python version with the following command:
python3 --version
If it returns a version below 3.6, you'll need to upgrade Python before you can continue.
Funkwhale supports multiple Operating Systems. For the sake of simplicity, our guide will assume you're using Debian/Ubuntu, but if you're using a different OS feel free to start from the Alternative installation methods section in the official documentation.
For each of the steps in this guide, you'll need to copy the commands shown into the prompt on your server and run them. It's okay if you don't understand what they all do, most of them will just automatically do the work needed to get Funkwhale installed and set up. Some commands may ask you for more input. Simply follow the instructions that appear and the installation will complete successfully. If you have any problems during installation, you can ask for help in the official Funkwhale channels here, or contact us here.
¶ INSTALLING REQUIRED PACKAGES
To install Funkwhale, we first need to install some other programs. These include:
- PostgreSQL and redis (database software)
- curl (to download Funkwhale releases)
- unzip (to unpack it)
- python3-pip, python3-venv, and python3-dev (Python modules needed to install/run Funkwhale)
- build-essential (a software compiler)
- ffmpeg (for audio encoding)
- nginx (a webserver)
First, refresh your package list:
sudo apt-get update
Then install the database software:
sudo apt-get install postgresql postgresql-contrib redis-server
Next, install other dependencies:
sudo apt-get install curl python3-pip python3-venv git unzip libldap2-dev libsasl2-dev gettext-base zlib1g-dev libffi-dev libssl-dev nginx
...and finally, our main Funkwhale dependencies:
sudo apt install build-essential ffmpeg libjpeg-dev libmagic-dev libpq-dev postgresql-client python3-dev make
¶ CREATING FUNKWHALE USER AND DIRECTORIES
Most of the Funkwhale files need to be stored in directory named /srv/funkwhale. We'll also need a dedicated funkwhale user to own those files and launch processes. Use the following commands to create both:
sudo useradd -r -s /usr/sbin/nologin -d /srv/funkwhale -m funkwhale
¶ DATABASE SETUP
Funkwhale needs a database to manage its users, accounts, and files (PostgreSQL). It also needs a cache server to speed up certain tasks, and handle music import (Redis). We've already installed both of these in the steps above, so now we need to set them up.
First, we need to log into a database shell:
sudo -u postgres psql
From here, we can create the funkwhale database:
CREATE DATABASE "funkwhale" WITH ENCODING 'utf8';
...and a database user to own it it:
CREATE USER funkwhale;
And then give that user the needed permissions:
GRANT ALL PRIVILEGES ON DATABASE funkwhale TO funkwhale;
You can now exit the database shell with Ctrl+D.
The funkwhale user account will need to be able to log into a database shell too, so let's make sure it can:
sudo -u funkwhale -H psql
Assuming there were no errors, you can now safely exit the database shell again with Ctrl+D.
Finally, we need to enable some database extensions for Funkwhale to work properly:
sudo -u postgres psql funkwhale -c 'CREATE EXTENSION "unaccent";'
sudo -u postgres psql funkwhale -c 'CREATE EXTENSION "citext";'
Fortunately, Redis is already set up automatically on installation, so we don't need to do any configuration on it.
¶ DOWNLOADING FUNKWHALE RELEASES
Log into Funkwhale's directory:
cd /srv/funkwhale
Then log into the funkwhale user account:
sudo -u funkwhale -H bash
The rest of the installation should be done as the funkwhale user, so you should stay logged into it until the instructions say otherwise.
Funkwhale will need several subdirectories for different files, so we need to create them:
mkdir -p config api data/static data/media data/music front
Now we can download the Funkwhale releases. This guide assumes version 1.1, the latest current release. We'll update the guide as new versions come out, but you should confirm this for yourself on the Release page of the official repository.
Funkwhale has two main components; the API (which handles music storage and user accounts), and the frontend (which is the part that users interact with).
First we download the API, unpack it into a temporary directory, move it to where it needs to be, and them delete the temporary directory:
curl -L -o "api-1.1.zip" "https://dev.funkwhale.audio/funkwhale/funkwhale/-/jobs/artifacts/1.1/download?job=build_api"
unzip "api-1.1.zip" -d extracted
mv extracted/api/* api/
rm -rf extracted
Then we do the same with the frontend files:
curl -L -o "front-1.1.zip" "https://dev.funkwhale.audio/funkwhale/funkwhale/-/jobs/artifacts/1.1/download?job=build_front"
unzip "front-1.1.zip" -d extracted
mv extracted/front .
rm -rf extracted
You can remove the ZIP archives if you wish, but leaving them where they are can help you remember which version you have installed.
¶ INSTALLING PYTHON DEPENDENCIES
Make sure we're in the main funkwhale directory:
cd /srv/funkwhale
Funkwhale needs to install several Python dependencies to work. To avoid having them interfere with other software on the server, we'll install them in a dedicated VIRTUAL ENVIRONMENT ("virtualenv" or "venv").
First, create the virtual environment:
python3 -m venv /srv/funkwhale/virtualenv
This environment is placed in a newly created directory, /srv/funkwhale/virtualenv
Now we need to activate the virtual environment with the following command:
source /srv/funkwhale/virtualenv/bin/activate
Then we can install the python dependencies:
pip install wheel
pip install -r api/requirements.txt
NOTE: the above commands should install all the python dependencies you need. In at least some cases, however, a few can slip between the cracks. "uvloop" and "httptools" in particular can turn up missing, so to avoid trouble later you can make sure they're installed by attempting to manually install them yourself:
pip install uvloop httptools
For any future python commands, make sure you've activated the virtualenv as above before running them to avoid errors.
¶ CONFIGURING FUNKWHALE
In order to configure Funkwhale, we need an environment file to store settings. First we'll download a sample environment file, then edit it to suit our needs.
First, download the sample environment file:
curl -L -o config/.env "https://dev.funkwhale.audio/funkwhale/funkwhale/raw/master/deploy/env.prod.sample"
...and then set its permissions:
chmod 600 /srv/funkwhale/config/.env
Next, we need to generate a secret key for Django. Django is a web framework that helps create the actual website users see when they visit your Funkwhale instance in the browser.
We can generate a key with the "openssl rand" command:
openssl rand -base64 45
This will about a random string using base64 encoding. Copy this string, as you'll need it for the next steps.
Open your environment file for editing:
nano /srv/funkwhale/config/.env
You'll see a lot of commented lines explaining what you can do in this file. Right now, we only want to focus on four things; FUNKWHALE_HOSTNAME, DATABASE_URL, CACHE_URL, and DJANGO_SECRET_KEY
NOTE: Once you first launch your Funkwhale instance, this domain name cannot be changed. Make sure you have your domain name under your control, and pointing at your server before you proceed beyond this point.
Find the line that says:
FUNKWHALE_HOSTNAME=yourdomain.funkwhale
...and replace "yourdomain.funkwhale" with the domain name for your instance.
Next, set the DATABASE_URL variable. Thankfully, a working example is provided for us, so we only need to uncomment it.
Find this section:
# Database configuration
# Examples:
# DATABASE_URL=postgresql://<user>:<password>@<host>:<port>/<database>
# DATABASE_URL=postgresql://funkwhale:passw0rd@localhost:5432/funkwhale_database
# Use the next one if you followed Debian installation guide
# DATABASE_URL=postgresql://funkwhale@:5432/funkwhale
...and change it so that it looks like this:
# Database configuration
# Examples:
# DATABASE_URL=postgresql://<user>:<password>@<host>:<port>/<database>
# DATABASE_URL=postgresql://funkwhale:passw0rd@localhost:5432/funkwhale_database
# Use the next one if you followed Debian installation guide
DATABASE_URL=postgresql://funkwhale@:5432/funkwhale
Make sure to uncomment DATABASE_URL by deleting BOTH the "#" AND the space next to it. Otherwise you'll get an error down the road when Funkwhale tries to read the environment file.
Now we set the CACHE_URL variable. As with DATABASE_URL, an example is kindly provided, so we only need to uncomment it.
Find this:
# Cache configuration
# Examples:
# CACHE_URL=redis://<host>:<port>/<database>
# CACHE_URL=redis://localhost:6379/0c
# With a password:
# CACHE_URL=redis://:password@localhost:6379/0
# (the extra semicolon is important)
# Use the next one if you followed Debian installation guide
#
# CACHE_URL=redis://127.0.0.1:6379/0
...and change it to this:
# Cache configuration
# Examples:
# CACHE_URL=redis://<host>:<port>/<database>
# CACHE_URL=redis://localhost:6379/0c
# With a password:
# CACHE_URL=redis://:password@localhost:6379/0
# (the extra semicolon is important)
# Use the next one if you followed Debian installation guide
#
CACHE_URL=redis://127.0.0.1:6379/0
Making sure to delete both the "#" and the space as before.
Lastly, find the following line:
# Generate one using `openssl rand -base64 45`, for example
DJANGO_SECRET_KEY=
...and paste the secret Django key we made before directly after the "=".
Now we can exit the editor with Ctrl+X, and save our changes by pressing Y and then Enter.
¶ MIGRATING THE DATABASE
Now we can import the database structure, which will create the necessary rows and tables for Funkwhale to work:
python api/manage.py migrate
NOTE: You may see a warning message that looks like the following:
Your models have changes that are not yet reflected in a migration, and so won't be applied.
This isn't an error, just a warning, and can be ignored. The migration will proceed normally regardless.
¶ CREATING AN ADMIN USER
You can create your admin user account with:
python api/manage.py createsuperuser
You will be prompted to set the user's name and password. Note these down, as you'll need them to log in once the installation is done.
If you ever need to reset your password, you can do so with the following, replacing <user> with the appropriate name:
python api/manage.py changepassword <user>
¶ COLLECT STATIC FILES
The API server will need certain assets so they can be served by the webserver. We need to collect them and place them in the correct directory, which we can do with the following command:
python api/manage.py collectstatic
¶ SYSTEMD SETUP
"systemd" is a service manager in Debian/Ubuntu (and other) Operating Systems. Not every OS has it, but we're assuming Debian/Ubuntu for this guide, so here's how to set it up for Funkwhale.
NOTE: this section should be run as root. If you're still in the python virtualenv, you can exit it with "deactivate". If you're still logged in as the funkwhale user (or any other non-root user), logout with "exit" until you're in a root shell.
First, we'll download four sample systemd service files before activating them on our server:
- funkwhale-server.service (which launches the Funkwhale web server)
- funkwhale-worker.service (which launches the Funkwhale task worker)
- funkwhale-beat.service (which launches the Funkwhale task beat for recurring tasks)
- funkwhale.target (which lets us easily stop and start all the above services at once)
We can download them with the following commands:
curl -L -o "/etc/systemd/system/funkwhale.target" "https://dev.funkwhale.audio/funkwhale/funkwhale/raw/1.0.1/deploy/funkwhale.target"
curl -L -o "/etc/systemd/system/funkwhale-server.service" "https://dev.funkwhale.audio/funkwhale/funkwhale/raw/1.0.1/deploy/funkwhale-server.service"
curl -L -o "/etc/systemd/system/funkwhale-worker.service" "https://dev.funkwhale.audio/funkwhale/funkwhale/raw/1.0.1/deploy/funkwhale-worker.service"
curl -L -o "/etc/systemd/system/funkwhale-beat.service" "https://dev.funkwhale.audio/funkwhale/funkwhale/raw/1.0.1/deploy/funkwhale-beat.service"
After they've all been downloaded, reload systemd:
systemctl daemon-reload
Then start the Funkwhale services:
systemctl start funkwhale.target
Set them to start automatically on boot:
systemctl enable funkwhale-server
systemctl enable funkwhale-worker
systemctl enable funkwhale-beat
Check the status of the services with the following command:
systemctl status funkwhale-\*
If everything went well, all three services should show as "active". If they do, systemd setup is complete.
If any of them show as "failed", run through these troubleshooting steps.
If funkwhale-worker.service failed, you may need to edit the service file. Open it with the following command (as root):
nano /etc/systemd/system/funkwhale-worker.service
Look for the line that looks like this:
ExecStart=/srv/funkwhale/virtualenv/bin/celery -A funkwhale_api.taskapp worker -l INFO --concurrency=${CELERYD_CONCURRENCY-0}
And edit it to look like this:
ExecStart=/srv/funkwhale/virtualenv/bin/celery -A funkwhale_api.taskapp worker -l INFO
...by deleting the "--concurrency=${CELERYD_CONCURRENCY-0}" from the end. Save and exit with Ctrl+X, then Y, and Enter.
Restart the worker service with:
systemctl restart funkwhale-worker
...and check the service status as above to see if it's working.
If funkwhale-server.service failed, check the logs with the following command:
journalctl -feu funkwhale-server
If you see error messages like this:
ModuleNotFoundError: No module named...
...then there may be a missing python dependency. Make note of the module name so we can attempt to install it.
Log into your funkwhale user, confirm you're in the correct directory, then activate the virtualenv as we did before:
sudo -u funkwhale -H bash
cd /srv/funkwhale
source /srv/funkwhale/virtualenv/bin/activate
Then run the following command to install the missing dependency, replacing <module> with the module name we noted from the journalctl log:
pip install <module>
Then return to your root shell using "deactivate" and "exit" as before. Restart the funkwhale-server service with:
systemctl restart funkwhale-server
...and check the service status as before to see if it's working.
If the above steps don't help, or any other errors occur, contact the Funkwhale support channels here, or contact us here for assistance.
¶ SET UP REVERSE PROXY
Now that the Funkwhale services are up and running, we need to set up a reverse proxy (nginx) so people can interact with it over the web. Fortunately, we've already installed nginx, so we can go straight to configuring it. To prevent errors, we'll automatically generate an nginx configuration file using the environment file.
First we'll download some template files:
export FUNKWHALE_VERSION="1.1"
curl -L -o /etc/nginx/funkwhale_proxy.conf "https://dev.funkwhale.audio/funkwhale/funkwhale/raw/1.1/deploy/funkwhale_proxy.conf"
curl -L -o /etc/nginx/sites-available/funkwhale.template "https://dev.funkwhale.audio/funkwhale/funkwhale/raw/1.1/deploy/nginx.template"
Then we'll use these templates and our environment file to generate nginx configuration:
set -a && source /srv/funkwhale/config/.env && set +a
(NOTE: copy the following lines as one block and enter them together)
envsubst "`env | awk -F = '{printf \" $%s\", $$1}'`" \
< /etc/nginx/sites-available/funkwhale.template \
> /etc/nginx/sites-available/funkwhale.conf "
This should fill in the nginx config with all the necessary information, but it's wise to check and make sure there aren't any placeholder variables like "${FUNKWHALE_HOSTNAME}" as these will cause errors:
grep '${' /etc/nginx/sites-available/funkwhale.conf
If this command doesn't output anything, then the configuration file is good to go.
If it does output something, you'll need to edit the file and replace the variable with an appropriate value:
nano /etc/nginx/sites-available/funkwhale.conf
If you're not sure what to do here, you should contact Funkwhale support channels here, or contact us here for help.
If you don't have any problems with the nginx config, then activate it:
ln -s /etc/nginx/sites-available/funkwhale.conf /etc/nginx/sites-enabled/
¶ SETTING UP HTTPS CERTIFICATES
We'll also need to set up a certificate so people can access the Funkwhale instance over HTTPS, for better security. We can do this with "certbot".
NOTE: It is the policy of 10friends guides to always be supplemental to, and never a replacement for official guides. When our guides contradict the official sources, the former should be considered correct. However, in the case of certbot, there are multiple methods of both installing the necessary software and acquiring the certificate. In our tests, the instructions and defaults provided in the official Funkwhale documentation often resulted in errors, and significant tweaking was required to complete this step.
The official documentation on configuring a certificate can be found here, and you should try at least once to run through them as written. If, however, this results in errors as it did with us, you can return here and follow our alternative instructions to see if that works better for you.
The Electronic Frontier Foundation recommends using "snapd", a special package manager, to install certbot. "snapd" might already be bundled with your server OS, but if it isn't, you can easily install it with:
sudo apt install snapd
Make sure your snapd version is up to date:
sudo snap install core
sudo snap refresh core
It's possible that another version of certbot exists on your server. If it does, it might conflict with the snapd version, so we should uninstall it if it exists:
sudo apt-get remove certbot
Now install certbot via snapd:
sudo snap install --classic certbot
The nginx configuration file we generated earlier should already be set up to look for certificates in the "/etc/letsencrypt/live/..." directory (in the "ssl_certificate" and "ssl_certificate_key" entries), so asking certbot for a standalone certificate will automatically place them where they need to be.
First we need to stop our reverse proxy:
sudo systemctl stop nginx
Then input the following command to request a certificate. Replace <example.com> with the domain name for your Funkwhale instance:
sudo certbot certonly --standalone -d <example.com>
You should get a message informing you of your success, and telling you where the certificate is located.
NOTE: your certificate will last 90 days, and will need to be renewed before it expires. You can read more about how to renew certificates here. Don't forget to stop nginx before renewing, and to restart it once you're done.
Test the nginx config to make sure it works:
nginx -t
If it works, you'll see a message that the syntax is okay, and that the test is successful. Now you can reload nginx:
sudo systemctl reload nginx
¶ POST-INSTALLATION
At this point, your Funkwhale instance should be up and running, and visible to the internet. Open a web browser and enter your domain name to check if your instance is online or not. If it isn't, go back through the configuration files and make sure you haven't mistyped anything or forgotten any steps. If you can't solve the issue yourself, reach out to the official Funkwhale support channels or contact us here.
If your instance is visible, then congratulations! You're got a working Funkwhale instance. Use the admin username and password you created earlier to log in and get things set up. Check out the User Documentation to see how you can use Funkwhale, or read the Moderator Documentation to see how you can create accounts for your friends and manage a multi-user instance.
¶ JOIN THE INSTANCE LIST (OPTIONAL)
Once you've successfully created a space for yourself and your friends, you might be interested in finding other groups to connect with. As you begin to follow more users on other instances, you'll be able to see a wider variety of content from across the Fediverse as a whole. And you'll be helping to create a more robust network for everyone else.
Check our instance list to find other groups of friends who've joined up with the 10friends Project, and consider joining the list yourself so other groups can find you.
In the future, we plan to create an automated list that instance moderators can join when they set up their server. In the meantime, this is a manually updated placeholder list. To add your instance, please contact us with your instance's information, including:
- The instance name
- Which service you're running (ie, Pleroma, PeerTube, etc.)
- What version of the service you have installed (ie, 3.0.1)
- The instance URL
- Whether or not your instance is open to new user registration
- A brief description of your instance (optional, but useful for organizing around hobbies, common interests, etc)
¶ UPDATING FUNKWHALE
As new version of Funkwhale come out, you'll want to update your instance to patch out bugs and enjoy new features. You should periodically check the Release page of the Funkwhale repository to see if a new version has been released.
If there is a new version, go through the following steps (or just follow the Update instructions in the official docs):
¶ UPDATING THE FRONTEND
Front-end updates are relatively easy. All you need to do is download the new files and unpack them into the correct location. The examples below assume version "1.1", but you should change the version number to whatever you're updating to:
export FUNKWHALE_VERSION="1.1"
cd /srv/funkwhale
sudo -u funkwhale curl -L -o front.zip "https://dev.funkwhale.audio/funkwhale/funkwhale/builds/artifacts/$FUNKWHALE_VERSION/download?job=build_front"
sudo -u funkwhale unzip -o front.zip
sudo -u funkwhale rm front.zip
¶ UPDATING THE API
As above, these examples assume version "1.1". Change the version number to the whatever you're updating to:
export FUNKWHALE_VERSION="1.1"
Move to the Funkwhale directory:
cd /srv/funkwhale
Download the API files:
sudo -u funkwhale curl -L -o "api-$FUNKWHALE_VERSION.zip" "https://dev.funkwhale.audio/funkwhale/funkwhale/-/jobs/artifacts/$FUNKWHALE_VERSION/download?job=build_api"
sudo -u funkwhale unzip "api-$FUNKWHALE_VERSION.zip" -d extracted
sudo -u funkwhale rm -rf api/ && sudo -u funkwhale mv extracted/api .
sudo -u funkwhale rm -rf extracted
Update your OS dependencies:
sudo api/install_os_dependencies.sh install
sudo -u funkwhale -H -E /srv/funkwhale/virtualenv/bin/pip install -r api/requirements.txt
Collect static files:
sudo -u funkwhale -H -E /srv/funkwhale/virtualenv/bin/python api/manage.py collectstatic --no-input
Stop the Funkwhale services:
sudo systemctl stop funkwhale.target
Apply database migrations:
sudo -u funkwhale -H -E /srv/funkwhale/virtualenv/bin/python api/manage.py migrate
NOTE: If your get an error when trying to migrate the database, you may need to manually add some database extensions with the following commands:
sudo -u postgres psql funkwhale -c 'CREATE EXTENSION IF NOT EXISTS "citext";'
sudo -u postgres psql funkwhale -c 'CREATE EXTENSION IF NOT EXISTS "unaccent";'
Then attempt the apply database migrations again.
Finally, restart the Funkwhale services:
sudo systemctl start funkwhale.target
¶ FURTHER READING
As a Funkwhale administrator, it's a good idea to read up on how to manage and maintain your server. The official Funkwhale documentation has guides and instructions on everything you might want to do, and the official support channels can answer any specific questions you have. We're also happy to help where we can (and you should feel free to contact us here), but official Funkwhale support channels are probably the best place to start.