Nov 9, 2024 3 min read

Funkwhale: The Full Guide to Self-Hosting Anywhere

Funkwhale: The Full Guide to Self-Hosting Anywhere
Table of Contents

Funkwhale is a self-hosted and federated music server that allows users to stream their personal audio collections while maintaining full control over their data. It’s an excellent choice for developers and system administrators looking for a customizable, privacy-respecting alternative to commercial streaming services. In this guide, we’ll walk through the process of installing, configuring, and managing Funkwhale, from setting it up with Docker to leveraging its unique features.

Installing Funkwhale

πŸ“¦ Docker/Docker Compose Setup

We’ll use Docker Compose to deploy Funkwhale for a streamlined and repeatable installation process. Create a docker-compose.yml file with the following content:


version: '3.7'

services:

funkwhale:

image: funkwhale/all-in-one:latest

container_name: funkwhale

ports:

- "5000:5000"

environment:

- FUNKWHALE_HOSTNAME=yourdomain.com

- DJANGO_SECRET_KEY=your_secret_key

- FUNKWHALE_API_IP=0.0.0.0

volumes:

- ./data:/data

- ./media:/media

- ./static:/static

restart: unless-stopped

Save the file and deploy the services:


docker-compose up -d

This command will pull the Funkwhale image, create containers, and start the app in the background.

πŸš€ Manual Installation

If you prefer to install Funkwhale manually on a Linux server, follow these steps:

  1. Install dependencies:

sudo apt update && sudo apt install -y python3 python3-pip postgresql nginx git

  1. Clone the Funkwhale repository and set up the environment:

git clone https://dev.funkwhale.audio/funkwhale/funkwhale.git

cd funkwhale

python3 -m venv venv

source venv/bin/activate

pip install -r requirements.txt

  1. Configure and run the application:

cp .env.sample .env

nano .env # Update settings like SECRET_KEY and DATABASE_URL

python manage.py migrate

python manage.py runserver 0.0.0.0:5000

Configuring Nginx as a Reverse Proxy

🌐 Nginx Configuration

To serve Funkwhale through Nginx, create a new server block:


sudo nano /etc/nginx/sites-available/funkwhale

Add the following configuration:


server {

listen 80;

server_name yourdomain.com;

location / {

proxy_pass http://127.0.0.1:5000;

proxy_set_header Host $host;

proxy_set_header X-Real-IP $remote_addr;

proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

}

}

Enable the configuration and reload Nginx:


sudo ln -s /etc/nginx/sites-available/funkwhale /etc/nginx/sites-enabled/

sudo nginx -t && sudo systemctl reload nginx

πŸ”’ SSL/TLS Setup

Secure your setup with a Let's Encrypt SSL certificate:


sudo apt install certbot python3-certbot-nginx

sudo certbot --nginx -d yourdomain.com

Certbot will automatically configure SSL and handle renewals.

πŸ› οΈ Testing and Reloading Nginx

Validate your Nginx configuration and reload it:


sudo nginx -t

sudo systemctl reload nginx

Access your Funkwhale instance securely at https://yourdomain.com.

Logging and Debugging Funkwhale

πŸ—ƒοΈ Enabling Debug Logs

To enable debug-level logging, update your .env file:


DEBUG=1

DJANGO_LOG_LEVEL=DEBUG

Restart your Funkwhale app to apply the changes:


docker-compose restart

πŸ“„ Viewing Logs

If using Docker, access logs with:


docker logs funkwhale -f

For manual installations, check the application logs directly:


tail -f /var/log/funkwhale.log

πŸ› οΈ Troubleshooting Common Issues

For issues like misconfigured environment variables, check the logs for errors such as missing database connections or API endpoint failures.

πŸ“€ Exporting Logs

To forward logs to an external system, configure a logging driver in Docker or use tools like rsyslog for manual setups.

Backup and Restore

πŸ—‚οΈ File-Based Backups

Create a tarball of your critical directories:


tar -czvf funkwhale-backup.tar.gz ./data ./media ./static

πŸ”„ Database Backups

For PostgreSQL users, back up the database with:


pg_dump -U funkwhale_user funkwhale_db > funkwhale_db_backup.sql

Restore the database when needed:


psql -U funkwhale_user funkwhale_db < funkwhale_db_backup.sql

πŸ“… Automated Backup Scripts

Set up a cron job to automate backups:


crontab -e

Add the following line to create daily backups:


0 2 * * * tar -czvf /backups/funkwhale-$(date +\%F).tar.gz /path/to/funkwhale

Updating and Upgrading Funkwhale

⬆️ Updating Docker Images

Pull the latest image and redeploy:


docker-compose pull

docker-compose up -d

πŸ› οΈ Manual Updates

For manual installations, pull the latest changes from the repository:


cd funkwhale

git pull

pip install -r requirements.txt

python manage.py migrate

πŸ” Checking for Updates

Monitor Funkwhale’s GitLab repository or run:


docker-compose images

Check if your current image matches the latest version.

Leveraging Funkwhale’s Unique Features

πŸ”§ Enabling APIs

To enable Funkwhale’s public APIs, update the .env file:


FUNKWHALE_API_ENABLED=true

Access API endpoints with tools like curl:


curl -X GET "http://yourdomain.com/api/v1/tracks/" -H "Authorization: Bearer YOUR_TOKEN"

🌟 Advanced Configurations

Funkwhale supports federation with other instances. Enable federation by setting:


FUNKWHALE_ACTIVITYPUB_ENABLED=true

Restart Funkwhale to apply changes.

Wrapping Up

By following this guide, you’ve installed, configured, and started managing your self-hosted Funkwhale instance. This powerful platform offers a rich feature set for streaming and sharing music while giving you full control over your data. Explore its advanced configurations to unlock its full potential and enjoy the freedom of self-hosting.

Great! You’ve successfully signed up.
Welcome back! You've successfully signed in.
You've successfully subscribed to Selfhosted Ninja.
Your link has expired.
Success! Check your email for magic link to sign-in.
Success! Your billing info has been updated.
Your billing was not updated.