# Funkwhale Music Platform

> Social music platform for sharing and discovering music.

- Category: Media & Entertainment
- Difficulty: advanced
- Components: funkwhale-api, funkwhale-front, funkwhale-celery, postgresql, redis
- Tags: music, funkwhale, social, federated, activitypub
- Source: https://docker.recipes/media/funkwhale-music

## Overview

Funkwhale is a self-hosted, federated music server that enables users to build their own Spotify-like platform with social features and ActivityPub federation. Born from the need for a decentralized alternative to proprietary music streaming services, Funkwhale allows individuals and communities to share, discover, and stream music while maintaining full control over their data and privacy. The platform supports multiple audio formats, provides Subsonic API compatibility for mobile apps, and integrates with the broader fediverse through ActivityPub protocol.

This deployment stack combines Funkwhale's Django-based API backend with a Vue.js frontend, while leveraging PostgreSQL for robust metadata storage and complex music library relationships, and Redis for high-performance caching and Celery task queue management. The architecture separates concerns effectively: the API handles music metadata, user management, and federation logic, while Celery workers process audio transcoding, library imports, and federation tasks in the background. Redis serves dual purposes as both a cache layer for frequently accessed music metadata and as a message broker for asynchronous task processing.

This configuration is ideal for music enthusiasts, podcast creators, radio stations, and organizations wanting to create their own streaming platform without vendor lock-in. The federated nature allows multiple Funkwhale instances to share content and users, creating a decentralized network similar to Mastodon but for audio content. Musicians can distribute their work directly, while communities can build curated collections with fine-grained privacy controls and user permissions.

## Features

- ActivityPub federation enabling content sharing across multiple Funkwhale instances and fediverse integration
- Subsonic API compatibility allowing use of existing mobile music apps like DSub and Ultrasonic
- Multi-format audio support with automatic transcoding via Celery workers for bandwidth optimization
- Advanced music library management with artist pages, album collections, and tag-based organization
- Social features including follow/unfollow, playlist sharing, and content discovery across federated instances
- Granular privacy controls with public, followers-only, and private content visibility levels
- Bulk music import from filesystem with automatic metadata extraction and duplicate detection
- Built-in audio player with queue management, repeat modes, and scrobbling support

## Use cases

- Independent musicians distributing music directly to fans with federated reach across multiple instances
- Community radio stations creating curated playlists with listener interaction and content discovery
- Music collectives and labels building private streaming platforms with controlled access and member features
- Podcast networks hosting audio content with RSS feed generation and cross-instance syndication
- Educational institutions providing music streaming for students with copyright-compliant content management
- Personal music servers replacing Spotify with family sharing and mobile app compatibility
- Music archivists preserving rare recordings with metadata preservation and federated backup systems

## Prerequisites

- Minimum 2GB RAM (1GB+ for PostgreSQL, 512MB+ for Redis, plus Funkwhale components and Celery workers)
- Port 80 available for HTTP access to the Funkwhale web interface
- Music library accessible at filesystem path with read permissions for Docker containers
- Domain name or hostname configured for FUNKWHALE_HOST environment variable
- Understanding of music metadata management and audio format compatibility
- Basic knowledge of Django admin interface for user and content moderation

## docker-compose.yml

```yaml
services:
  api:
    image: funkwhale/api:latest
    container_name: funkwhale-api
    environment:
      - FUNKWHALE_HOSTNAME=${FUNKWHALE_HOST}
      - FUNKWHALE_PROTOCOL=http
      - DATABASE_URL=postgresql://funkwhale:${DB_PASSWORD}@db:5432/funkwhale
      - CACHE_URL=redis://redis:6379/0
      - DJANGO_SECRET_KEY=${SECRET_KEY}
      - DJANGO_ALLOWED_HOSTS=*
    volumes:
      - funkwhale-data:/srv/funkwhale/data
      - /path/to/music:/music:ro
    depends_on:
      - db
      - redis
    networks:
      - funkwhale-network
    restart: unless-stopped

  front:
    image: funkwhale/front:latest
    container_name: funkwhale-front
    environment:
      - FUNKWHALE_API_HOST=api
      - FUNKWHALE_API_PORT=5000
    ports:
      - "80:80"
    depends_on:
      - api
    networks:
      - funkwhale-network
    restart: unless-stopped

  celery-worker:
    image: funkwhale/api:latest
    container_name: funkwhale-celery-worker
    command: celery -A funkwhale_api.taskapp worker -l INFO
    environment:
      - FUNKWHALE_HOSTNAME=${FUNKWHALE_HOST}
      - DATABASE_URL=postgresql://funkwhale:${DB_PASSWORD}@db:5432/funkwhale
      - CACHE_URL=redis://redis:6379/0
      - DJANGO_SECRET_KEY=${SECRET_KEY}
    volumes:
      - funkwhale-data:/srv/funkwhale/data
      - /path/to/music:/music:ro
    depends_on:
      - api
    networks:
      - funkwhale-network
    restart: unless-stopped

  celery-beat:
    image: funkwhale/api:latest
    container_name: funkwhale-celery-beat
    command: celery -A funkwhale_api.taskapp beat -l INFO
    environment:
      - FUNKWHALE_HOSTNAME=${FUNKWHALE_HOST}
      - DATABASE_URL=postgresql://funkwhale:${DB_PASSWORD}@db:5432/funkwhale
      - CACHE_URL=redis://redis:6379/0
      - DJANGO_SECRET_KEY=${SECRET_KEY}
    depends_on:
      - api
    networks:
      - funkwhale-network
    restart: unless-stopped

  db:
    image: postgres:15-alpine
    container_name: funkwhale-db
    environment:
      - POSTGRES_USER=funkwhale
      - POSTGRES_PASSWORD=${DB_PASSWORD}
      - POSTGRES_DB=funkwhale
    volumes:
      - postgres-data:/var/lib/postgresql/data
    networks:
      - funkwhale-network
    restart: unless-stopped

  redis:
    image: redis:7-alpine
    container_name: funkwhale-redis
    volumes:
      - redis-data:/data
    networks:
      - funkwhale-network
    restart: unless-stopped

volumes:
  funkwhale-data:
  postgres-data:
  redis-data:

networks:
  funkwhale-network:
    driver: bridge
```

## .env

```bash
# Funkwhale
FUNKWHALE_HOST=funkwhale.localhost
DB_PASSWORD=secure_funkwhale_password

# Generate with: openssl rand -hex 32
SECRET_KEY=your_secret_key
```

## Usage notes

- Web UI at http://localhost
- Create admin: manage.py createsuperuser
- Federation with ActivityPub
- Import from filesystem
- Subsonic API compatible

## Troubleshooting

- Import tasks failing or stuck: Check Celery worker logs and ensure music directory has proper read permissions and supported audio formats
- Federation not working with other instances: Verify FUNKWHALE_HOSTNAME matches your actual domain and is accessible externally with proper DNS configuration
- High memory usage during imports: Limit concurrent Celery workers and increase Redis memory allocation for large music libraries
- Subsonic API authentication failing: Ensure user accounts are created through Django admin and have proper API permissions enabled
- Frontend showing API connection errors: Verify FUNKWHALE_API_HOST environment variable matches the actual API service name and port 5000 connectivity
- Database migration errors on startup: Check PostgreSQL logs for disk space and ensure DATABASE_URL format matches PostgreSQL connection requirements

