Deploying musikcube

Introduction

musikcube is a fully functional terminal-based music player, library manager, and streaming audio server written in C++. While it shines as a fast, keyboard-driven local player, its built-in streaming server component makes it excellent for cloud deployment, allowing you to stream your music library to clients anywhere.

The musikcube server can stream your library to the musikcube client applications available for Windows, macOS, Linux, and Android. This creates a personal streaming service similar to commercial offerings, but with complete control over your music and infrastructure.

Key highlights of musikcube:

Terminal-Based Interface: Fast, keyboard-driven UI with curses interface
Streaming Server: Built-in server for remote streaming to clients
Cross-Platform Clients: Native clients for Windows, macOS, Linux, and Android
Gapless Playback: Seamless transitions between tracks
Format Support: Plays MP3, FLAC, OGG, AAC, WMA, and more via FFmpeg
Library Management: Automatic indexing and metadata management
Playlist Support: Create and manage playlists with smart filtering
ReplayGain: Volume normalization support
Low Resource Usage: Lightweight C++ implementation
Transcoding: Server-side transcoding for bandwidth optimization
API Access: REST-like API for third-party integration
Open Source: Licensed under BSD

This guide walks through deploying musikcube server on Klutch.sh using Docker, configuring streaming, and connecting clients.

Why Deploy musikcube on Klutch.sh

Deploying musikcube on Klutch.sh provides several advantages:

Personal Streaming Service: Create your own music streaming service accessible from anywhere.

Simplified Deployment: Klutch.sh automatically detects your Dockerfile and builds musikcube without complex configuration.

Persistent Storage: Attach persistent volumes for your music library, database, and settings.

HTTPS by Default: Klutch.sh provides automatic SSL certificates for secure streaming connections.

GitHub Integration: Connect your configuration repository for automatic redeployments.

Low Resource Requirements: musikcube’s efficient C++ implementation runs well with minimal resources.

Custom Domains: Assign a custom domain for easy client configuration.

Prerequisites

Before deploying musikcube 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 concepts
Your music library files ready to upload
(Optional) A custom domain for your musikcube instance

Understanding musikcube Architecture

musikcube consists of several components:

musikcubed: The headless server daemon that indexes music and serves streams.

Library Database: SQLite database containing music metadata and library information.

Streaming Engine: HTTP-based streaming with optional transcoding.

WebSocket API: Real-time communication for client synchronization.

Preparing Your Repository

Create a GitHub repository with your musikcube configuration.

Repository Structure

musikcube-deploy/
├── Dockerfile
└── .dockerignore

Creating the Dockerfile

Create a Dockerfile in your repository root:

FROM debian:bookworm-slim

# Install dependencies
RUN apt-get update && apt-get install -y \
    wget \
    libev4 \
    libmicrohttpd12 \
    libcurl4 \
    libssl3 \
    libasound2 \
    libpulse0 \
    libsndio7.0 \
    libavcodec59 \
    libavformat59 \
    libavutil57 \
    libswresample4 \
    libtag1v5 \
    && rm -rf /var/lib/apt/lists/*

# Download and install musikcube
RUN wget -O /tmp/musikcube.deb https://github.com/clangen/musikcube/releases/download/3.0.4/musikcube_3.0.4_linux_x86_64.deb \
    && dpkg -i /tmp/musikcube.deb || apt-get install -f -y \
    && rm /tmp/musikcube.deb

# Create directories
RUN mkdir -p /music /data/.musikcube

# Set environment variables
ENV MUSIKCUBE_SERVER_PASSWORD=${MUSIKCUBE_SERVER_PASSWORD}
ENV MUSIKCUBE_SERVER_PORT=7905
ENV MUSIKCUBE_AUDIO_PORT=7906

# Expose ports
# 7905: Metadata and control
# 7906: Audio streaming
EXPOSE 7905 7906

# Create startup script
RUN echo '#!/bin/bash\n\
musikcubed --foreground' > /start.sh && chmod +x /start.sh

# Health check
HEALTHCHECK --interval=30s --timeout=10s --start-period=30s --retries=3 \
    CMD wget --no-verbose --tries=1 --spider http://localhost:7905/ || exit 1

WORKDIR /data
CMD ["/start.sh"]

Creating the .dockerignore File

.git
.github
*.md
LICENSE
.gitignore
*.log
.DS_Store

Environment Variables Reference

Variable	Required	Default	Description
`MUSIKCUBE_SERVER_PASSWORD`	Yes	-	Password for client authentication
`MUSIKCUBE_SERVER_PORT`	No	7905	Metadata and control port
`MUSIKCUBE_AUDIO_PORT`	No	7906	Audio streaming port

Deploying musikcube on Klutch.sh

Push Your Repository to GitHub

Initialize and push your repository with the Dockerfile.

Create a New Project on Klutch.sh

Navigate to the Klutch.sh dashboard and create a new project called “musikcube”.

Create a New App

Within your project, create a new app and connect your GitHub repository.

Configure HTTP Traffic

In the deployment settings:

Select HTTP as the traffic type
Set the internal port to 7905 for the metadata server

Note: Audio streaming on port 7906 may need additional configuration.

Set Environment Variables

Configure the following environment variables:

Variable	Value
`MUSIKCUBE_SERVER_PASSWORD`	A strong password for client authentication

Attach Persistent Volumes

Add the following volumes:

Mount Path	Recommended Size	Purpose
`/music`	50+ GB	Your music library
`/data/.musikcube`	2 GB	Database and configuration

Deploy Your Application

Click Deploy to start the build process.

Upload Your Music

Transfer your music files to the /music volume.

Configure the Server

After deployment, the server will automatically index music in the /music directory.

Connect Clients

Use musikcube clients to connect to your server.

Connecting Clients

Desktop Client (musikcube)

The full musikcube application can connect to remote servers:

Install musikcube on your computer
Press s to access settings
Navigate to “Remote Library” settings
Enter your server details:
- Hostname: your-app-name.klutch.sh
- Port: 7905
- Password: Your configured password

Android Client

The musikcube Android app provides mobile access:

Download from Google Play
Add a new server connection
Enter your server details
Stream your library on mobile

API Access

musikcube exposes a WebSocket-based API for third-party integration:

Connect to wss://your-app-name.klutch.sh/ws
Authenticate with your password
Send commands and receive responses

Library Management

Automatic Indexing

musikcube automatically indexes new music added to the library directory. The indexer runs periodically and on demand.

Supported Formats

musikcube supports all formats handled by FFmpeg:

Lossless: FLAC, ALAC, WAV, AIFF
Lossy: MP3, AAC, OGG, Opus, WMA
Other formats supported by FFmpeg

Metadata Handling

musikcube reads embedded metadata from audio files:

Artist, Album, Title
Track and disc numbers
Genre, Year
Album art

Recommended Directory Structure

/music/
├── Artist Name/
│   ├── Album Name/
│   │   ├── 01 - Track.flac
│   │   ├── 02 - Track.flac
│   │   └── folder.jpg
│   └── Another Album/
└── Various Artists/
    └── Compilation/

Server Configuration

Transcoding Settings

musikcube can transcode audio for bandwidth optimization:

Original quality: Stream files as-is
Reduced bitrate: Compress for mobile connections

Connection Limits

Configure maximum simultaneous connections to manage resources and bandwidth.

SSL/TLS

Klutch.sh provides automatic HTTPS, ensuring secure connections between clients and your server.

Troubleshooting

Client Cannot Connect

Verify the server password is correct
Check that port 7905 is accessible
Ensure the server is running (check logs)

No Music Showing

Verify music files are in the /music directory
Check file permissions
Trigger a library rescan

Playback Issues

Check network connectivity
Try lower quality transcoding for slow connections
Verify audio file integrity

High Memory Usage

Large libraries may require more memory
Consider limiting concurrent streams
Optimize album art sizes

Additional Resources

Conclusion

Deploying musikcube on Klutch.sh gives you a personal music streaming service with native clients for all major platforms. The lightweight C++ implementation means efficient resource usage while still providing high-quality streaming.

With automatic library indexing, transcoding support, and secure HTTPS connections, musikcube on Klutch.sh provides an excellent foundation for streaming your personal music collection from anywhere. Whether you’re at home or on the go, your entire music library is just a connection away.