Deploying Mopidy

Introduction

Mopidy is an extensible music server written in Python that plays music from local disk, Spotify, SoundCloud, Google Play Music, and more. It can be controlled from any device through web interfaces, MPD clients, or its HTTP/JSON-RPC API, making it a versatile foundation for music streaming setups.

Built with a modular extension architecture, Mopidy supports dozens of backends for music sources and frontends for control interfaces. Whether you want a personal streaming server, a multi-room audio solution, or an API-driven music service, Mopidy provides the flexibility to build it.

Key highlights of Mopidy:

Multi-Source Playback: Local files, Spotify, SoundCloud, YouTube, and more
MPD Protocol: Compatible with hundreds of MPD clients
Web Interfaces: Multiple web UI options available
HTTP API: JSON-RPC API for custom integrations
Extension System: Modular architecture with 100+ extensions
Playlist Support: M3U, local, and service-specific playlists
Queue Management: Full playback queue control
Scrobbling: Last.fm and ListenBrainz integration
Podcast Support: Subscribe to and play podcasts
Radio Streams: Internet radio support
Multi-Room: Snapcast integration for synchronized audio
Python-Based: Easy to extend and customize

This guide covers deploying Mopidy on Klutch.sh, configuring music sources, and setting up web control interfaces.

Why Deploy Mopidy on Klutch.sh

Deploying Mopidy on Klutch.sh provides key advantages:

Simplified Deployment: Klutch.sh automatically builds and deploys Mopidy. Push to GitHub, and your music server deploys automatically.

Persistent Storage: Attach volumes for local music files, playlists, and configuration.

HTTPS by Default: Klutch.sh provides automatic SSL certificates for secure web access.

GitHub Integration: Connect your repository for automatic deployments.

Scalable Resources: Allocate CPU and memory based on transcoding needs.

Environment Variable Management: Securely store API credentials for Spotify, SoundCloud, etc.

Custom Domains: Use your own domain for a personalized music server.

Always-On Availability: Access your music from anywhere, anytime.

Prerequisites

Before deploying Mopidy on Klutch.sh, ensure you have:

A Klutch.sh account
A GitHub account with a repository for your configuration
Basic familiarity with Docker and containerization
(Optional) Spotify Premium account for Spotify integration
(Optional) Local music files to stream
(Optional) A custom domain

Understanding Mopidy Architecture

Mopidy uses a modular architecture:

Core: Central component managing playback, playlist, and library.

Backends: Provide music sources (local files, Spotify, SoundCloud).

Frontends: Handle control interfaces (HTTP, MPD, web UIs).

Audio Output: Configurable output (local, HTTP stream, Snapcast).

Extensions: Add functionality through pip-installable packages.

Preparing Your Repository

Repository Structure

mopidy-deploy/
├── Dockerfile
├── mopidy.conf
├── README.md
└── .dockerignore

Creating the Dockerfile

Create a Dockerfile:

FROM wernight/mopidy:latest

# Install additional extensions
RUN pip3 install \
    Mopidy-Spotify \
    Mopidy-SoundCloud \
    Mopidy-YouTube \
    Mopidy-Iris \
    Mopidy-Local

# Copy configuration
COPY mopidy.conf /etc/mopidy/mopidy.conf

# Set environment variables
ENV SPOTIFY_USERNAME=${SPOTIFY_USERNAME}
ENV SPOTIFY_PASSWORD=${SPOTIFY_PASSWORD}
ENV SPOTIFY_CLIENT_ID=${SPOTIFY_CLIENT_ID}
ENV SPOTIFY_CLIENT_SECRET=${SPOTIFY_CLIENT_SECRET}
ENV SOUNDCLOUD_AUTH_TOKEN=${SOUNDCLOUD_AUTH_TOKEN}

# Create directories
RUN mkdir -p /var/lib/mopidy/local /var/lib/mopidy/playlists

# Expose ports
# 6600 - MPD
# 6680 - HTTP
EXPOSE 6600 6680

# Health check
HEALTHCHECK --interval=30s --timeout=10s --start-period=30s --retries=3 \
  CMD curl -f http://localhost:6680/ || exit 1

# Start Mopidy
CMD ["mopidy"]

Creating mopidy.conf

Create a mopidy.conf configuration file:

[core]
cache_dir = /var/lib/mopidy/cache
config_dir = /etc/mopidy
data_dir = /var/lib/mopidy

[logging]
verbosity = 0

[audio]
output = autoaudiosink

[http]
enabled = true
hostname = 0.0.0.0
port = 6680

[mpd]
enabled = true
hostname = 0.0.0.0
port = 6600

[local]
enabled = true
media_dir = /var/lib/mopidy/media

[iris]
country = US
locale = en_US

[spotify]
enabled = true
username = ${SPOTIFY_USERNAME}
password = ${SPOTIFY_PASSWORD}
client_id = ${SPOTIFY_CLIENT_ID}
client_secret = ${SPOTIFY_CLIENT_SECRET}

[soundcloud]
enabled = true
auth_token = ${SOUNDCLOUD_AUTH_TOKEN}

Environment Variables Reference

Variable	Required	Default	Description
`SPOTIFY_USERNAME`	No	-	Spotify Premium username
`SPOTIFY_PASSWORD`	No	-	Spotify password
`SPOTIFY_CLIENT_ID`	No	-	Spotify API client ID
`SPOTIFY_CLIENT_SECRET`	No	-	Spotify API client secret
`SOUNDCLOUD_AUTH_TOKEN`	No	-	SoundCloud auth token

Deploying Mopidy on Klutch.sh

Get Spotify API Credentials (Optional)

If using Spotify:

Visit Spotify Developer Dashboard
Create a new application
Note Client ID and Client Secret

Push Your Repository to GitHub

git init
git add Dockerfile mopidy.conf .dockerignore README.md
git commit -m "Initial Mopidy deployment"
git remote add origin https://github.com/yourusername/mopidy-deploy.git
git push -u origin main

Create a New Project on Klutch.sh

Navigate to the Klutch.sh dashboard and create a project named “mopidy” or “music-server”.

Create a New App

Create a new app and connect your GitHub repository.

Configure HTTP Traffic

In deployment settings:

Select HTTP as the traffic type
Set the internal port to 6680 for web interface

Set Environment Variables

Configure your environment:

Variable	Value
`SPOTIFY_USERNAME`	Your Spotify username
`SPOTIFY_PASSWORD`	Your Spotify password
`SPOTIFY_CLIENT_ID`	Your Spotify client ID
`SPOTIFY_CLIENT_SECRET`	Your Spotify client secret

Attach Persistent Volumes

Add volumes for persistent data:

Mount Path	Recommended Size	Purpose
`/var/lib/mopidy/media`	100+ GB	Local music files
`/var/lib/mopidy/playlists`	1 GB	Playlist files
`/var/lib/mopidy/cache`	5 GB	Cache data

Deploy Your Application

Click Deploy to build and launch Mopidy.

Access Web Interface

Navigate to https://your-app-name.klutch.sh to access the Iris web interface.

Web Interfaces

Iris (Recommended)

Iris is the most popular Mopidy web interface:

Modern, responsive design
Full queue and playlist management
Search across all sources
Artist and album browsing
Now playing visualization

Access at: https://your-server/iris/

Other Interfaces

Alternative web UIs available as extensions:

Moped: Simple, minimal interface
Party: Jukebox mode with voting
Musicbox-Webclient: Classic interface

Configuring Music Sources

Local Files

Add local music:

Upload files to /var/lib/mopidy/media
Run local scan: mopidy local scan
Browse in interface

Supported formats: MP3, FLAC, OGG, WAV, M4A

Spotify Integration

Requires Spotify Premium:

Configure credentials in environment
Browse Spotify library
Play tracks and playlists

SoundCloud

Add SoundCloud support:

Get auth token from Mopidy-SoundCloud docs
Configure in environment
Access SoundCloud content

YouTube

Play YouTube audio:

Install Mopidy-YouTube extension
Search and play YouTube videos
Audio extracted automatically

MPD Clients

Connecting MPD Clients

Mopidy supports the MPD protocol:

Server: your-server.klutch.sh
Port: 6600
Password: (none by default)

Popular MPD Clients

ncmpcpp: Terminal-based player
Cantata: Qt desktop client
MPDroid: Android app
MPoD: iOS app

Playlists

Creating Playlists

Open Iris interface
Navigate to Playlists
Click Create Playlist
Add tracks from any source

M3U Playlists

Import M3U playlists:

Upload .m3u files to playlists directory
Restart Mopidy
Access from playlist browser

Troubleshooting

No Sound Output

Check audio output configuration
Verify audio device permissions
Review audio backend settings

Spotify Not Working

Verify Spotify Premium subscription
Check API credentials
Ensure token is valid

Local Files Not Appearing

Run local scan: mopidy local scan
Check file permissions
Verify media directory path

Web Interface Not Loading

Check HTTP frontend is enabled
Verify port configuration
Review browser console for errors

Additional Resources

Conclusion

Mopidy on Klutch.sh provides a flexible, extensible music server that aggregates content from multiple sources into a unified interface. Whether streaming from Spotify, SoundCloud, YouTube, or your local collection, Mopidy delivers control through web interfaces, MPD clients, or API integrations. The extension architecture means you can customize your setup to match exactly how you listen to music, while Klutch.sh handles the deployment complexity.