Home

Awesome

Maloja

Simple self-hosted music scrobble database to create personal listening statistics.

screenshot

You can check my own Maloja page as an example instance.

Table of Contents

Features

How to install

Requirements

Maloja should run on any x86 or ARM machine that runs Python.

It is highly recommended to use Docker or Podman.

Your CPU should have a single core passmark score of at the very least 1500. 500 MB RAM should give you a decent experience, but performance will benefit greatly from up to 2 GB.

Docker / Podman

Pull the latest image or check out the repository and use the included Containerfile.

Of note are these settings which should be passed as environmental variables to the container:

You must publish a port on your host machine to bind to the container's web port (default 42010). The container uses IPv4 per default.

An example of a minimum run configuration to access maloja via localhost:42010:

	docker run -p 42010:42010 -v $PWD/malojadata:/mljdata -e MALOJA_DATA_DIRECTORY=/mljdata krateng/maloja

Linux Host

NOTE: If you are using rootless containers with Podman this DOES NOT apply to you.

If you are running Docker on a Linux Host you should specify user:group ids of the user who owns the folder on the host machine bound to MALOJA_DATA_DIRECTORY in order to avoid docker file permission problems. These can be specified using the environmental variables PUID and PGID.

To get the UID and GID for the current user run these commands from a terminal:

The modified run command with these variables would look like:

	docker run -e PUID=1000 -e PGID=1001 -p 42010:42010 -v $PWD/malojadata:/mljdata -e MALOJA_DATA_DIRECTORY=/mljdata krateng/maloja

PyPI

You can install Maloja with

	pip install malojaserver

To make sure all dependencies are installed, you can also use one of the included scripts in the install folder.

From Source

Clone this repository and enter the directory with

	git clone https://github.com/krateng/maloja
	cd maloja

Then install all the requirements and build the package, e.g.:

	sh ./install/install_dependencies_alpine.sh
	pip install -r requirements.txt
	pip install .

Extras

How to use

Basic control

When not running in a container, you can run the application with maloja run. You can also run it in the background with maloja start and maloja stop, but this might not be supported in the future.

Data

If you would like to import your previous scrobbles, use the command maloja import *filename*. This works on:

⚠️ Never import your data while maloja is running. When you need to do import inside docker container start it in shell mode instead and perform import before starting the container as mentioned above.

	docker run -it --entrypoint sh -v $PWD/malojadata:/mljdata -e MALOJA_DATA_DIRECTORY=/mljdata krateng/maloja
	cd /mljdata
	maloja import my_last_fm_export.csv

To backup your data, run maloja backup, optional with --include_images.

Customization

How to scrobble

You can set up any amount of API keys in the file apikeys.yml in your configuration folder (or via the web interface). It is recommended to define a different API key for every scrobbler you use.

Some scrobbler clients support Maloja's native API. You can also use any scrobbler that allows you to set a custom Listenbrainz or GNUFM server. See API.md for details.

If you're the maintainer of a music player or server and would like to implement native Maloja scrobbling, feel free to reach out!

If you can't automatically scrobble your music, you can always do it manually on the /admin_manual page of your Maloja server.

How to extend

If you'd like to implement anything on top of Maloja, visit /api_explorer.