Overview

tip

For the difference between ENV and File examples in this document see Configuration Types.

Docker

Cross-platform images are built for x86 (Intel/AMD) and ARM64 (IE Raspberry Pi)

Available Images

Dockerhub

Repository Page

docker.io/foxxmd/multi-scrobbler:latest

Github Packages

Repository Page

ghcr.io/foxxmd/multi-scrobbler:latest

Recommended Settings

Storage

You should bind a host directory into the container for storing configurations, credentials, database, and other files. Otherwise, these will be lost when the container is updated.

docker-compose.yml

services:
  multi-scrobbler:
  # ...
  volumes:
    - "./config:/config"

Optionally, use a separate directory for data (database, cache, etc...) by mounting an additional directory and setting the DATA_DIR ENV to the directory that should be used inside the container:

docker-compose.yml

services:
  multi-scrobbler:
  # ...
  environment:
    # ...
    - DATA_DIR=/msData
  volumes:
    - "./config:/config" # used for config files
    - "./my/host/folder:/msData" # used for data files

Networking

If you are using a bridge network (default docker setup) you must map a port to the container in order to access the dashboard and use MS with some sources (Webscrobbler, LFM/LZ Endpoints). The default container port is 9078.

docker-compose.yml

services:
  multi-scrobbler:
  # ...
  ports:
    - "9078:9078"

Base URL

Optionally, when

• using a Source or Client that has a "Redirect URI" that you have not explicitly defined
• and
  • using a bridge network or
  • installing MS on a different machine than the one used to view the dashboard

set the Base URL as the IP of the host machine. (This is the IP you would use to view the dashboard in a browser)

docker-compose.yml

services:
  multi-scrobbler:
  # ...
  environment:
    - BASE_URL=http://hostMachineIP

Timezone

Set the timezone for the container using the environmental variable TZ.

docker-compose.yml

services:
  multi-scrobbler:
  # ...
  environment:
    # Specify timezone from TZ Database name found here https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
    - TZ=America/New_York

Linux Host

If you are running this container with Docker on a Linux Host you should specify user:group permissions of the user who owns the configuration directory on the host 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:

• id -u -- prints UID
• id -g -- prints GID

Read Only

MS can be hardended by setting the file system as read only with read_only, with a few exceptions:

docker-compose.yml

services:
  multi-scrobbler:
    image: foxxmd/multi-scrobbler
    # ...
    read_only: true
    tmpfs:
      - /run:exec
      - /tmp:noexec    

Caching

Optionally, add a Valkey service to your stack for secondary caching to take advantage of faster performance and reduced memory usage.

docker-compose.yml

services:
  multi-scrobbler:
    image: foxxmd/multi-scrobbler
    # ...
    environment:
      # ...
      CACHE_VALKEY=redis://valkey:6379
    # ...

  valkey:
    image: valkey/valkey
    volumes:
      - valkeydata:/data

volumes:
  valkeydata:
    driver: local

Docker Usage Example

tip

See the Quick Start Guide for another guided docker-compose example

The example scenario:

• Jellyfin Source
• Maloja Client
• Serving app on port 9078
• Docker container located on a different IP (192.168.0.100) so use Base URL
• Config/data directory on host machine in a directory next to docker-compose.yml
• Linux uid/gid is 1000:1000
• Optional caching using valkey (after uncommenting)

See docker-compose.yml sample above for more options and annotations.

docker-compose.yml

services:
  multi-scrobbler:
    image: foxxmd/multi-scrobbler
    container_name: multi-scrobbler
    environment:
      - TZ=Etc/GMT # Specify timezone from TZ Database name found here https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
      - JELLYFIN_APIKEY=c9fae8756fbf481ebd9c5bb56bd6540c
      - JELLYFIN_URL=192.168.0.101:8096
      - JELLYFIN_USER=MyUser
      - BASE_URL=http://192.168.0.100:9078
      - MALOJA_URL=http://domain.tld:42010
      - MALOJA_API_KEY=1234
      - PUID=1000
      - PGID=1000
      # uncomment along with valkey service/volume below for better caching
      #- CACHE_METADATA=valkey
      #- CACHE_METADATA_CONN=redis://valkey:6379
    volumes:
      - ./config:/config
    ports:
      - 9078:9078
    restart: unless-stopped
    
    #valkey:
    #    image: valkey/valkey
    #    volumes:
    #        - valkeydata:/data

#volumes:
#    valkeydata:
#        driver: local

Local Installation

After installation see service.md to configure multi-scrobbler to run automatically in the background.

Nodejs

Clone this repository somewhere using the latest git tag and then install from the working directory.

git clone --branch <LATEST_RELEASE_TAG> https://github.com/FoxxMD/multi-scrobbler.git
cd multi-scrobbler
nvm use # optional, to set correct Node version
npm install
npm run docs:install && npm run build
npm run start

Config And Data Directories

The directories MS uses for Configuration (config.json, jellyfin.json, etc...) and Data (database, cache, etc...) can be specified by environmental variables passed directly to npm/node, or set in an .env file in the working directory.

When parsing these ENVs MS will resolve relative directories but not bash expansions like ~ for home. Examples:

• CONFIG_DIR=/my/absolute/path => sets directory to use for config files
• DATA_DIR=./relative/data => sets directory relative to working directory for data files

If you do not set these environmental variables then MS will attempt to use OS-standardized directories:

Linux

• Config => $XDG_CONFIG_HOME/multi-scrobbler or ~/.config/multi-scrobbler
• Data => $XDG_DATA_HOME/multi-scrobbler or ~/.local/share/multi-scrobbler

MacOS

• Config => ~/Library/Preferences/multi-scrobbler
• Data => ~/Library/Application Support/multi-scrobbler

Windows

• Config => %APPDATA%\multi-scrobbler\Config
• Data => %LOCALAPPDATA%\multi-scrobbler\Data

Rollup build error

During building if you encounter an error like: Your current platform "XXX" and architecture "XXX" combination is not yet supported by the native Rollup build.

Modify overrides in package.json to use @rollup/wasm-node as a drop-in replacement for rollup:

"overrides": {
  "spotify-web-api-node": {
    "superagent": "$superagent"
  }
  "vite": {
    "rollup": "npm:@rollup/wasm-node@^4.9.6"
  }
}

See this issue for more detail.

Usage Examples

ENV

JELLYFIN_APIKEY=c9fae8756fbf481ebd9c5bb56bd6540c JELLYFIN_URL=192.168.0.101:8096 JELLYFIN_USER=MyUser MALOJA_URL="http://domain.tld" node src/index.js

File

./config/config.json

./config/config.json

{
    "sources": [
        {
            "type": "jellyfin",
            "clients": ["myConfig"],
            "name": "myJellyfinSource",
            "data": {
                "apiKey": "a89cba1569901a0671d5a9875fed4be1",
                "url": "http://192.168.0.101:8096",
                "user": "MyUser"
             }
        }
    ],
    "clients": [
        {
            "type": "maloja",
            "name": "myConfig",
            "data": {
                "url": "http://localhost:42010",
                "apiKey": "myMalojaKey"
            }
        }
    ],
}

npm run start

tip

The web UI and API is served on port 9078. This can be modified using the PORT environmental variable.

Flatpak

Unsupported

Flatpak/Flathub installs are no longer supported. You can still build MS as a Flatpak app from source. See more information about Flatpak EOL.