Something went wrong. Try again.
[READ-ONLY] Mirror of https://github.com/FoxxMD/multi-scrobbler. Scrobble plays from multiple sources to multiple clients docs.multi-scrobbler.app
deezer docker jellyfin koito lastfm listenbrainz maloja mopidy mpris music music-assistant plex scrobble self-hosted spotify subsonic tautulli youtube-music
Something went wrong. Try again.
15 kB · 464 lines
MDX
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464---sidebar_position: 1title: Overviewdescription: Installation---
import Tabs from '@theme/Tabs';import TabItem from '@theme/TabItem';import CodeBlock from '@theme/CodeBlock';import ComposeStack from '!!raw-loader!../../../docker-compose.yml';
:::tip
For the difference between **ENV** and **File** examples in this document see [Configuration Types](../configuration/configuration.mdx#configuration-types).
:::
## Docker
Cross-platform images are built for x86 (Intel/AMD) and ARM64 (IE Raspberry Pi)
:::info[Available Images]
<Tabs> <TabItem value="docker" label="Dockerhub"> [Repository Page](https://hub.docker.com/r/foxxmd/multi-scrobbler) ``` docker.io/foxxmd/multi-scrobbler:latest ``` </TabItem> <TabItem value="ghcr" label="Github Packages"> [Repository Page](https://github.com/FoxxMD/multi-scrobbler/pkgs/container/multi-scrobbler) ``` ghcr.io/foxxmd/multi-scrobbler:latest ``` </TabItem></Tabs>
:::
### Recommended Settings
<Tabs groupId="dockerSetting" queryString><TabItem value="storage" label="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.
```yaml title="docker-compose.yml"services: multi-scrobbler: # ... // highlight-start volumes: - "./config:/config" // highlight-end```
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:
```yaml title="docker-compose.yml"services: multi-scrobbler: # ... environment: # ... // highlight-start - DATA_DIR=/msData // highlight-end volumes: - "./config:/config" # used for config files // highlight-start - "./my/host/folder:/msData" # used for data files // highlight-end```
</TabItem><TabItem value="networking" label="Networking">If you are using a [bridge network](https://www.appsdeveloperblog.com/docker-networking-bridging-host-and-overlay/) (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`.
```yaml title="docker-compose.yml"services: multi-scrobbler: # ... // highlight-start ports: - "9078:9078" // highlight-end```
:::important
If your machine is accessible from the public internet consider installing multi-scrobbler on a different, private machine.
**Read [Securing Multi-Scrobbler](/configuration/security)**
:::
</TabItem><TabItem value="baseUrl" label="Base URL">
<Tabs groupId="baseUrlUsage"><TabItem value="redirect" label="Redirects">**Optionally**, when
* using a [Source or Client](../configuration/configuration.mdx) 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](../configuration/configuration.mdx#base-url) as the IP/domain of the host machine. (This is the IP you would use to view the dashboard in a browser)
```yaml title="docker-compose.yml"services: multi-scrobbler: # ... environment: // highlight-start - BASE_URL=http://hostMachineIP // highlight-end```</TabItem><TabItem value="subpath" label="Deploying MS with a Subpath">When deploying MS to a domain where it will be served under a **subpath**, like `http://mydomain.com/multiscrobbler`, you **must** define `BASE_URL`:
```yaml title="docker-compose.yml"services: multi-scrobbler: # ... environment: // highlight-start # multi-scrobbler served under this subpath - BASE_URL=https://mydomain.com/multiscrobbler // highlight-end```
This is **not required** when the root path is `/`, like `https://my-scrobbler.com` or `scrobbler.mydomain.com`.
<DetailsAdmo type="important" summary="Self-Hosted Docs">
Multi-Scrobbler's docs are at [docs.multi-scrobbler.app](https://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:
```yaml title="docker-compose.yml"services: multi-scrobbler: // highlight-start ## remove/comment out official image # image: docker.io/foxxmd/multi-scrobbler:latest ## add build spec build: context: https://github.com/FoxxMD/multi-scrobbler.git args: - BASE_URL=https://mydomain.com/multiscrobbler // highlight-end # ... environment: # ... // highlight-start # multi-scrobbler served under this subpath - BASE_URL=https://mydomain.com/multiscrobbler // highlight-end```
</DetailsAdmo></TabItem></Tabs>
</TabItem><TabItem value="tz" label="Timezone">Set the [timezone](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) for the container using the environmental variable `TZ`.
```yaml title="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 // highlight-start - TZ=America/New_York // highlight-end```
</TabItem><TabItem value="linuxHost" label="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 and data directories** on the host to avoid [docker file permission problems.](https://ikriv.com/blog/?p=4698) These can be specified using the [environmental variables **PUID** and **PGID**.](https://docs.linuxserver.io/general/understanding-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</TabItem><TabItem value="ro" label="Read Only">MS can be hardended by setting the file system as read only with [`read_only`](https://docs.docker.com/reference/compose-file/services/#read_only), with a few exceptions:
```yaml title="docker-compose.yml"services: multi-scrobbler: image: foxxmd/multi-scrobbler # ... // highlight-start read_only: true tmpfs: - /run:exec - /tmp:noexec // highlight-end ```
</TabItem><TabItem value="caching" label="Caching">**Optionally**, add a [Valkey](https://valkey.io/) service to your stack for [secondary caching](/configuration#secondary-caching) to take advantage of faster performance, reduced memory usage, and cached api calls to external services.
```yaml title="docker-compose.yml"services: multi-scrobbler: image: foxxmd/multi-scrobbler # ... environment: # ... // highlight-start CACHE_VALKEY=redis://valkey:6379 // highlight-end # ...
// highlight-start valkey: image: valkey/valkey volumes: - valkeydata:/data
volumes: valkeydata: driver: local // highlight-end```
</TabItem></Tabs>
### Docker Usage Example
:::tip
See the [**Quick Start Guide**](/quickstart) for another guided docker-compose example
:::
The example scenario:
* [Jellyfin **Source**](/configuration/sources/jellyfin)* [Maloja **Client**](/configuration/sources/maloja)* Serving app on port `9078`* Docker container located on a different IP (`192.168.0.100`) so use [Base URL](/configuration#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`](#docker) sample above for more options and annotations.
```yaml title="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_VALKEY=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 [As a Service](/installation/service) to configure multi-scrobbler to run automatically in the background.
### Nodejs
Clone this repository somewhere using the latest [git tag](/updating#git) and then install from the working directory.
```shellgit clone --branch <LATEST_RELEASE_TAG> https://github.com/FoxxMD/multi-scrobbler.gitcd multi-scrobblernvm use # optional, to set correct Node versionnpm installnpm run docs:install && npm run buildnpm run start```
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**](./?#persistent-directories) for config/data/log directories.
#### Usage Examples
:::note
Regardless of the config type you are using, some settings must be set via ENV such as [**Persistent Directories**](./?#persistent-directories) for config/data/log directories.
:::
<Tabs groupId="configType" queryString><TabItem value="env" label="ENV">```shellJELLYFIN_APIKEY=c9fae8756fbf481ebd9c5bb56bd6540c JELLYFIN_URL=192.168.0.101:8096 JELLYFIN_USER=MyUser MALOJA_URL="http://domain.tld" node src/index.js```</TabItem><TabItem value="file" label="File">
<details> <summary>`./config/config.json`</summary>
```json title="./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" } } ], } ```
</details>
```shellnpm run start```</TabItem></Tabs>
:::tip
The web UI and API is served on port `9078`. This can be modified using the `PORT` environmental variable.
:::
## 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.**
<DetailsAdmo type="note" summary="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 files* `DATA_DIR=./relative/data` => sets directory relative to working directory for data files* `LOGS_DIR=~/myDir/logs` => ❌ cannot use this path!
(The bash expansions shown below are for example only)
</DetailsAdmo>
<Tabs groupId="dirType" queryString> <TabItem value="config" label="Config">
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](/installation/service) * OS-standardized directory from below... <Tabs> <TabItem value="linux" label="Linux"> `$XDG_CONFIG_HOME/multi-scrobbler` or `~/.config/multi-scrobbler` </TabItem> <TabItem value="mac" label="MacOS"> `~/Library/Preferences/multi-scrobbler` </TabItem> <TabItem value="win" label="Windows"> `%APPDATA%\multi-scrobbler\Config` </TabItem> </Tabs> </TabItem> <TabItem value="data" label="Data"> 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](/installation/service) * OS-standardized directory from below... <Tabs> <TabItem value="linux" label="Linux"> `$XDG_DATA_HOME/multi-scrobbler` or `~/.local/share/multi-scrobbler` </TabItem> <TabItem value="mac" label="MacOS"> `~/Library/Application Support/multi-scrobbler` </TabItem> <TabItem value="win" label="Windows"> `%LOCALAPPDATA%\multi-scrobbler\Data` </TabItem> </Tabs> </TabItem> <TabItem value="logs" label="Logs"> 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](/installation/service) * OS-standardized directory from below... <Tabs> <TabItem value="linux" label="Linux"> `$XDG_STATE_HOME/multi-scrobbler` or `~/.local/state/multi-scrobbler` </TabItem> <TabItem value="mac" label="MacOS"> `~/Library/Logs/multi-scrobbler` </TabItem> <TabItem value="win" label="Windows"> `%LOCALAPPDATA%\multi-scrobbler\Log` </TabItem> </Tabs> </TabItem></Tabs>