From 8b0c7205b7fa4693b47149bfa0f17d7dff153226 Mon Sep 17 00:00:00 2001 From: FoxxMD Date: Wed, 17 Jul 2024 11:33:56 -0400 Subject: [PATCH] docs: Add quick start guide --- README.md | 6 +- docsite/docs/configuration/_category_.json | 2 +- docsite/docs/configuration/configuration.mdx | 3 +- docsite/docs/development/_category_.json | 2 +- docsite/docs/installation/_category_.json | 2 +- docsite/docs/installation/installation.mdx | 38 +++-- docsite/docs/installation/service.md | 4 +- docsite/docs/quickstart.mdx | 165 +++++++++++++++++++ docsite/docusaurus.config.ts | 9 +- docsite/package-lock.json | 9 + docsite/package.json | 1 + docsite/src/pages/index.mdx | 6 + 12 files changed, 223 insertions(+), 24 deletions(-) create mode 100644 docsite/docs/quickstart.mdx diff --git a/README.md b/README.md index db651089..affa2cb0 100644 --- a/README.md +++ b/README.md @@ -39,7 +39,7 @@ A javascript app to scrobble music you listened to, to [Maloja](https://github.c * Easy configuration through ENVs or JSON * Install using [Docker images for x86/ARM](https://foxxmd.github.io/multi-scrobbler/docs/installation#docker#docker), [flatpak](https://foxxmd.github.io/multi-scrobbler/docs/installation#docker#flatpak), or [locally with NodeJS](https://foxxmd.github.io/multi-scrobbler/docs/installation#docker#nodejs) -[**Read The Docs to get started**](https://foxxmd.github.io/multi-scrobbler/docs/installation) +[**Quick Start Guide**](https://foxxmd.github.io/multi-scrobbler/docs/quickstart) @@ -77,6 +77,10 @@ Client configurations consist of: * A friendly name. * Any data needed to communicate or authenticate with the Client. +## Quick Start + +[See the **Quick Start Guide**](https://foxxmd.github.io/multi-scrobbler/docs/quickstart) + ## Installation [See the **Installation** documentation](https://foxxmd.github.io/multi-scrobbler/docs/installation) diff --git a/docsite/docs/configuration/_category_.json b/docsite/docs/configuration/_category_.json index 18e70148..1ec2cf62 100644 --- a/docsite/docs/configuration/_category_.json +++ b/docsite/docs/configuration/_category_.json @@ -1,6 +1,6 @@ { "label": "Configuration", - "position": 2, + "position": 3, "link": { "type": "generated-index", "description": "Configuring Multi-Scrobbler and examples" diff --git a/docsite/docs/configuration/configuration.mdx b/docsite/docs/configuration/configuration.mdx index ad52731e..5eb6e645 100644 --- a/docsite/docs/configuration/configuration.mdx +++ b/docsite/docs/configuration/configuration.mdx @@ -357,6 +357,8 @@ Can use this source for any application that implements the [Subsonic API](http: ### [Jellyfin](https://jellyfin.org/) +#### Webhook Setup + Must be using Jellyfin 10.7 or greater * In the Jellyfin desktop web UI Navigate to -> Administration -> Dashboard -> Plugins -> Catalog @@ -1310,7 +1312,6 @@ or replace `localhost:9078` with your own base URL | `LASTFM_SECRET` | Yes | | Shared secret from your API Account | | `LASTFM_REDIRECT_URI` | No | `http://localhost:9078/lastfm/callback` | Url to use for authentication. Must include `lastfm/callback` somewhere in it | | `LASTFM_SESSION` | No | | Session id. Will be generated by authentication flow if not provided. | - LastfmClientConfig diff --git a/docsite/docs/development/_category_.json b/docsite/docs/development/_category_.json index 6942c16c..10e299b6 100644 --- a/docsite/docs/development/_category_.json +++ b/docsite/docs/development/_category_.json @@ -1,6 +1,6 @@ { "label": "Development", - "position": 3, + "position": 4, "link": { "type": "generated-index", "description": "Developing for Multi-Scrobbler and tutorials" diff --git a/docsite/docs/installation/_category_.json b/docsite/docs/installation/_category_.json index 89454591..126765d8 100644 --- a/docsite/docs/installation/_category_.json +++ b/docsite/docs/installation/_category_.json @@ -1,6 +1,6 @@ { "label": "Installation", - "position": 1, + "position": 2, "link": { "type": "generated-index", "description": "Way to install Multi-Scrobbler" diff --git a/docsite/docs/installation/installation.mdx b/docsite/docs/installation/installation.mdx index 9113deb6..dbe1f40d 100644 --- a/docsite/docs/installation/installation.mdx +++ b/docsite/docs/installation/installation.mdx @@ -285,6 +285,12 @@ To get the UID and GID for the current user run these commands from a terminal: ### Docker Usage Example +:::tip + +See the [**Quick Start Guide**](../quickstart.mdx) for another guided docker-compose example + +::: + The example scenario: * [Spotify **Source**](../configuration/configuration.mdx#spotify) @@ -315,22 +321,22 @@ The example scenario: ```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 - - SPOTIFY_CLIENT_ID=yourId - - SPOTIFY_CLIENT_SECRET=yourSecret - - BASE_URL="http://192.168.0.100:9078" - - MALOJA_URL=http://domain.tld:42010 - - MALOJA_API_KEY=1234 - - PUID=1000 - - PGID=1000 - volumes: - - /home/myUser/ms:/config - ports: - - "9078:9078" - restart: unless-stopped + 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 + - SPOTIFY_CLIENT_ID=yourId + - SPOTIFY_CLIENT_SECRET=yourSecret + - BASE_URL="http://192.168.0.100:9078" + - MALOJA_URL=http://domain.tld:42010 + - MALOJA_API_KEY=1234 + - PUID=1000 + - PGID=1000 + volumes: + - /home/myUser/ms:/config + ports: + - "9078:9078" + restart: unless-stopped ``` diff --git a/docsite/docs/installation/service.md b/docsite/docs/installation/service.md index d561b7f5..77bcdbbb 100644 --- a/docsite/docs/installation/service.md +++ b/docsite/docs/installation/service.md @@ -17,7 +17,7 @@ This setup will create a [user service](https://wiki.archlinux.org/title/systemd Create a new service file for multi-scrobbler under your HOME config: -```console +```bash mkdir -p ~/.config/systemd/user touch ~/.config/systemd/user/multi-scrobbler.service ``` @@ -56,7 +56,7 @@ Restart=no Save the file then run: -```console +```bash systemctl daemon-reload systemctl --user enable multi-scrobbler.service systemctl --user start multi-scrobbler.service diff --git a/docsite/docs/quickstart.mdx b/docsite/docs/quickstart.mdx new file mode 100644 index 00000000..2c2e0d50 --- /dev/null +++ b/docsite/docs/quickstart.mdx @@ -0,0 +1,165 @@ +--- +title: 'Quickstart' +sidebar_position: 1 +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +This guide will get you up and running with multi-scrobbler using [Docker](https://www.docker.com/) and [`docker compose`](https://docs.docker.com/compose/). At the end of the guide you will have: + +* the dashboard served on port `9078` of a host machine which has an IP of `192.168.0.100` +* data saved to the same directory as the `docker-compose.yml` file +* multi-scrobbler monitoring [Spotify](./configuration/configuration.mdx#spotify) and/or [Jellyfin](./configuration/configuration.mdx#jellyfin) for listening activity +* multi-scrobbler scrobbling to [Lastfm](./configuration/configuration.mdx#lastfm) and/or [Maloja](./configuration/configuration.mdx#maloja) + +:::note + +If the multi-scrobbler container is on the same machine you will be viewing the dashboard from (IE `localhost`) you can remove and ignore `BASE_URL` usage below. Additionally, replace usage of `192.168.0.100` with `localhost`. + +::: + +## Create Docker Compose File + +Create a new folder for multi-scrobbler related data and then create `docker-compose.yml` with this content: + +```yaml title="~/msData/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 + - BASE_URL="http://192.168.0.100:9078" + # all Environmental Variables in below examples go here! + + volumes: + - "$PWD/config:/config" + ports: + - "9078:9078" + restart: unless-stopped +``` + +## Setup Sources + +**Sources** are the services multi-scrobbler monitors to look for listening activity. + + + + Follow the Jellyfin configuration [instructions for setting up a **webhook**.](./configuration/configuration.mdx#jellyfin) + + After webhook is setup add **at least one** of these values to the `environment` section in the [`docker-compose.yml` you created.](#create-docker-compose-file) + + ```yaml title="~/msData/docker-compose.yml" + - JELLYFIN_USER=myUserName # comma-separated list of users to monitor + - JELLYFIN_SERVER=myServerName # comma-separated list of servers that should be monitored + ``` + + + To access your Spotify activity you must [register a Spotify application](https://developer.spotify.com/dashboard) to get a + **Client ID/Secret**. + + When creating the application add this to **Redirect URIs** + + ``` + http://192.168.0.100:9078/callback + ``` + + After the application is created add these values to the `environment` section in the [`docker-compose.yml` you created.](#create-docker-compose-file) + + ```yaml title="~/msData/docker-compose.yml" + - SPOTIFY_CLIENT_ID=yourClientId + - SPOTIFY_CLIENT_SECRET=yourClientSecret + ``` + + Later, after [starting multi-scrobbler](#start-multi-scrobbler), visit the dashboard at `http://192.168.0.100:9078` and click **(Re)authenticate** on the Spotify card to authorize multi-scrobbler to use your account. Monitoring will begin automatically after authorization is complete. + + + +## Setup Clients + +**Clients** are services that store scrobbles. Multi-scrobbler will scrobble all listening activity from the **Sources** you configured to all **Clients** you configure here. + + + + Setup a [Maloja server](https://github.com/krateng/maloja?tab=readme-ov-file#how-to-install) if you have not already done this. + +
+ + Maloja Setup Intructions + + Using Maloja's example `docker-compose.yml`: + + ```yaml reference title="~/malojaData/docker-compose.yml" + https://github.com/krateng/maloja/blob/master/example-compose.yml + ``` + + Uncomment `environment` and add `MALOJA_FORCE_PASSWORD=CHANGE_ME` to set an admin password + + Start the container: + + ```shell title="~/malojaData" + docker compose up -d + ``` +
+ + * Navigate to the Admin Panel (Cog in upper-right corner) -> API Keys (or at http://192.168.0.100:42010/admin_apikeys) + * Create a **New Key** and then copy the generated key value + + Finally, add these values to the `environment` section in the [`docker-compose.yml` you created for multi-scrobbler earlier.](#create-docker-compose-file) + + ```yaml title="~/msData/docker-compose.yml" + - MALOJA_URL="http://192.168.0.100:42010" + - MALOJA_API_KEY=myApiKey + ``` + + + [Register for an API account at Last.fm.](https://www.last.fm/api/account/create) + + Use the following for **Callback URL**: + + ``` + http://192.168.0.100:9078/lastfm/callback + ``` + + After account creation use the displayed information and add these values to the `environment` section in the [`docker-compose.yml` you created for multi-scrobbler earlier.](#create-docker-compose-file) + + ```yaml title="~/msData/docker-compose.yml" + - LASTFM_API_KEY=myApiKey + - LASTFM_SECRET=myApiSecret + ``` + + + +## Start Multi-Scrobbler + +:::tip + +If you are running your multi-scrobbler container on a Linux host see [these instructions for setting proper file permissions.](./installation/installation.mdx#linux-host) + +::: + +From the same directory as the [`docker-compose.yml` you created earlier](#create-docker-compose-file) start the container: + +```shell title="~/msData" +docker compose up -d +``` + +You're done! Multi-scrobbler is now running. It will monitor the sources you configured and scrobble to clients you set up. + +Visit `http://192.168.0.100:9078` to see the dashboard where + +* configured Sources/Clients + * show current status and authentication options + * display statistics about discovered/scrobbled tracks and Now Playing status +* a real-time log shows multi-scrobbler's activity + +## Next Steps + +* See more advanced docker options as well as other install methods in the [**Installation**](./installation/installation.mdx#docker) docs +* Review the [**Configuration**](./configuration/configuration.mdx) docs + * Learn about how to configure multi-scrobbler using files for more complicated Source/Client scenarios + * See all available Sources/Clients alongside configuration examples + * Learn how to set up [notification webhooks](./configuration/configuration.mdx#webhook-configurations) + * Check out the [kitchensink example](./configuration/kitchensink.md) +* Consult the [**FAQ**](./FAQ.md) for solutions to common problems diff --git a/docsite/docusaurus.config.ts b/docsite/docusaurus.config.ts index 9771fa08..04f48d10 100644 --- a/docsite/docusaurus.config.ts +++ b/docsite/docusaurus.config.ts @@ -75,6 +75,7 @@ const config: Config = { // ``` }, ], + 'docusaurus-theme-github-codeblock' ], plugins: [ ], @@ -155,13 +156,19 @@ const config: Config = { prism: { theme: themes.themes.github, darkTheme: themes.themes.dracula, - additionalLanguages: ['json','json5','typescript'] + additionalLanguages: ['json','json5','typescript', 'docker', 'bash', 'ini'] }, colorMode: { defaultMode: 'dark', disableSwitch: false, respectPrefersColorScheme: false, }, + codeblock: { + showGithubLink: true, + githubLinkLabel: 'View on GitHub', + showRunmeLink: false, + runmeLinkLabel: 'Checkout via Runme' + } } satisfies Preset.ThemeConfig, }; diff --git a/docsite/package-lock.json b/docsite/package-lock.json index 3e072045..baae91f4 100644 --- a/docsite/package-lock.json +++ b/docsite/package-lock.json @@ -14,6 +14,7 @@ "@mdx-js/react": "^3.0.0", "clsx": "^2.0.0", "docusaurus-json-schema-plugin": "^1.12.1", + "docusaurus-theme-github-codeblock": "^2.0.2", "micromark-extension-directive": "^3.0.1", "prism-react-renderer": "^2.3.0", "raw-loader": "^4.0.2", @@ -5991,6 +5992,14 @@ "react": ">=17 <= 18" } }, + "node_modules/docusaurus-theme-github-codeblock": { + "version": "2.0.2", + "resolved": "https://registry.npmjs.org/docusaurus-theme-github-codeblock/-/docusaurus-theme-github-codeblock-2.0.2.tgz", + "integrity": "sha512-H2WoQPWOLjGZO6KS58Gsd+eUVjTFJemkReiSSu9chqokyLc/3Ih3+zPRYfuEZ/HsDvSMIarf7CNcp+Vt+/G+ig==", + "dependencies": { + "@docusaurus/types": "^3.0.0" + } + }, "node_modules/dom-converter": { "version": "0.2.0", "resolved": "https://registry.npmjs.org/dom-converter/-/dom-converter-0.2.0.tgz", diff --git a/docsite/package.json b/docsite/package.json index 211a9aa6..ef4958f8 100644 --- a/docsite/package.json +++ b/docsite/package.json @@ -20,6 +20,7 @@ "@mdx-js/react": "^3.0.0", "clsx": "^2.0.0", "docusaurus-json-schema-plugin": "^1.12.1", + "docusaurus-theme-github-codeblock": "^2.0.2", "micromark-extension-directive": "^3.0.1", "prism-react-renderer": "^2.3.0", "raw-loader": "^4.0.2", diff --git a/docsite/src/pages/index.mdx b/docsite/src/pages/index.mdx index 7904d6d0..e5f8137a 100644 --- a/docsite/src/pages/index.mdx +++ b/docsite/src/pages/index.mdx @@ -40,6 +40,8 @@ A javascript app to scrobble music you listened to, to [Maloja](https://github.c * Easy configuration through ENVs or JSON * Install using [Docker images for x86/ARM](docs/installation#docker), [flatpak](docs/installation#flatpak), or [locally with NodeJS](docs/installation#nodejs) +[**Quick Start Guide**](docs/quickstart) + **Why should I use this over a browser extension and/or mobile app scrobbler?** @@ -76,6 +78,10 @@ Client configurations consist of: * A friendly name. * Any data needed to communicate or authenticate with the Client. +## Quick Start + +[See the **Quick Start Guide**](docs/quickstart.mdx) + ## Installation [See the **Installation** documentation](docs/installation)