Deploying Maloja

Introduction

Maloja is a self-hosted music scrobbling server that lets you track your listening history with complete data ownership and privacy. Unlike centralized services like Last.fm, Maloja gives you full control over your listening data while providing beautiful statistics and visualizations about your music habits.

Built with Python, Maloja is designed to be lightweight yet feature-rich. It supports multiple scrobbling protocols, making it compatible with a wide range of music players and apps. Whether you’re listening on your phone, desktop, or smart speakers, Maloja can capture and store your listening history.

Key highlights of Maloja:

• Complete Data Ownership: Your listening history stays on your server, never shared with third parties
• Multiple Protocol Support: Compatible with Last.fm, ListenBrainz, and native API scrobbling
• Beautiful Statistics: Detailed charts and graphs showing your listening trends over time
• Artist and Album Tracking: Comprehensive statistics for artists, albums, and individual tracks
• Time-Based Analysis: View your listening habits by day, week, month, or year
• Data Import: Import existing scrobble history from Last.fm or ListenBrainz
• Data Export: Export your data in multiple formats for backup or analysis
• Native API: RESTful API for building custom integrations
• Docker Support: Easy deployment with official Docker images
• No Account Required: No email, no registration, just your music data

This guide walks through deploying Maloja on Klutch.sh using Docker, configuring scrobbling clients, and managing your personal music listening history.

Why Deploy Maloja on Klutch.sh

Deploying Maloja on Klutch.sh provides several advantages for music tracking:

Always-On Scrobbling: Your Maloja server runs 24/7, capturing every song you play regardless of when you listen.

Remote Access: View your listening statistics and manage your server from anywhere with an internet connection.

HTTPS by Default: Automatic SSL certificates ensure secure scrobbling from all your devices.

Persistent Storage: Your listening history persists across container restarts and redeployments.

GitHub Integration: Update your configuration through Git, with automatic redeployments on push.

Scalable Resources: Allocate resources based on your listening volume and historical data size.

Custom Domains: Set up a memorable domain for your personal music tracking server.

Prerequisites

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

• A Klutch.sh account
• A GitHub account with a repository for your Maloja configuration
• Music players or apps that support scrobbling (Last.fm protocol, ListenBrainz, or Maloja native)
• (Optional) Existing scrobble data from Last.fm or ListenBrainz to import

Understanding Maloja Architecture

Maloja is designed as a simple, single-container application:

Python Backend: The core application is written in Python using the Doreah micro-framework, providing both the web interface and API endpoints.

SQLite Database: All scrobble data is stored in a SQLite database, making backups simple and portable.

Built-in Web Server: Maloja includes its own web server, requiring no external web server configuration.

File-Based Configuration: Configuration is managed through environment variables and configuration files in the data directory.

Extensible Architecture: The API allows for custom integrations and automation.

Preparing Your Repository

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

Repository Structure

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

Creating the Dockerfile

Create a Dockerfile in the root of your repository:

FROM krateng/maloja:latest

# Environment variables for configuration
ENV MALOJA_DATA_DIRECTORY=/data
ENV MALOJA_HOST=0.0.0.0
ENV MALOJA_PORT=42010

# Set timezone (optional)
ENV TZ=${TZ:-UTC}

# Create data directory
RUN mkdir -p /data

# Expose the web interface port
EXPOSE 42010

Advanced Dockerfile with Custom Settings

For more control over your deployment:

FROM krateng/maloja:latest

# Core configuration
ENV MALOJA_DATA_DIRECTORY=/data
ENV MALOJA_HOST=0.0.0.0
ENV MALOJA_PORT=42010

# Timezone
ENV TZ=${TZ:-UTC}

# Scrobble settings
ENV MALOJA_SCROBBLE_THRESHOLD=${MALOJA_SCROBBLE_THRESHOLD:-50}
ENV MALOJA_INVALID_ARTISTS=${MALOJA_INVALID_ARTISTS:-}
ENV MALOJA_REMOVE_FEATURED_ARTISTS=${MALOJA_REMOVE_FEATURED_ARTISTS:-false}

# Third-party integrations
ENV MALOJA_LASTFM_API_KEY=${MALOJA_LASTFM_API_KEY:-}
ENV MALOJA_SPOTIFY_API_ID=${MALOJA_SPOTIFY_API_ID:-}
ENV MALOJA_SPOTIFY_API_SECRET=${MALOJA_SPOTIFY_API_SECRET:-}

# Create necessary directories
RUN mkdir -p /data/logs /data/backups

# Expose the application port
EXPOSE 42010

Creating the .dockerignore File

Create a .dockerignore file:

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

Environment Variables Reference

Variable	Required	Default	Description
MALOJA_DATA_DIRECTORY	No	/data	Directory for storing database and configuration
MALOJA_HOST	No	0.0.0.0	Host address to bind to
MALOJA_PORT	No	42010	Port for the web interface
MALOJA_SCROBBLE_THRESHOLD	No	50	Minimum percentage of song to count as scrobble
MALOJA_LASTFM_API_KEY	No	-	Last.fm API key for fetching artist images
MALOJA_SPOTIFY_API_ID	No	-	Spotify API ID for metadata fetching
MALOJA_SPOTIFY_API_SECRET	No	-	Spotify API secret for metadata fetching

Deploying Maloja on Klutch.sh

Once your repository is prepared, follow these steps to deploy Maloja:

Push Your Repository to GitHub

Initialize your repository and push to GitHub:

git init
git add Dockerfile .dockerignore
git commit -m "Initial Maloja deployment configuration"
git remote add origin https://github.com/yourusername/maloja-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 “maloja” or “music-scrobbler”.

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 Maloja Dockerfile.

Configure HTTP Traffic

Maloja serves its web interface over HTTP. In the deployment settings:

• Select HTTP as the traffic type
• Set the internal port to 42010 (Maloja’s default port)

Set Environment Variables

In the environment variables section, add optional configurations:

Variable	Value
TZ	Your timezone (e.g., America/New_York)
MALOJA_LASTFM_API_KEY	Your Last.fm API key (for artist images)

Attach Persistent Volume

Persistent storage is essential for your listening history. Add a volume:

Mount Path	Recommended Size	Purpose
/data	5 GB	Database, configuration, images, and backups

Deploy Your Application

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

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

Access Maloja

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

Initial Setup and Configuration

First-Time Access

When you first access your Maloja instance:

1. Navigate to the Setup page from the menu
2. Create an API key for scrobbling (click Generate New Key)
3. Copy and save this API key securely - you’ll need it for your scrobbling clients

Web Interface Overview

Maloja’s interface includes several sections:

• Pulse: Real-time view of recent scrobbles
• Charts: Top artists, albums, and tracks
• Statistics: Detailed listening analytics
• Settings: Configuration and API key management

Configuring Third-Party Integrations

For enhanced metadata and artist images:

Last.fm API Key:

1. Create an API account at Last.fm API
2. Add the API key to your environment variables
3. Redeploy your application

Spotify API:

1. Create an application at Spotify Developer Dashboard
2. Add both the client ID and secret to environment variables
3. Redeploy your application

Configuring Scrobbling Clients

Maloja supports multiple scrobbling protocols. Here’s how to configure popular music players:

Multi-Scrobbler (Recommended)

Multi-Scrobbler is a universal scrobbling application that supports many sources:

1. Deploy or install Multi-Scrobbler
2. Configure your music sources (Spotify, Plex, Jellyfin, etc.)
3. Add Maloja as a scrobble destination with your API key

Pano Scrobbler (Android)

1. Install Pano Scrobbler from Play Store
2. Go to Settings > Services
3. Add a ListenBrainz-compatible service
4. Set URL to https://your-app-name.klutch.sh
5. Enter your API key as the token

Web Scrobbler (Browser Extension)

1. Install Web Scrobbler browser extension
2. Go to extension options
3. Under “Scrobble Services”, add ListenBrainz-compatible
4. Set your Maloja URL and API key

Navidrome/Jellyfin

For self-hosted music servers:

1. Enable scrobbling in your media server settings
2. Configure the scrobble endpoint to your Maloja URL
3. Use the native Maloja API or Last.fm compatibility mode

Desktop Players

Many desktop players support Last.fm scrobbling. Set:

• URL: https://your-app-name.klutch.sh/apis/audioscrobbler
• Username: Any value (not used)
• Password: Your Maloja API key

Importing Existing Data

Importing from Last.fm

1. Export your Last.fm data using Last.fm to CSV or similar tool
2. Convert to Maloja’s expected format
3. Upload through the web interface or API

Importing from ListenBrainz

1. Export your ListenBrainz data
2. Use Maloja’s import functionality
3. Review and confirm the import

API Import

Use Maloja’s API for programmatic imports:

curl -X POST https://your-app-name.klutch.sh/apis/mlj_1/newscrobble \
  -H "Content-Type: application/json" \
  -d '{
    "key": "your-api-key",
    "artists": ["Artist Name"],
    "title": "Track Title",
    "album": "Album Name",
    "time": 1609459200
  }'

Managing Your Data

Viewing Statistics

Maloja provides comprehensive statistics:

• Top Artists/Albums/Tracks: Customizable time ranges
• Listening Trends: Charts showing listening patterns over time
• Scrobbles Per Day/Week/Month: Track your listening frequency
• Compare Time Periods: See how your taste has changed

Exporting Data

Back up your listening history:

1. Navigate to Settings
2. Use the Export function
3. Choose your preferred format (CSV, JSON)
4. Download your complete scrobble history

Data Cleanup

Maloja allows you to clean up your data:

• Merge Duplicate Artists: Combine variations of artist names
• Fix Album Associations: Correct misattributed tracks
• Delete Scrobbles: Remove unwanted entries

Production Best Practices

Security Recommendations

• Protect Your API Key: Never share or commit your API key publicly
• Use HTTPS: Klutch.sh provides this automatically
• Regular Backups: Export your data periodically

Backup Strategy

1. Database Backups: Regularly export the SQLite database from /data
2. Configuration Export: Back up your settings and API keys
3. Scrobble Export: Periodically export your listening history in portable formats

Performance Optimization

• Regular Maintenance: Maloja handles optimization automatically
• Storage Monitoring: Monitor your volume usage as your history grows
• Resource Allocation: Increase resources if response times slow with large datasets

Troubleshooting Common Issues

Scrobbles Not Recording

Symptoms: Plays aren’t appearing in Maloja.

Solutions:

• Verify your API key is correct in your scrobbling client
• Check the scrobble threshold setting (some short plays may not count)
• Verify the endpoint URL includes the correct protocol (HTTPS)
• Test with a manual API call to isolate the issue

Artist Images Not Loading

Symptoms: Artist pages show placeholder images.

Solutions:

• Configure a Last.fm or Spotify API key
• Check API key validity
• Some artists may not have images available

Slow Performance

Symptoms: Pages load slowly, especially statistics.

Solutions:

• Increase allocated resources in Klutch.sh
• Limit time ranges for statistics queries
• Consider cleaning up duplicate entries

Web Interface Not Accessible

Symptoms: Cannot connect to Maloja.

Solutions:

• Verify the deployment is running in Klutch.sh dashboard
• Confirm HTTP traffic type is selected with port 42010
• Check deployment logs for errors

Additional Resources

• Maloja GitHub Repository
• Maloja Wiki
• Multi-Scrobbler for Universal Scrobbling
• Last.fm API Documentation
• Klutch.sh Persistent Volumes
• Klutch.sh Deployments

Conclusion

Deploying Maloja on Klutch.sh gives you a private, self-hosted music scrobbling server that runs continuously and captures your listening history with complete privacy. With support for multiple scrobbling protocols, you can track plays from virtually any music player or streaming service.

The combination of Maloja’s comprehensive statistics and Klutch.sh’s reliable hosting means you can explore your listening habits through beautiful visualizations while maintaining complete ownership of your data. Whether you’re curious about your most-played artists or want to see how your taste has evolved over the years, Maloja provides the insights while keeping your data private.

Take control of your music listening history and never worry about a third-party service shutting down or changing its policies with your scrobble data locked away.