diff --git a/docsite/docs/updating/updating.mdx b/docsite/docs/updating/updating.mdx index 74aec376..18d99e24 100644 --- a/docsite/docs/updating/updating.mdx +++ b/docsite/docs/updating/updating.mdx @@ -10,11 +10,37 @@ import CodeBlock from '@theme/CodeBlock'; ## Updating -Currently, multi-scrobbler does not have any databases or dependencies that require additional interaction when updating. +The majority of Multi-scrobbler updates can be completed without any manual intervention. This is **guaranteed** for [patch version updates](#versioning). -Any **breaking changes** will be related to [configuration](/configuration) that has been deprecated/changed, or tooling that usually only affects [Local Installations.](/installation#local-installation) +Regardless, it is recommended to consult the [**Github Release Notes**](https://github.com/FoxxMD/multi-scrobbler/releases) before any upgrades. The release notes contain all changelogs as well as most **breaking changes**/notices. -These changes, and how to update configs accordingly, are detailed in [**Github Release Notes**](https://github.com/FoxxMD/multi-scrobbler/releases). It is recommended to check this page before upgrading [minor or major versions.](#versioning) +The [**Upgrade Path** docs](/configuration/updating/upgrade-path) contain information for upgrading through **required versions** or in-depth migration guides. Check this section before upgrading any [minor versions](#versioning). + +### Database + +Multi-scrobbler depends on a SQLite database (`ms.db`) that is created on first run and stored in the [`CONFIG_DIR`](/installation/?dockerSetting=storage#recommended-settings). + +If any database migrations are required for an update then your database is **automatically backed up** before migration occurs. The backup file is created in the same directory. + +You can manually make a backup of this database by making a copy of `ms.db` and any similarly named files like `ms.db-journal`. + +:::tip + +If upgrading a [minor version](#versioning) you may want to make a backup for extra safety. + +::: + +### Configuration + +[Minor versions](#versioning) may have **breaking changes** related to [configuration](/configuration). Consult the [**Github Release Notes**](https://github.com/FoxxMD/multi-scrobbler/releases) and [Upgrade Paths](/configuration/updating/upgrade-path) before upgrading. + + +## Update Instructions + +Assuming: + +* upgrade(s) are only [patch versions](#versioning) and the [Release Notes](https://github.com/FoxxMD/multi-scrobbler/releases) do not contain any other guidance or +* you have checked the release notes, upgrade paths docs, and completed all migration steps for the specific version upgrade diff --git a/docsite/docs/updating/upgradePath/_category_.json b/docsite/docs/updating/upgradePath/_category_.json new file mode 100644 index 00000000..c040a491 --- /dev/null +++ b/docsite/docs/updating/upgradePath/_category_.json @@ -0,0 +1,7 @@ +{ + "label": "Upgrade Path", + "link": { + "type": "doc", + "id": "updating/upgradePath/upgradePath" + } +} diff --git a/docsite/docs/updating/upgradePath/from0140.mdx b/docsite/docs/updating/upgradePath/from0140.mdx new file mode 100644 index 00000000..02df4733 --- /dev/null +++ b/docsite/docs/updating/upgradePath/from0140.mdx @@ -0,0 +1,205 @@ +--- +sidebar_position: 1 +title: From < 0.14.0 +description: Upgrading to 0.14.0 +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; +import RequiredUpgrade from "@site/src/components/snippets/_upgrade-required.mdx" + + + +## Source/Client IDs + +MS `0.14.0` introduces a database for persisting Plays/Scrobbles, queues, and other data **associated with a Source/Client**. + +To make this association atomic a Source/Client **ID** is now configurable. This ID is what MS will use to identify the Source/Client in your **config** with the Source/Client in the **database**. + +This ID needs to be unique to the client or source type it is used on IE: + +* two [Koito Clients](/configuration/clients/koito/) cannot both have the ID `myKoitoID` +* it is recommended that the ID be *globally* unique among all sources/clients, but it's not required + +### Configuring IDs + + + + + +For each Source/Client in your environmental variables, add a key with the suffix `_ID` and the ID value. EX + +```yaml title="compose.yaml" +services: + multi-scrobbler: + # ... + environment: + - KOTIO_TOKEN=... + # ...more koito config + // highlight-start + - KOITO_ID=myKoitoID + // highlight-end + + - JELLYFIN_URL=... + # ...more jellyin config + // highlight-start + - JELLYFIN_ID=myJellyfinID + // highlight-end +``` + + + + +Add an `id` to the top-level for each Source/Client configuration, next to `data`: + +```json title="koito.json" +[ + { + "name": "koito-source", + "configureAs": "source", + // highlight-start + "id": "myKoitoID", + // highlight-end + "data": { + "token": "029b081ba-9156-4pe7-88e5-3be671f5ea2b", + "username": "admin", + "url": "http://192.168.0.100:4110" + } + } +] +``` + + + + +Add an `id` to the top-level for each Source/Client configuration, next to `data`: + +```json title="koito.json" +[ + { + "name": "koito-source", + "configureAs": "source", + "type": "koito", + // highlight-start + "id": "myKoitoID", + // highlight-end + "data": { + "token": "029b081ba-9156-4pe7-88e5-3be671f5ea2b", + "username": "admin", + "url": "http://192.168.0.100:4110" + } + } +] +``` + + + + +:::note[Default ID] + +If you do not add an ID then Multi-Scrobbler will automatically use the **name** of the Source/Client as the ID. The name is shown in the Dashboard. + +If you decide to add an ID later you must use the name as the ID in order to keep Plays/Scobbles associated with the same config. + +::: + +## Cached Scrobble Migration + +:::tip + +Before upgrading, if your MS dashboard shows 0 queued/failed for all [Scrobble Clients](/configuration/clients) then you **skip this step** and can safely delete `ms-scrobble.cache` before the upgrade occurs. + +::: + +MS `0.14.0` introduces a database for persisting Plays/Scrobbles, queues, and other data. Prior to `0.14.0`, queued/failed scrobbles were stored in a cache **file** inside your [`CONFIG_DIR`](/installation/?dockerSetting=storage#recommended-settings) named `ms-scrobble.cache`. + +On first run of `0.14.0`: + +* MS will make a copy of `ms-scrobble.cache` named `ms-scrobble.cache.bak` + * You may make a manual copy of this file before upgrading, for additional safety +* Scrobbles in the cache will automatically be migrated to the new database +* The now "old" cache data will be cleared so that subsequent application starts don't duplicate migrations + * the empty `ms-scrobble.cache` file will remain + +You can follow progress of this by looking for log lines starting with `Migrating cached scrobbles to database...` + +If MS does not report/log any errors during this time and you see your scrobbles processed normally then it is safe to delete `ms-scrobble.cache` the next time MS is stopped/restarted. + +## Cache Configuration + +In `0.14.0` [Cache](/configuration/cache) has been simplified with much of the required configuration being removed. + +:::tip + +This only applies to users who have `cache` in their [AIO Config](configuration/?configType=aio#configuration-types) `config.json` or are using `CACHE_*` [ENV Config](configuration/?configType=env#configuration-types) + +If you do not have any of the above [Cache](/configuration/cache) configuration defined then you can **skip this step.** + +::: + +#### Scrobble Caching Removed + +[Scrobble caching has removed and replaced by the new database.](#cached-scrobble-migration) + +* Remove any ENV Config starting with `CACHE_SCROBBLE` +* Remove `cache.scrobble` from the AIO Config + +#### Metadata Config Simplified + +Metadata caching remains the same but the config has been simplified. If you were using [Valkey for caching](/configuration/#secondary-caching) update your config: + + + + + +* Remove `CACHE_METADATA` +* Rename `CACHE_METADATA_CONN` to [`CACHE_VALKEY`](/configuration/#secondary-caching) + + + + +Remove `cache.metadata` and add a new string key `valkey` to the `cache` object, containing your valkey connection string: + +```diff + "cache": { ++ "valkey": "redis://valkey:6379" +- "metadata": { +- "provider": "valkey", +- "connection": "redis://valkey:6379" +- } + } +``` + + + + + +#### Auth Config Simplified + +Auth caching remains the same but the config has been simplified. The connection option for Auth is no longer configurable. You may specify provider as either `file` (default, uses `CONFIG_DIR`) or `valkey`. If you want to use Valkey for auth it will use the same config as Metadata. + + + + + +* Remove `CACHE_AUTH_CONN` +* Add [`CACHE_VALKEY`](/configuration/#secondary-caching) (if using valkey) + + + + +Remove the `connection` property from the `auth` object. If using `file` the entire `auth` object can be removed. + +```diff + "cache": { ++ "valkey": "redis://valkey:6379", + "auth": { + "provider": "valkey", +- "connection": "redis://valkey:6379" + } + } +``` + + + \ No newline at end of file diff --git a/docsite/docs/updating/upgradePath/upgradePath.mdx b/docsite/docs/updating/upgradePath/upgradePath.mdx new file mode 100644 index 00000000..8f3505b6 --- /dev/null +++ b/docsite/docs/updating/upgradePath/upgradePath.mdx @@ -0,0 +1,39 @@ +--- +sidebar_position: 1 +title: Upgrade Path +description: Updating Multi-Scrobbler +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + +The majority of changes are detailed in [**Github Release Notes**](https://github.com/FoxxMD/multi-scrobbler/releases), including *most* breaking changes. You should consult the release notes for each version you will be updating through/to. + +Upgrade paths for specific version, detailed here, are reserved for: + + + + + +:::warning[Required Upgrade] + +Versions you **must** upgrade to **before** upgrading to a newer version. Likely due to the codebase containing functionality to upgrade persistent data that cannot be migrating across multiple versions. + +::: + + + + + +:::note[Optional Upgrade] + +(Breaking) Changes to configuration/data that require more detail or formatting than is feasible in Github release notes. These upgrades may be skipped. + +::: + + + + + +The type of upgrade is shown at the top of each page with the same colored callout shown above. \ No newline at end of file diff --git a/docsite/src/components/snippets/_upgrade-optional.mdx b/docsite/src/components/snippets/_upgrade-optional.mdx new file mode 100644 index 00000000..e69de29b diff --git a/docsite/src/components/snippets/_upgrade-required.mdx b/docsite/src/components/snippets/_upgrade-required.mdx new file mode 100644 index 00000000..657519f9 --- /dev/null +++ b/docsite/src/components/snippets/_upgrade-required.mdx @@ -0,0 +1,15 @@ +:::warning[Required Upgrade] + +You **MUST** upgrade to this version **before** upgrading Multi-Scrobbler to a newer version. + +This version contains functionality to migrate your data from **{props.before}** that newer versions depend on. + +
+ +Upgrade Process Example + +* Upgrade Multi-Scrobbler {props.old} to {props.current} +* **After** upgrading, you can optionally upgrade to > {props.current} + +
+::: \ No newline at end of file