Deploying mStream

Introduction

mStream is a lightweight, personal music streaming server that lets you stream your entire music collection from any device. Built with Node.js and designed for simplicity, mStream provides a fast, no-frills experience for personal music streaming.

Unlike heavier alternatives, mStream focuses on doing one thing well: streaming your music quickly and reliably. It scans your music library, provides a clean web interface, and offers mobile apps for on-the-go listening.

Key highlights of mStream:

• Lightning Fast: Lightweight design for quick loading and streaming
• Gapless Playback: Seamless transitions between tracks
• Album Art: Automatic album artwork from embedded tags or folder images
• Playlist Support: Create and manage playlists through the interface
• Multi-User: Support for multiple user accounts with separate libraries
• DLNA Support: Stream to DLNA-compatible devices
• Chromecast: Cast music to Chromecast devices
• Mobile Apps: Native apps for iOS and Android
• Scrobbling: Last.fm integration for tracking listening history
• Low Resource Usage: Runs efficiently on minimal hardware
• 100% Open Source: GPL-3.0 licensed

This guide walks through deploying mStream on Klutch.sh using Docker, uploading your music, and streaming from anywhere.

Why Deploy mStream on Klutch.sh

Deploying mStream on Klutch.sh provides several advantages:

Always-On Streaming: Your music is available 24/7 without a home server running.

Simplified Deployment: Klutch.sh builds and deploys without manual Node.js setup.

Persistent Storage: Your music library survives restarts and redeployments.

HTTPS by Default: Secure streaming with automatic SSL certificates.

GitHub Integration: Track configuration changes in version control.

Custom Domains: Stream from your own domain.

Lightweight: mStream’s efficiency means lower resource costs.

Prerequisites

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

• A Klutch.sh account
• A GitHub account with a repository for your configuration
• A music collection in supported formats
• Basic familiarity with Docker

Understanding mStream Architecture

mStream has a simple architecture:

Node.js Server: Core application serving the web interface and API.

File Scanner: Indexes music files and extracts metadata.

SQLite Database: Stores user data, playlists, and library metadata.

Web Interface: Responsive HTML5 player that works on any device.

Preparing Your Repository

Create a GitHub repository for your mStream deployment.

Repository Structure

mstream-deploy/
├── Dockerfile
├── config.json
├── README.md
└── .dockerignore

Creating the Dockerfile

Create a Dockerfile in the root of your repository:

FROM lscr.io/linuxserver/mstream:latest

# Set environment variables
ENV PUID=${PUID:-1000}
ENV PGID=${PGID:-1000}
ENV TZ=${TZ:-America/New_York}

# Expose the web interface
EXPOSE 3000

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

Alternative Dockerfile with Configuration

For more control:

FROM lscr.io/linuxserver/mstream:latest

# User/Group IDs
ENV PUID=${PUID:-1000}
ENV PGID=${PGID:-1000}

# Timezone
ENV TZ=${TZ:-America/New_York}

# Expose web interface
EXPOSE 3000

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

Configuration File

Create config.json for detailed settings:

{
  "port": 3000,
  "secret": "CHANGE_THIS_TO_A_RANDOM_STRING",
  "folders": {
    "music": {
      "root": "/music"
    }
  },
  "users": {
    "admin": {
      "password": "CHANGE_THIS_PASSWORD",
      "vpaths": ["music"],
      "admin": true
    }
  },
  "database": {
    "dbPath": "/config/mstream.db"
  },
  "scanOptions": {
    "scanInterval": 24,
    "saveInterval": 500,
    "skipImg": false
  }
}

Environment Variables Reference

Variable	Required	Default	Description
PUID	No	1000	User ID for file permissions
PGID	No	1000	Group ID for file permissions
TZ	No	UTC	Timezone setting

Deploying mStream on Klutch.sh

Push Your Repository to GitHub

Initialize and push your repository:

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

Create a New Project on Klutch.sh

Navigate to the Klutch.sh dashboard and create a new project named “mstream” or “music”.

Create a New App

Within your project, create a new app. Connect your GitHub account and select the repository containing your Dockerfile.

Configure HTTP Traffic

In the deployment settings:

• Select HTTP as the traffic type
• Set the internal port to 3000

Set Environment Variables

Add the following environment variables:

Variable	Value
PUID	1000
PGID	1000
TZ	Your timezone

Attach Persistent Volumes

Add storage for music and configuration:

Mount Path	Recommended Size	Purpose
/music	100+ GB	Music library storage
/config	1 GB	mStream configuration and database

Deploy Your Application

Click Deploy to start the build process.

Upload Your Music

Transfer your music files to the /music volume.

Access mStream

Once deployed, access mStream at https://your-app-name.klutch.sh.

Initial Configuration

First Login

Access the mStream web interface and log in:

1. Navigate to your mStream URL
2. Use the credentials from your config.json
3. Start browsing your music

Scanning Music Library

Trigger a library scan:

1. Log in as admin
2. Go to Admin Panel
3. Click “Scan Library”
4. Wait for the scan to complete

Creating Users

Add family or friends:

1. Access the Admin Panel
2. Create new user accounts
3. Assign appropriate folder access

Mobile Apps

Official Apps

Download mStream apps for mobile:

• iOS App
• Android App

App Configuration

Connect the mobile app:

1. Open the mStream app
2. Enter your server URL
3. Log in with your credentials
4. Enable offline sync for downloads

Features and Usage

Creating Playlists

Build custom playlists:

1. Browse your music
2. Add songs to the queue
3. Save queue as a playlist
4. Access playlists from the sidebar

Gapless Playback

mStream supports gapless playback:

• Works automatically for supported formats
• Perfect for live albums and mixes
• Enabled by default

Chromecast Support

Cast music to Chromecast:

1. Look for the Cast icon in the player
2. Select your Chromecast device
3. Control playback from mStream

Last.fm Scrobbling

Track your listening:

1. Go to Settings
2. Connect your Last.fm account
3. Plays are automatically scrobbled

Organizing Music

Recommended Structure

/music/
├── Artist Name/
│   ├── Album Name/
│   │   ├── 01 - Track.mp3
│   │   ├── 02 - Track.mp3
│   │   └── cover.jpg
│   └── Another Album/
└── Another Artist/

Supported Formats

• MP3
• FLAC
• OGG
• AAC
• WAV
• OPUS

Album Art

mStream finds album art from:

1. Embedded cover in audio file
2. cover.jpg in album folder
3. folder.jpg in album folder

Troubleshooting

Music Not Appearing

• Verify files are in the correct directory
• Check file format support
• Run a manual library scan

Playback Issues

• Check audio file integrity
• Verify network connectivity
• Clear browser cache

Mobile App Not Connecting

• Ensure HTTPS is working
• Check firewall settings
• Verify credentials

Additional Resources

• mStream Official Website
• mStream GitHub Repository
• mStream Documentation
• mStream Docker Image
• Klutch.sh Persistent Volumes
• Klutch.sh Deployments

Conclusion

Deploying mStream on Klutch.sh gives you a fast, lightweight personal music streaming server. With mobile apps, Chromecast support, and efficient resource usage, mStream provides everything you need for personal music streaming without unnecessary complexity.

Stream your music collection from anywhere with mStream on Klutch.sh.