v4_to_v5_migration.md

Migrating from v4.x.x to v5.x.x

Version 5.0.0 of Tauticord introduces major changes, including:

• A major change to the structure (schema) of the configuration (YAML) file
• Configuration file renamed from config.yamlto tauticord.yaml
• Dropped support for configuration via environmental variables

This guide details the differences between the config file used in v4.x.x and earlier and the new version using in v5.x.x.

✏️ v4.2.x and v5.x.x of Tauticord ship with built-in tools that will automatically migrate configuration files as needed

⚠️ Unraid users, please see "Migrating on Unraid"

New Configuration File

The schema for the configuration file has been changed to improve readability and logical grouping of settings, make it easier to set up libraries and combined libraries, and allow per-channel customization for each statistic/metric voice channel.

The following is a list of previous configuration variable paths in config.yaml and their corresponding new location in tauticord.yaml:

- Tautulli -> Connection -> URL
+ Tautulli -> URL

- Tautulli -> Connection -> APIKey
+ Tautulli -> APIKey

- Tautulli -> Connection -> UseSelfSignedCert
+ Tautulli -> UseSelfSignedCert

- Tautulli -> Customization -> ServerName
+ Display -> ServerName

- Tautulli -> Customization -> TerminateMessage
+ Tautulli -> TerminateMessage

- Tautulli -> Customization -> RefreshSeconds
+ Tautulli -> RefreshSeconds

- Tautulli -> Customization -> PlexPass
+ <none>

- Tautulli -> Customization -> ServerTimeZone
+ Display -> Time -> ServerTimeZone

(DEPRECATED in v5.12.0)

- Tautulli -> Customization -> Use24HourTime
+ Display -> Time -> Use24HourTime

(DEPRECATED in v5.12.0)

- Tautulli -> Customization -> VoiceChannels -> Stats -> CategoryName
+ Stats -> Activity -> CategoryName

- Tautulli -> Customization -> VoiceChannels -> Stats -> StreamCount
+ Stats -> Activity -> StatTypes -> StreamCount -> Enable

- Tautulli -> Customization -> VoiceChannels -> Stats -> StreamCountChannelID
+ Stats -> Activity -> StatTypes -> StreamCount -> VoiceChannelID

- Tautulli -> Customization -> VoiceChannels -> Stats -> TranscodeCount
+ Stats -> Activity -> StatTypes -> TranscodeCount -> Enable

- Tautulli -> Customization -> VoiceChannels -> Stats -> TranscodeCountChannelID
+ Stats -> Activity -> StatTypes -> TranscodeCount -> VoiceChannelID

- Tautulli -> Customization -> VoiceChannels -> Stats -> Bandwidth
+ Stats -> Activity -> StatTypes -> Bandwidth -> Enable

- Tautulli -> Customization -> VoiceChannels -> Stats -> BandwidthChannelID
+ Stats -> Activity -> StatTypes -> Bandwidth -> VoiceChannelID

- Tautulli -> Customization -> VoiceChannels -> Stats -> LocalBandwidth
+ Stats -> Activity -> StatTypes -> LocalBandwidth -> Enable

- Tautulli -> Customization -> VoiceChannels -> Stats -> LocalBandwidthChannelID
+ Stats -> Activity -> StatTypes -> LocalBandwidth -> VoiceChannelID

- Tautulli -> Customization -> VoiceChannels -> Stats -> RemoteBandwidth
+ Stats -> Activity -> StatTypes -> RemoteBandwidth -> Enable

- Tautulli -> Customization -> VoiceChannels -> Stats -> RemoteBandwidthChannelID
+ Stats -> Activity -> StatTypes -> RemoteBandwidth -> VoiceChannelID

- Tautulli -> Customization -> VoiceChannels -> Stats -> PlexStatus
+ Stats -> Activity -> StatTypes -> PlexServerAvailability -> Enable

- Tautulli -> Customization -> VoiceChannels -> Stats -> PlexStatusChannelID
+ Stats -> Activity -> StatTypes -> PlexServerAvailability -> VoiceChannelID

- Tautulli -> Customization -> VoiceChannels -> Libraries -> CategoryName
+ Stats -> Libraries -> CategoryName

- Tautulli -> Customization -> VoiceChannels -> Libraries -> Enable
+ Stats -> Libraries -> Enable

- Tautulli -> Customization -> VoiceChannels -> Libraries -> LibraryRefreshSeconds
+ Stats -> Libraries -> RefreshSeconds

- Tautulli -> Customization -> VoiceChannels -> Libraries -> LibraryNames

See Libraries configuration

- Tautulli -> Customization -> VoiceChannels -> Libraries -> CombinedLibraries

See Combined Libraries configuration

- Tautulli -> Customization -> VoiceChannels -> Libraries -> UseEmojis

See Voice Channel Customization

- Tautulli -> Customization -> VoiceChannels -> Libraries -> TVSeriesCount

See Libraries configuration

- Tautulli -> Customization -> VoiceChannels -> Libraries -> TVEpisodeCount

See Libraries configuration

- Tautulli -> Customization -> VoiceChannels -> Libraries -> MusicArtistCount

See Libraries configuration

- Tautulli -> Customization -> VoiceChannels -> Libraries -> MusicAlbumCount

See Libraries configuration

- Tautulli -> Customization -> VoiceChannels -> Libraries -> MusicTrackCount

See Libraries Configuration

- Tautulli -> Customization -> VoiceChannels -> Performance -> CategoryName
+ Stats -> Performance -> CategoryName

- Tautulli -> Customization -> Anonymize -> HideUsernames
+ Display -> Anonymize -> HideUsernames

- Tautulli -> Customization -> Anonymize -> HidePlayerNames
+ Display -> Anonymize -> HidePlayerNames

- Tautulli -> Customization -> Anonymize -> HidePlatforms
+ Display -> Anonymize -> HidePlatforms

- Tautulli -> Customization -> Anonymize -> HideQuality
+ Display -> Anonymize -> HideQuality

- Tautulli -> Customization -> Anonymize -> HideBandwidth
+ Display -> Anonymize -> HideBandwidth

- Tautulli -> Customization -> Anonymize -> HideTranscode
+ Display -> Anonymize -> HideTranscode

- Tautulli -> Customization -> Anonymize -> HideProgress
+ Display -> Anonymize -> HideProgress

- Tautulli -> Customization -> Anonymize -> HideETA
+ Display -> Anonymize -> HideETA

- Tautulli -> Customization -> UseFriendlyNames
+ Display -> UseFriendlyNames

- Tautulli -> Customization -> ThousandSeparator
+ Display -> ThousandSeparator

- Discord -> Connection -> BotToken
+ Discord -> BotToken

- Discord -> Connection -> ServerID
+ Discord -> ServerID

- Discord -> Connection -> AdminIDs
+ Discord -> AdminIDs

- Discord -> Connection -> PostSummaryMessage
+ Discord -> PostSummaryMessage

- Discord -> Connection -> ChannelName
+ Discord -> ChannelName

- Discord -> Connection -> EnableSlashCommands
+ Discord -> EnableSlashCommands

- Discord -> Customization -> Nitro
+ <none>

- Extras -> Analytics
+ Extras -> AllowAnalytics

- Extras -> Performance -> TautulliUserCount
+ Stats -> Performance -> Metrics -> UserCount -> Enable

- Extras -> Performance -> DiskSpace
+ Stats -> Performance -> Metrics -> DiskSpace -> Enable

- Extras -> Performance -> CPU
+ Stats -> Performance -> Metrics -> CPU -> Enable

- Extras -> Performance -> Memory
+ Stats -> Performance -> Metrics -> Memory -> Enable

Additional settings have been added to the configuration file. Please refer to the comments in tauticord.yaml.example and the provided configuration schema for more information.

⚠️ Migrating on Unraid

✏️ This process is only needed for Unraid users who are using the Variables to configure Tauticord. If you are already using a config file, you can upgrade as normal.

Starting with v5.0.0, the Unraid Community Application template for Tauticord no longer provides environmental variable (Variable) configuration options. As a result, you will not be able to provide environmental variables to configure Tauticord from the Unraid web UI.

The new template will be pulled in automatically when the Community Applications plugin is updated on your Unraid machine. Unless you manually avoid updating the plugin, the new template will likely be imported into your system.

Unraid users have two options:

• Manually migrate their environmental variables to the tauticord.yaml configuration file
  • Note: Your previously-configured Variables may not be visible in the GUI to reference due to the template change. If so, DO NOT save any changes to your container configuration and exit the GUI.
  • You can attempt to "rescue" the old configuration layout, which should be stored in /boot/config/plugins/dockerMan/templates-user/my-Tauticord.xml on your Unraid machine. Simply view/download the file from your server for referencing.
• Step-increment your Docker container

How to step-increment in Unraid

Step-incrementing the Docker container on Unraid will leverage Tauticord's built-in configuration migration tools, by first migrating existing environmental variables to a config file (v4.x.x) and then converting that config file to the new schema (v5.x.x).

Please follow the following steps:

1. DO NOT open the GUI configuration editor for your Tauticord container. If the Community Applications plugin has updated on your system and the new template has been imported, it could interfere with this step-incrementing process.
2. Delete your existing Tauticord container from the Docker tab in your Unraid web UI (yes, really).
3. Download your existing Tauticord configuration template file (stored at /boot/config/plugins/dockerMan/templates-user/my-Tauticord.xml on your Unraid system) to a separate folder/machine for safe keeping.
4. Copy your existing Tauticord configuration template file (see above) to /boot/config/plugins/dockerMan/templates/tauticord_v4.xml. This folder stores templates separate from those provided by the Community Applications plugin.
5. Edit the Tauticord configuration template (/boot/config/plugins/dockerMan/templates/tauticord_v4.xml) and change:

   - <Repository>nwithan8/tauticord:latest</Repository>
   + <Repository>nwithan8/tauticord:4.2.2</Repository>

6. Open the Docker tab in your Unraid web UI, and click "Add Container" at the bottom of the page.
7. From the "Template" dropdown, select "Tauticord" from the "Default templates" section (not from the "User templates" section). Your previous configuration should populate on the page.
8. Verify that your configuration is correct. Toggle "Advanced View" in the top-right corner of the page and confirm that the "Repository" is "nwithan8/tauticord:4.2.2"
9. Click "Apply" at the bottom of the screen. Tauticord v4.2.2 should now be running on your system.
10. Wait a few minutes for Tauticord to start up and complete the migration process. You can verify this process by clicking on the icon next to the running container and selecting "Logs" from the dropdown. The log file should say Migration 001: Copying environment variables to /config/migration_data/001_env_var_to_config_yaml.yaml followed by normal bot operation.
11. The migration of environmental variables to a configuration file is now complete. Shut down and delete the Tauticord container.
12. Open the Community Applications store in the Unraid web UI and search for "Tauticord". Click "Install".
13. You are now installing/configuring v5.x.x of Tauticord. Notice the lack of Variables to configure. Use the same Config Path, Log Path and Monitor Path settings as before. This is crucial, as the migration files created in the previous steps exist in whatever path was mapped to /config, so /config needs to be mapped to the same path for migration to complete properly.
14. Verify that your configuration is correct. Toggle "Advanced View" in the top-right corner of the page and confirm that the "Repository" is "nwithan8/tauticord:latest"
15. Click "Apply" at the bottom of the screen. Tauticord v5.x.x should now be running on your system.
16. Wait a few minutes for Tauticord to start up and complete the migration process. You can verify this process by clicking on the icon next to the running container and selecting "Logs" from the dropdown. The log file should say Migration 002: Migrating old config to new config schema. The bot (not the Docker container) will restart itself automatically following the migration.
17. Enjoy Tauticord!