Deploying Meelo

Introduction

Meelo is a self-hosted music server designed for organizing and streaming your personal music collection. Built with a focus on metadata accuracy and a clean interface, Meelo automatically fetches album art, artist information, and track details from various sources to create a beautifully organized music library.

The application provides a modern web interface for browsing and streaming your music, with support for various audio formats. Meelo emphasizes proper music organization with features for handling compilations, multi-disc albums, and various artist types.

Key highlights of Meelo:

• Automatic Metadata: Fetches album art, artist bios, and track information automatically
• Clean Interface: Modern, responsive web interface for browsing and playing music
• Smart Organization: Properly handles compilations, soundtracks, and multi-disc albums
• Multiple Format Support: Plays MP3, FLAC, OGG, and other common audio formats
• Artist Management: Distinguishes between album artists, track artists, and featured artists
• Library Statistics: View insights about your music collection
• Search and Filter: Find music quickly with comprehensive search
• Scrobbling: Optional Last.fm integration for tracking listening habits
• Self-Hosted: Complete control over your music library and data
• Open Source: Transparent, community-driven development

This guide walks through deploying Meelo on Klutch.sh using Docker, configuring persistent storage for your music library, and setting up the application for streaming.

Why Deploy Meelo on Klutch.sh

Deploying Meelo on Klutch.sh provides several advantages for self-hosted music streaming:

Simplified Deployment: Klutch.sh automatically detects your Dockerfile and builds Meelo without complex orchestration. Push to GitHub, and your music server deploys automatically.

Persistent Storage: Attach persistent volumes for your music library and database. Your collection survives container restarts and redeployments.

HTTPS by Default: Klutch.sh provides automatic SSL certificates for secure music streaming from anywhere.

GitHub Integration: Connect your configuration repository directly from GitHub. Updates trigger automatic redeployments.

Scalable Resources: Allocate CPU and memory based on your library size and expected concurrent users.

Custom Domains: Assign a custom domain to your Meelo instance for easy access.

Always-On Availability: Your music server remains accessible 24/7 without managing your own hardware.

Prerequisites

Before deploying Meelo 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 ready for upload
• (Optional) A custom domain for your Meelo instance

Preparing Your Repository

To deploy Meelo on Klutch.sh, create a GitHub repository containing your Dockerfile and configuration.

Repository Structure

meelo-deploy/
├── Dockerfile
├── README.md
└── .dockerignore

Creating the Dockerfile

Create a Dockerfile in the root of your repository:

FROM ghcr.io/keikomono96/meelo:latest

# Set environment variables
ENV MEELO_PORT=3000
ENV MEELO_DATABASE_PATH=/data/meelo.db
ENV MEELO_MUSIC_PATH=/music

# Create necessary directories
RUN mkdir -p /data /music

# Expose the web interface port
EXPOSE 3000

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

Environment Variables Reference

Variable	Required	Default	Description
MEELO_PORT	No	3000	Web interface port
MEELO_DATABASE_PATH	No	./meelo.db	Path to SQLite database
MEELO_MUSIC_PATH	No	/music	Path to music library
MEELO_SCAN_INTERVAL	No	3600	Library scan interval in seconds
LASTFM_API_KEY	No	-	Last.fm API key for scrobbling
LASTFM_API_SECRET	No	-	Last.fm API secret

Deploying on Klutch.sh

Push Your Repository to GitHub

Initialize your repository and push to GitHub:

git init
git add Dockerfile .dockerignore README.md
git commit -m "Initial Meelo deployment configuration"
git remote add origin https://github.com/yourusername/meelo-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. Give it a descriptive name like “meelo” or “music-server”.

Create a New App

Within your project, create a new app. Connect your GitHub account if you haven’t already, then select the repository containing your Meelo Dockerfile.

Configure HTTP Traffic

Meelo serves its web interface over HTTP. 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
MEELO_DATABASE_PATH	/data/meelo.db
MEELO_MUSIC_PATH	/music

Attach Persistent Volumes

Add the following volumes:

Mount Path	Recommended Size	Purpose
/data	5 GB	Database and application data
/music	Size of your library	Music files

Deploy Your Application

Click Deploy to start the build process. Klutch.sh will:

• Detect your Dockerfile automatically
• Build the container image
• Attach the persistent volumes
• Start the Meelo container
• Provision an HTTPS certificate

Access Meelo

Once deployment completes, access your Meelo instance at https://example-app.klutch.sh.

Initial Setup

First-Time Configuration

When you first access Meelo:

1. Create your admin account
2. Configure your music library path
3. Initiate the first library scan

Library Scanning

Meelo scans your music directory to build the library:

1. Navigate to Settings > Library
2. Click Scan Library
3. Wait for the scan to complete
4. Review any unmatched or problematic tracks

Metadata Fetching

Meelo automatically fetches metadata:

• Album artwork from various sources
• Artist biographies and images
• Track information and lyrics
• Genre and release year data

Organizing Your Music

Recommended Folder Structure

For best results, organize your music like this:

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

File Naming Best Practices

• Include track numbers in filenames
• Use consistent artist and album naming
• Embed metadata in files when possible
• Include album art as cover.jpg or folder.jpg

Handling Compilations

Meelo properly handles compilation albums:

• Use “Various Artists” as album artist
• Keep individual track artists in metadata
• Group compilation tracks together

Using Meelo

Browsing Your Library

Navigate your collection by:

• Artists: Browse alphabetically or by genre
• Albums: View all albums with artwork
• Tracks: Search or browse all songs
• Genres: Filter by musical genre

Playing Music

• Click any track to start playing
• Use the queue to manage upcoming tracks
• Create playlists for your favorites
• Shuffle or repeat as desired

Search

Find music quickly:

• Search by artist, album, or track name
• Filter results by type
• Use advanced search for specific criteria

Advanced Features

Last.fm Scrobbling

Track your listening habits:

1. Get API keys from Last.fm
2. Add keys to environment variables
3. Authenticate with your Last.fm account
4. Scrobbles are sent automatically

Library Statistics

View insights about your collection:

• Total tracks, albums, and artists
• Most played songs
• Recently added content
• Storage usage

Troubleshooting

Music Not Appearing

• Verify files are in the correct directory
• Check file format compatibility
• Review scan logs for errors
• Ensure proper file permissions

Missing Metadata

• Check your internet connection
• Some obscure releases may not have metadata
• Consider manually editing metadata
• Try re-scanning affected albums

Playback Issues

• Verify browser supports the audio format
• Check network connectivity
• Try a different browser
• Review container logs for errors

Additional Resources

• Meelo GitHub Repository
• Klutch.sh Persistent Volumes
• Klutch.sh Deployments

Conclusion

Deploying Meelo on Klutch.sh gives you a beautiful, self-hosted music streaming solution that properly organizes your collection. With automatic metadata fetching and a clean interface, Meelo transforms your music files into a organized, accessible library.

The combination of Meelo’s organization features and Klutch.sh’s reliable infrastructure means you can enjoy your music from anywhere while maintaining complete control over your collection. Whether you have hundreds or thousands of albums, Meelo on Klutch.sh provides the foundation for a personal music streaming service that rivals commercial offerings.