---
sidebar_position: 1
title: Overview
description: 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
```

</TabItem>
<TabItem value="baseUrl" label="Base URL">
**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 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="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 [service.md](service.md) 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.

```shell
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:

<Tabs>
    <TabItem value="linux" label="Linux">
        * Config => `$XDG_CONFIG_HOME/multi-scrobbler` or `~/.config/multi-scrobbler`
        * Data => `$XDG_DATA_HOME/multi-scrobbler` or `~/.local/share/multi-scrobbler`
    </TabItem>
    <TabItem value="mac" label="MacOS">
        * Config => `~/Library/Preferences/multi-scrobbler`
        * Data => `~/Library/Application Support/multi-scrobbler`
    </TabItem>
    <TabItem value="win" label="Windows">
        * Config => `%APPDATA%\multi-scrobbler\Config`
        * Data => `%LOCALAPPDATA%\multi-scrobbler\Data`
    </TabItem>
</Tabs>


#### 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:

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

See [this issue](https://github.com/FoxxMD/multi-scrobbler/issues/135#issuecomment-1927080260) for more detail.

#### Usage Examples

<Tabs groupId="configType" queryString>
<TabItem value="env" label="ENV">
```shell
JELLYFIN_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>

```shell
npm run start
```
</TabItem>
</Tabs>

:::tip

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

:::

### Flatpak

:::warning[Unsupported]

Flatpak/Flathub installs are no longer supported. You can still build MS as a [Flatpak app from source.](../development/flatpak) See more information about [Flatpak EOL.](https://github.com/FoxxMD/multi-scrobbler/issues/287)

:::