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:
- Install dependencies:
sudo apt update && sudo apt install -y python3 python3-pip postgresql nginx git
- 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
- 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.
