Overview
Docker
Section titled “Docker”Cross-platform images are built for x86 (Intel/AMD) and ARM64 (IE Raspberry Pi). Available images:
docker.io/foxxmd/multi-scrobbler:latestghcr.io/foxxmd/multi-scrobbler:latestRecommended Settings
Section titled “Recommended Settings”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.
services: multi-scrobbler: # ... volumes:- 1.Mounts the host directory
./configinto the container at/config
Optional Data Directory
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:
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 Ingress Sources like the Listenbrainz Endpoint.
The default container port is 9078.
services: multi-scrobbler: # ... ports: - "9078:9078"The Base URL is an optional value you can provide to Multi-Scrobbler to let it know what URL it will be accessible from.
Providing this value has many benefits, it is highly recommended that you set it.
Tip The Base URL value is an interactive placeholder. Fill it in to update its usage everywhere on this site.
When using a Source or Client that has a “Redirect URI” that you have not explicitly defined, setting the Base URL allows correct redirect URLs to be generated automatically.
services: multi-scrobbler: # ... environment:- 1.Should be the same URL you would use to view the MS dashboard in a browser
BASE_URL is also used when Securing Your Instance.
When deploying MS to a domain where it will be served under a subpath like
https://YOUR_MS_DOMAIN.com/multiscrobbleryou must define BASE_URL in order for MS to properly serve the dashboard:
services: multi-scrobbler: # ... environment:- 1.multi-scrobbler served under this subpath
This is not required when the root path is /, like https://my-scrobbler.com or scrobbler.mydomain.com.
Self-Hosted Docs
Multi-Scrobbler’s docs are at docs.multi-scrobbler.app but they are also generated and hosted on your instance.
If you are using a subpath and need these self-hosted docs as well you will need to build your own docker image. This is a limitation of Docusaurus, the framework the docs are built on.
This build step is optional and not required for MS to run with a subpath, you just won’t have self-hosted docs and will need to use the official, hosted docs instead.
To build MS with self-hosted docs, provide the same BASE_URL used above as a build arg:
services: multi-scrobbler: build: context: https://github.com/FoxxMD/multi-scrobbler.git args: # ... environment: # ...- 1.remove or comment out the official image, use
buildspec instead to point to the repository - 2.Must include
BASE_URLbuild arg here - 3.multi-scrobbler served under this subpath
Set the timezone for the container using the environmental variable TZ.
services: multi-scrobbler: # ... environment: - TZ=America/New_YorkOptionally, add a Valkey service to your stack for secondary caching to take advantage of faster performance, reduced memory usage, and cached api calls to external services.
services: multi-scrobbler: image: foxxmd/multi-scrobbler # ... environment: # ... CACHE_VALKEY=redis://valkey:6379 # ...
valkey: image: valkey/valkey volumes: - valkeydata:/data
volumes: valkeydata: driver: localThe default image has no shell or system tools. When troubleshooting, especially networking issues, switch to the same version with a -debug suffix, like latest-debug or 1.2.3-debug. It is identical to the normal image but adds a busybox shell and curl.
services: multi-scrobbler: image: foxxmd/multi-scrobbler:latest-debugThen open a shell in the running container:
docker exec -it multi-scrobbler shcurl -v https://example.comSwitch back to the normal image when you are done.
User and Permissions Important
Section titled “User and Permissions Important ”The container runs as a non-root user, UID/GID 65532:65532, by default.
This user must be able to read and write the configuration and data directories you mount into it.
If you bind mount host directories (like ./config:/config from the Storage tab above) choose one of these:
Run the container as the user who owns the directory (simplest).
In this scenario you will be able to edit and read config/db/log files used by MS normally from your host.
Get your UID and GID with id -u and id -g:
$ id -u1000$ id -g1001Then, set user:
services: multi-scrobbler: # ... user: 1000:1001 # ... volumes: - "./config:/config"Run the container as the default user (most isolated).
This is the most secure option as the user unlikely has any privileges on the host machine but it does mean you will need to use sudo to edit config files created by it.
Make sure the host folders already exist and then give the default user ownership, or permission, to create/edit these.
The easiest way to do this is give full ownership:
existing host directorysudo chown -R 65532:65532 ./configIf you have user set in docker-compose.yml then you should remove it now.
Note: The above advice also applies to Docker Desktop on Windows when the directory is inside WSL (like ~/multi-scrobbler/config). Run the commands in your WSL terminal.
Docker Usage Example
Section titled “Docker Usage 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.
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://YOUR_MS_DOMAIN:9078 - MALOJA_URL=http://domain.tld:42010 - MALOJA_API_KEY=1234 # uncomment along with valkey service/volume below for better caching #- CACHE_VALKEY=redis://valkey:6379 user: 1000:1000 volumes: - ./config:/config ports: - 9078:9078 restart: unless-stopped
#valkey: # image: valkey/valkey # volumes: # - valkeydata:/data
#volumes:# valkeydata:# driver: localLocal Installation
Section titled “Local Installation”After installation see As a Service to configure multi-scrobbler to run automatically in the background.
Nodejs
Section titled “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.gitcd multi-scrobblernpm installnpm run docs:install && npm run buildnpm run start- 1.optional, to set correct Node version
Pass ENVs directly to node/npm, or make a new .env (using .env.example as a reference), to configure MS for basic settings and Persistent Directories for config/data/log directories.
Usage Examples
Section titled “Usage Examples”JELLYFIN_APIKEY=c9fae8756fbf481ebd9c5bb56bd6540c JELLYFIN_URL=192.168.0.101:8096 JELLYFIN_USER=MyUser MALOJA_URL="http://domain.tld" node src/index.js./config/config.json
{ "sources": [ { "type": "jellyfin",only scrobbles to the Client with this name "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 startPersistent Directories
Section titled “Persistent Directories”The directories MS uses for
- Configuration -
config.json,jellyfin.json, etc… - Data - database, cache, etc…
- Logs
can be specified by environmental variables passed directly to npm/node, or set in an .env file in the working directory.
Settings these paths is optional. If you do not set paths MS will try to use OS-standardized directories, falling back to subfolders in the working directory (.config/). Note: These paths are automatically set for you when using Docker.
Relative and Absolute Paths Only
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 filesDATA_DIR=./relative/data=> sets directory relative to working directory for data filesLOGS_DIR=~/myDir/logs=> ❌ cannot use this path!
(The bash expansions shown below are for example only)
All of your configuration files, like config.json, jellyfin.json, etc… will be read from this directory.
Order of path acquisition:
$CONFIG_DIR- user-defined (or auto defined in Docker image)$CONFIGURATION_DIRECTORY- defined by systemd- OS-standardized directory from below…
$XDG_CONFIG_HOME/multi-scrobbler or ~/.config/multi-scrobbler
~/Library/Preferences/multi-scrobbler
%APPDATA%\multi-scrobbler\Config
All of the persistent data – like the database (ms.db), cache, and credential files – will be written to this directory.
Order of path acquisition:
$DATA_DIR- user-defined (or auto defined in Docker image)$STATE_DIRECTORY- defined by systemd- OS-standardized directory from below…
$XDG_DATA_HOME/multi-scrobbler or ~/.local/share/multi-scrobbler
~/Library/Application Support/multi-scrobbler
%LOCALAPPDATA%\multi-scrobbler\Data
Logs will be written to this directory.
Order of path acquisition:
$LOGS_DIR- user-defined (or auto defined in Docker image)$LOGS_DIRECTORY- defined by systemd- OS-standardized directory from below…
$XDG_STATE_HOME/multi-scrobbler or ~/.local/state/multi-scrobbler
~/Library/Logs/multi-scrobbler
%LOCALAPPDATA%\multi-scrobbler\Log
Reverse Proxy Recommended
Section titled “Reverse Proxy Recommended”Multi-Scrobbler’s UI performs best when it is behind a reverse proxy, like NGINX (NPM) Traefik or Caddy.
Why: Connection Pooling and Live Events
For connections to domains using HTTP/1.1 (non-TLS http: addresses like http://192.168.0.101) all major browsers use a shared connection pool per domain, that is used across all tabs. This connection pool is limited to 6 concurrent connections.
For non-TLS connections Multi-Scrobbler uses one, always-open SSE connection per tab to send live updates and logs to your browser.
So, with HTTP/1.1, if you open more than 5 tabs of multi-scrobbler you will not be able to communciate to the server through your browser.
Using TLS (like https://ms.mydomain.com), which reverse proxies make easy, removes this connection limit for the pool.
Additionally, using TLS unlocks the ability for Multi-Scrobbler to share a single SSE connection between all tabs which reduces the bandwidth used by all tabs signficantly.
Disable Buffering for Searches
When Multi-Scrobbler performs metadata searches for your Play data it streams results from providers as soon as they arrive, rather than waiting for all providers to respond. This can significantly speed up how soon you see search results in your browser.
Some reverse proxies automatically enable buffering for requests which is usually a good thing but in this scenario prevents you from benefiting streaming results because buffering waits for the entire response before forwarding it to your browser.
Use one of the common methods below to disable buffering for search-related routes. Note: these are not complete solutions, just examples as a jumping off point:
Set flush_interval -1 to disable response buffering.
multi-scrobbler.domain.tld { reverse_proxy multi-scrobbler:9078
@search { method POST GET path /api/metadata/search/* }
reverse_proxy @search multi-scrobbler:9078 { flush_interval -1 }
}NGINX
location /your-route { proxy_pass http://your_backend; proxy_buffering off;}Traefik does not automatically enable buffering. If you use the Buffering middleware then responses are automatically buffered and cannot be disabled, yet.