[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
docs: Add upgrade path for 0.14.0
+295
-3
+29
-3
docsite/docs/updating/updating.mdx
+29
-3
docsite/docs/updating/updating.mdx
···
10
10
11
11
## Updating
12
12
13
-
Currently, multi-scrobbler does not have any databases or dependencies that require additional interaction when updating.
13
+
The majority of Multi-scrobbler updates can be completed without any manual intervention. This is **guaranteed** for [patch version updates](#versioning).
14
14
15
-
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)
15
+
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.
16
16
17
-
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)
17
+
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).
18
+
19
+
### Database
20
+
21
+
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).
22
+
23
+
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.
24
+
25
+
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`.
26
+
27
+
:::tip
28
+
29
+
If upgrading a [minor version](#versioning) you may want to make a backup for extra safety.
30
+
31
+
:::
32
+
33
+
### Configuration
34
+
35
+
[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.
36
+
37
+
38
+
## Update Instructions
39
+
40
+
Assuming:
41
+
42
+
* 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
43
+
* you have checked the release notes, upgrade paths docs, and completed all migration steps for the specific version upgrade
18
44
19
45
<Tabs groupId="installType" queryString>
20
46
<TabItem value="docker-compose" label="Docker Compose">
+7
docsite/docs/updating/upgradePath/_category_.json
+7
docsite/docs/updating/upgradePath/_category_.json
+205
docsite/docs/updating/upgradePath/from0140.mdx
+205
docsite/docs/updating/upgradePath/from0140.mdx
···
1
+
---
2
+
sidebar_position: 1
3
+
title: From < 0.14.0
4
+
description: Upgrading to 0.14.0
5
+
---
6
+
7
+
import Tabs from '@theme/Tabs';
8
+
import TabItem from '@theme/TabItem';
9
+
import CodeBlock from '@theme/CodeBlock';
10
+
import RequiredUpgrade from "@site/src/components/snippets/_upgrade-required.mdx"
11
+
12
+
<RequiredUpgrade before='< 0.14.0' current='0.14.0' old='0.13.2' />
13
+
14
+
## Source/Client IDs
15
+
16
+
MS `0.14.0` introduces a database for persisting Plays/Scrobbles, queues, and other data **associated with a Source/Client**.
17
+
18
+
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**.
19
+
20
+
This ID needs to be unique to the client or source type it is used on IE:
21
+
22
+
* two [Koito Clients](/configuration/clients/koito/) cannot both have the ID `myKoitoID`
23
+
* it is recommended that the ID be *globally* unique among all sources/clients, but it's not required
24
+
25
+
### Configuring IDs
26
+
27
+
<Tabs groupId="configType" queryString>
28
+
29
+
<TabItem value="env" label="ENV">
30
+
31
+
For each Source/Client in your environmental variables, add a key with the suffix `_ID` and the ID value. EX
32
+
33
+
```yaml title="compose.yaml"
34
+
services:
35
+
multi-scrobbler:
36
+
# ...
37
+
environment:
38
+
- KOTIO_TOKEN=...
39
+
# ...more koito config
40
+
// highlight-start
41
+
- KOITO_ID=myKoitoID
42
+
// highlight-end
43
+
44
+
- JELLYFIN_URL=...
45
+
# ...more jellyin config
46
+
// highlight-start
47
+
- JELLYFIN_ID=myJellyfinID
48
+
// highlight-end
49
+
```
50
+
51
+
</TabItem>
52
+
<TabItem value="file" label="File">
53
+
54
+
Add an `id` to the top-level for each Source/Client configuration, next to `data`:
55
+
56
+
```json title="koito.json"
57
+
[
58
+
{
59
+
"name": "koito-source",
60
+
"configureAs": "source",
61
+
// highlight-start
62
+
"id": "myKoitoID",
63
+
// highlight-end
64
+
"data": {
65
+
"token": "029b081ba-9156-4pe7-88e5-3be671f5ea2b",
66
+
"username": "admin",
67
+
"url": "http://192.168.0.100:4110"
68
+
}
69
+
}
70
+
]
71
+
```
72
+
73
+
</TabItem>
74
+
<TabItem value="aio" label="AIO">
75
+
76
+
Add an `id` to the top-level for each Source/Client configuration, next to `data`:
77
+
78
+
```json title="koito.json"
79
+
[
80
+
{
81
+
"name": "koito-source",
82
+
"configureAs": "source",
83
+
"type": "koito",
84
+
// highlight-start
85
+
"id": "myKoitoID",
86
+
// highlight-end
87
+
"data": {
88
+
"token": "029b081ba-9156-4pe7-88e5-3be671f5ea2b",
89
+
"username": "admin",
90
+
"url": "http://192.168.0.100:4110"
91
+
}
92
+
}
93
+
]
94
+
```
95
+
96
+
</TabItem>
97
+
</Tabs>
98
+
99
+
:::note[Default ID]
100
+
101
+
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.
102
+
103
+
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.
104
+
105
+
:::
106
+
107
+
## Cached Scrobble Migration
108
+
109
+
:::tip
110
+
111
+
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.
112
+
113
+
:::
114
+
115
+
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`.
116
+
117
+
On first run of `0.14.0`:
118
+
119
+
* MS will make a copy of `ms-scrobble.cache` named `ms-scrobble.cache.bak`
120
+
* You may make a manual copy of this file before upgrading, for additional safety
121
+
* Scrobbles in the cache will automatically be migrated to the new database
122
+
* The now "old" cache data will be cleared so that subsequent application starts don't duplicate migrations
123
+
* the empty `ms-scrobble.cache` file will remain
124
+
125
+
You can follow progress of this by looking for log lines starting with `Migrating cached scrobbles to database...`
126
+
127
+
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.
128
+
129
+
## Cache Configuration
130
+
131
+
In `0.14.0` [Cache](/configuration/cache) has been simplified with much of the required configuration being removed.
132
+
133
+
:::tip
134
+
135
+
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)
136
+
137
+
If you do not have any of the above [Cache](/configuration/cache) configuration defined then you can **skip this step.**
138
+
139
+
:::
140
+
141
+
#### Scrobble Caching Removed
142
+
143
+
[Scrobble caching has removed and replaced by the new database.](#cached-scrobble-migration)
144
+
145
+
* Remove any ENV Config starting with `CACHE_SCROBBLE`
146
+
* Remove `cache.scrobble` from the AIO Config
147
+
148
+
#### Metadata Config Simplified
149
+
150
+
Metadata caching remains the same but the config has been simplified. If you were using [Valkey for caching](/configuration/#secondary-caching) update your config:
151
+
152
+
<Tabs groupId="configType" queryString>
153
+
154
+
<TabItem value="env" label="ENV">
155
+
156
+
* Remove `CACHE_METADATA`
157
+
* Rename `CACHE_METADATA_CONN` to [`CACHE_VALKEY`](/configuration/#secondary-caching)
158
+
159
+
</TabItem>
160
+
<TabItem value="aio" label="AIO">
161
+
162
+
Remove `cache.metadata` and add a new string key `valkey` to the `cache` object, containing your valkey connection string:
163
+
164
+
```diff
165
+
"cache": {
166
+
+ "valkey": "redis://valkey:6379"
167
+
- "metadata": {
168
+
- "provider": "valkey",
169
+
- "connection": "redis://valkey:6379"
170
+
- }
171
+
}
172
+
```
173
+
174
+
</TabItem>
175
+
</Tabs>
176
+
177
+
178
+
#### Auth Config Simplified
179
+
180
+
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.
181
+
182
+
<Tabs groupId="configType" queryString>
183
+
184
+
<TabItem value="env" label="ENV">
185
+
186
+
* Remove `CACHE_AUTH_CONN`
187
+
* Add [`CACHE_VALKEY`](/configuration/#secondary-caching) (if using valkey)
188
+
189
+
</TabItem>
190
+
<TabItem value="aio" label="AIO">
191
+
192
+
Remove the `connection` property from the `auth` object. If using `file` the entire `auth` object can be removed.
193
+
194
+
```diff
195
+
"cache": {
196
+
+ "valkey": "redis://valkey:6379",
197
+
"auth": {
198
+
"provider": "valkey",
199
+
- "connection": "redis://valkey:6379"
200
+
}
201
+
}
202
+
```
203
+
204
+
</TabItem>
205
+
</Tabs>
+39
docsite/docs/updating/upgradePath/upgradePath.mdx
+39
docsite/docs/updating/upgradePath/upgradePath.mdx
···
1
+
---
2
+
sidebar_position: 1
3
+
title: Upgrade Path
4
+
description: Updating Multi-Scrobbler
5
+
---
6
+
7
+
import Tabs from '@theme/Tabs';
8
+
import TabItem from '@theme/TabItem';
9
+
import CodeBlock from '@theme/CodeBlock';
10
+
11
+
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.
12
+
13
+
Upgrade paths for specific version, detailed here, are reserved for:
14
+
15
+
<Tabs groupId="upgradeType" queryString>
16
+
17
+
<TabItem value="required" label="Required Upgrades">
18
+
19
+
:::warning[Required Upgrade]
20
+
21
+
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.
22
+
23
+
:::
24
+
25
+
</TabItem>
26
+
27
+
<TabItem value="depth" label="In Depth Upgrades">
28
+
29
+
:::note[Optional Upgrade]
30
+
31
+
(Breaking) Changes to configuration/data that require more detail or formatting than is feasible in Github release notes. These upgrades may be skipped.
32
+
33
+
:::
34
+
35
+
</TabItem>
36
+
37
+
</Tabs>
38
+
39
+
The type of upgrade is shown at the top of each page with the same colored callout shown above.
docsite/src/components/snippets/_upgrade-optional.mdx
docsite/src/components/snippets/_upgrade-optional.mdx
This is a binary file and will not be displayed.
+15
docsite/src/components/snippets/_upgrade-required.mdx
+15
docsite/src/components/snippets/_upgrade-required.mdx
···
1
+
:::warning[Required Upgrade]
2
+
3
+
You **MUST** upgrade to this version **before** upgrading Multi-Scrobbler to a newer version.
4
+
5
+
This version contains functionality to migrate your data from **{props.before}** that newer versions depend on.
6
+
7
+
<details>
8
+
9
+
<summary>Upgrade Process Example</summary>
10
+
11
+
* Upgrade Multi-Scrobbler {props.old} to {props.current}
12
+
* **After** upgrading, you can optionally upgrade to > {props.current}
13
+
14
+
</details>
15
+
:::