docs/customservices.md

   1 # Custom Services
   2
   3 Some service can use a specific a component that provides some extra features by adding a `type` key to the service yaml
   4 configuration and, where applicable, an apikey. Note that config.yml is exposed at /assets/config.yml via HTTP and any
   5 apikey included in the configuration file is exposed to anyone who can access the homer instance. Only include an apikey
   6 if your homer instance is secured behind some form of authentication or access restriction.
   7
   8 Available services are in `src/components/`. Here is an overview of all custom services that are available
   9 within Homer:
  10
  11 - [Custom Services](#custom-services)
  12   - [Common options](#common-options)
  13   - [PiHole](#pihole)
  14   - [OpenWeatherMap](#openweathermap)
  15   - [Medusa](#medusa)
  16   - [Lidarr, Prowlarr, Sonarr, Readarr and Radarr](#lidarr-prowlarr-sonarr-readarr-and-radarr)
  17   - [PaperlessNG](#paperlessng)
  18   - [Ping](#ping)
  19   - [Prometheus](#prometheus)
  20   - [AdGuard Home](#adguard-home)
  21   - [Portainer](#portainer)
  22   - [Emby / Jellyfin](#emby--jellyfin)
  23   - [Uptime Kuma](#uptime-kuma)
  24   - [Tautulli](#tautulli)
  25   - [Mealie](#mealie)
  26   - [Healthchecks](#healthchecks)
  27   - [Proxmox](#proxmox)
  28   - [rTorrent](#rtorrent)
  29   - [qBittorrent](#qbittorrent)
  30   - [CopyToClipboard](#copy-to-clipboard)
  31   - [Speedtest Tracker](#SpeedtestTracker)
  32   - [What's Up Docker](#whats-up-docker)
  33   - [SABnzbd](#sabnzbd)
  34   - [OctoPrint](#octoprint)
  35   - [Tdarr](#tdarr)
  36   - [PiAlert](#pialert)
  37   - [Immich](#immich)
  38   - [OpenHAB](#openhab)
  39
  40 If you experiencing any issue, please have a look to the [troubleshooting](troubleshooting.md) page.
  41
  42 ## Common options
  43
  44 ```yaml
  45 - name: "My Service"
  46   logo: "assets/tools/sample.png"
  47   url: "http://my-service-link"
  48   endpoint: "http://my-service-endpoint" # Optional: alternative base URL used to fetch service data is necessary.
  49   useCredentials: false # Optional: Override global proxy.useCredentials configuration.
  50   type: "<type>"
  51 ```
  52
  53 ## PiHole
  54
  55 Using the PiHole service you can display info about your local PiHole instance right on your Homer dashboard.
  56
  57 The following configuration is available for the PiHole service.
  58
  59 ```yaml
  60 - name: "Pi-hole"
  61   logo: "assets/tools/sample.png"
  62   # subtitle: "Network-wide Ad Blocking" # optional, if no subtitle is defined, PiHole statistics will be shown
  63   url: "http://192.168.0.151/admin"
  64   apikey: "<---insert-api-key-here--->" # optional, needed if web interface is password protected
  65   type: "PiHole"
  66 ```
  67
  68 **Remarks:**
  69 If PiHole web interface is password protected, obtain the `apikey` from Settings > API/Web interface > Show API token.
  70
  71 ## OpenWeatherMap
  72
  73 Using the OpenWeatherMap service you can display weather information about a given location.
  74 The following configuration is available for the OpenWeatherMap service:
  75
  76 ```yaml
  77 - name: "Weather"
  78   location: "Amsterdam" # your location.
  79   locationId: "2759794" # Optional: Specify OpenWeatherMap city ID for better accuracy
  80   apikey: "<---insert-api-key-here--->" # insert your own API key here. Request one from https://openweathermap.org/api.
  81   units: "metric" # units to display temperature. Can be one of: metric, imperial, kelvin. Defaults to kelvin.
  82   background: "square" # choose which type of background you want behind the image. Can be one of: square, circle, none. Defaults to none.
  83   type: "OpenWeather"
  84 ```
  85
  86 **Remarks:**
  87 If for some reason your city can't be found by entering the name in the `location` property, you could also try to configure the OWM city ID in the `locationId` property. To retrieve your specific City ID, go to the [OWM website](https://openweathermap.org), search for your city and retrieve the ID from the URL (for example, the City ID of Amsterdam is 2759794).
  88
  89 ## Medusa
  90
  91 This service displays News (grey), Warning (orange) or Error (red) notifications bubbles from the Medusa application.
  92 Two lines are needed in the config.yml :
  93
  94 ```yaml
  95   type: "Medusa"
  96   apikey: "<---insert-api-key-here--->"
  97 ```
  98
  99 The url must be the root url of Medusa application.
 100 The Medusa API key can be found in General configuration > Interface. It is needed to access Medusa API.
 101
 102 ## Lidarr, Prowlarr, Sonarr, Readarr and Radarr
 103
 104 This service displays Activity (blue), Warning (orange) or Error (red) notifications bubbles from the Lidarr, Readarr, Radarr or Sonarr application.
 105 Readarr display also a Missing (purple) notification bubbles.
 106 Two lines are needed in the config.yml :
 107
 108 ```yaml
 109   type: "Lidarr", "Prowlarr", "Radarr" or "Sonarr"
 110   apikey: "<---insert-api-key-here--->"
 111 ```
 112
 113 The url must be the root url of Lidarr, Prowlarr, Readarr, Radarr or Sonarr application.
 114 The Lidarr, Prowlarr, Readarr, Radarr or Sonarr API key can be found in Settings > General. It is needed to access the API.
 115 If you are using an older version of Radarr or Sonarr which don't support the new V3 api endpoints, add the following line to your service config "legacyApi: true", example:
 116
 117 ```yaml
 118 - name: "Radarr"
 119   type: "Radarr"
 120   url: "http://localhost:7878/"
 121   apikey: "<---insert-api-key-here--->"
 122   target: "_blank"
 123   legacyApi: true
 124 ```
 125
 126 ## PaperlessNG
 127
 128 This service displays total number of documents stored. Two lines are required:
 129
 130 ```yaml
 131   type: "PaperlessNG"
 132   apikey: "<---insert-api-key-here--->"
 133 ```
 134
 135 API key can be generated in Settings > Administration > Auth Tokens
 136
 137 ## Ping
 138
 139 For Ping you need to set the type to Ping and provide a url. By default the HEAD method is used but it can be configured to use GET using the optional `method` property.
 140
 141 ```yaml
 142 - name: "Awesome app"
 143   type: Ping
 144   logo: "assets/tools/sample.png"
 145   subtitle: "Bookmark example"
 146   tag: "app"
 147   url: "https://www.reddit.com/r/selfhosted/"
 148   method: "head"
 149 ```
 150
 151 ## Prometheus
 152
 153 For Prometheus you need to set the type to Prometheus and provide a url.
 154
 155 ```yaml
 156 - name: "Prometheus"
 157   type: Prometheus
 158   logo: "assets/tools/sample.png"
 159   url: "http://192.168.0.151/"
 160   # subtitle: "Monitor data server"
 161 ```
 162
 163 ## AdGuard Home
 164 For AdGuard Home you need to set the type to AdGuard, if you have somes issues as 403 responses on requests you need to provide authentification in headers for locations needed as below.
 165
 166 ```yaml
 167 - name: "Adguard"
 168   logo: "assets/tools/adguardhome.png"
 169   url: "https://adguard.exemple.com"
 170   target: "_blank"
 171   type: "AdGuardHome"
 172 ```
 173
 174 ## Portainer
 175
 176 This service displays info about the total number of containers managed by your Portainer instance.
 177 In order to use it, you must be using Portainer version 1.11 or later. Generate an access token from the UI and pass
 178 it to the apikey field.
 179 By default, every connected environments will be checked. To select specific ones, add an "environments" entry which can be a simple string or an array containing all the selected environments name.
 180
 181 See https://docs.portainer.io/api/access#creating-an-access-token
 182
 183 ```yaml
 184 - name: "Portainer"
 185   logo: "assets/tools/sample.png"
 186   url: "http://192.168.0.151/"
 187   type: "Portainer"
 188   apikey: "<---insert-api-key-here--->"
 189   # environments:
 190   #   - "raspberry"
 191   #   - "local"
 192 ```
 193
 194 ## Emby / Jellyfin
 195
 196 You need to set the type to Emby, provide an api key and choose which stats to show if the subtitle is disabled.
 197
 198 ```yaml
 199 - name: "Emby"
 200   logo: "assets/tools/sample.png"
 201   url: "http://192.168.0.151/"
 202   type: "Emby"
 203   apikey: "<---insert-api-key-here--->"
 204   libraryType: "music" #Choose which stats to show. Can be one of: music, series or movies.
 205 ```
 206
 207 ## Uptime Kuma
 208
 209 Using the Uptime Kuma service you can display info about your instance uptime right on your Homer dashboard.
 210
 211 The following configuration is available for the UptimeKuma service. Needs v1.13.1 or later because of the change in APIs due to [multiple status pages support](https://github.com/louislam/uptime-kuma/releases/tag/1.13.1).
 212
 213 ```yaml
 214 - name: "Uptime Kuma"
 215   logo: "assets/tools/sample.png"
 216   # subtitle: "A fancy self-hosted monitoring tool" # optional, if no subtitle is defined, Uptime Kuma incidents, if any, will be shown
 217   url: "http://192.168.0.151:3001"
 218   slug: "myCustomDashboard" # Defaults to "default" if not provided.
 219   type: "UptimeKuma"
 220 ```
 221
 222 ## Tautulli
 223
 224 The Tautulli service can allow you to show the number of currently active
 225 streams on you Plex instance. An API key is required, and can be obtained from
 226 the "Web Interface" section of settings on the Tautulli web UI.
 227
 228 ```yaml
 229 - name: "Tautulli"
 230   logo: "assets/tools/sample.png"
 231   url: "http://192.168.0.151:8181"
 232   type: "Tautulli"
 233   apikey: "<---insert-api-key-here--->"
 234 ```
 235
 236 Because the service type and link don't necessarily have to match, you could
 237 even make the service type Tautulli on your Plex card and provide a separate
 238 endpoint pointing to Tautulli!
 239
 240 ```yaml
 241 - name: "Plex"
 242   logo: "assets/tools/sample.png"
 243   url: "http://192.168.0.151:32400/web" # Plex
 244   endpoint: "http://192.168.0.151:8181" # Tautulli
 245   type: "Tautulli"
 246   apikey: "<---insert-api-key-here--->"
 247 ```
 248
 249 ## Mealie
 250
 251 First off make sure to remove an existing `subtitle` as it will take precedence if set.
 252 Setting `type: "Mealie"` will then show the number of recipes Mealie is keeping organized or the planned meal for today if one is planned. You will have to set an API key in the field `apikey` which can be created in your Mealie installation.
 253
 254 ## Healthchecks
 255
 256 This service displays information about the configured status checks from the Healthchecks application.
 257 Two lines are needed in the config.yml :
 258
 259 ```yaml
 260   type: "Healthchecks"
 261   apikey: "<---insert-api-key-here--->"
 262 ```
 263
 264 The url must be the root url of the Healthchecks application.
 265 The Healthchecks API key can be found in Settings > API Access > API key (read-only). The key is needed to access Healthchecks API.
 266
 267 ## rTorrent
 268
 269 This service displays the global upload and download rates, as well as the number of torrents
 270 listed in rTorrent. The service communicates with the rTorrent XML-RPC interface which needs
 271 to be accessible from the browser. Please consult
 272 [the instructions](https://github.com/rakshasa/rtorrent-doc/blob/master/RPC-Setup-XMLRPC.md)
 273 for setting up rTorrent and make sure the correct CORS-settings are applied. Examples for various
 274 servers can be found at https://enable-cors.org/server.html.
 275
 276 ```yaml
 277 - name: "rTorrent"
 278   logo: "assets/tools/sample.png"
 279   url: "http://192.168.0.151" # Your rTorrent web UI, f.e. ruTorrent or Flood.
 280   xmlrpc: "http://192.168.0.151:8081" # Reverse proxy for rTorrent's XML-RPC.
 281   type: "Rtorrent"
 282   rateInterval: 5000 # Interval for updating the download and upload rates.
 283   torrentInterval: 60000 # Interval for updating the torrent count.
 284   username: "username" # Username for logging into rTorrent (if applicable).
 285   password: "password" # Password for logging into rTorrent (if applicable).
 286 ```
 287
 288
 289 ## Proxmox
 290
 291 This service displays status information of a Proxmox node (VMs running and disk, memory and cpu used). It uses the proxmox API and [API Tokens](https://pve.proxmox.com/pve-docs/pveum-plain.html) for authorization so you need to generate one to set in the yaml config. You can set it up in Proxmox under Permissions > API Tokens. You also need to know the realm the user of the API Token is assigned to (by default pam).
 292
 293 The API Token (or the user asigned to that token if not separated permissions is checked) are this:
 294
 295 | Path               | Permission | Comments                                                          |
 296 |--------------------|------------|-------------------------------------------------------------------|
 297 | /nodes/<your-node> | Sys.Audit  |                                                                   |
 298 | /vms/<id-vm>       | VM.Audit   | You need to have this permission on any VM you want to be counted |
 299
 300 It is highly recommended that you create and API Token with only these permissions on a read-only mode.
 301
 302 If you get errors, they will be shown on browser's dev console. Main issues tend to be CORS related as Proxmox does not include CORS headers and you have to deploy it behind a reverse proxy and make the proxy add this headers.
 303
 304 Configuration example:
 305
 306 ```yaml
 307 - name: "Proxmox - Node"
 308   logo: "https://www.google.com/url?sa=i&url=https%3A%2F%2Fgithub.com%2FandOTP%2FandOTP%2Fissues%2F337&psig=AOvVaw2YKVuEUIBeTUikr7kAjm8D&ust=1665323538747000&source=images&cd=vfe&ved=0CAkQjRxqFwoTCPCTruLj0PoCFQAAAAAdAAAAABAN"
 309   type: "Proxmox"
 310   url: "https://your.proxmox.server"
 311   node: "your-node-name"
 312   warning_value: 50
 313   danger_value: 80
 314   api_token: "PVEAPIToken=root@pam!your-api-token-name=your-api-token-key"
 315   # values below this line are optional (default value are false/empty):
 316   hide_decimals: true # removes decimals from stats values.
 317   hide: [] # hides information. Possible values are "vms", "vms_total", "lxcs", "lxcs_total", "disk", "mem" and "cpu".
 318   small_font_on_small_screens: true # uses small font on small screens (like mobile)
 319   small_font_on_desktop: true # uses small font on desktops (just in case you're showing much info)
 320 ```
 321
 322 ## qBittorrent
 323
 324 This service displays the global upload and download rates, as well as the number of torrents
 325 listed. The service communicates with the qBittorrent API interface which needs
 326 to be accessible from the browser. Please consult
 327 [the instructions](https://github.com/qbittorrent/qBittorrent/pull/12579)
 328 for setting up qBittorrent and make sure the correct CORS-settings are applied. Examples for various
 329 servers can be found at [enable-cors.org](https://enable-cors.org/server.html).
 330
 331 ```yaml
 332 - name: "qBittorrent"
 333   logo: "assets/tools/sample.png"
 334   url: "http://192.168.1.2:8080" # Your rTorrent web UI, f.e. ruTorrent or Flood.
 335   type: "qBittorrent"
 336   rateInterval: 2000 # Interval for updating the download and upload rates.
 337   torrentInterval: 5000 # Interval for updating the torrent count.
 338   target: "_blank" # optional html a tag target attribute
 339 ```
 340
 341 ## Copy to Clipboard
 342
 343 This service displays the same information of a generic one, but shows an icon button on the indicator place (right side) you can click to get the content of the `clipboard` field copied to your clipboard.
 344
 345 You can still provide an `url` that would be open when clicked anywhere but on the icon button.
 346
 347 Configuration example:
 348
 349 ```yaml
 350 - name: "Copy me!"
 351   logo: "assets/tools/sample.png"
 352   subtitle: "Subtitle text goes here"
 353   url: "#"
 354   type: "CopyToClipboard"
 355   clipboard: "this text will be copied to your clipboard"
 356 ```
 357
 358 ## SpeedtestTracker
 359
 360 This service will show the download and upload speeds in Mbit/s and the ping in ms.
 361 To configure the service, you need to define the url of SpeedtestTracker running and an entry with type `SpeedtestTracker`.
 362
 363 Configuration example:
 364
 365 ```yaml
 366 - name: "Speedtest Tracker"
 367   type: "SpeedtestTracker"
 368   url: "http://192.168.0.1:8080"
 369   target: "_blank"
 370 ```
 371
 372 ## What's up Docker
 373
 374 What's up Docker allow to display info about the number of container running and the number for which an update is available on your Homer dashboard.
 375
 376 The following configuration is available for the WUD service.
 377
 378 ```yaml
 379 - name: "What's Up Docker"
 380   logo: "assets/tools/sample.png"
 381   subtitle: "Docker image update notifier"
 382   url: "http://192.168.1.12:3001"
 383   type: "WUD"
 384 ```
 385
 386 ## SABnzbd
 387
 388 The SABnzbd service can allow you to show the number of currently active
 389 downloads on your SABnzbd instance. An API key is required, and can be obtained from
 390 the "Config" > "General" section of the SABnzbd config in the SABnzbd web UI.
 391
 392 ```yaml
 393 - name: "SABnzbd"
 394   logo: "assets/tools/sample.png"
 395   url: "http://192.168.0.151:8080"
 396   type: "SABnzbd"
 397   apikey: "MY-SUPER-SECRET-API-KEY"
 398   downloadInterval: 5000 # (Optional) Interval (in ms) for updating the download count
 399 ```
 400
 401 ## OctoPrint/Moonraker
 402
 403 The OctoPrint/Moonraker service only needs an `apikey` & `endpoint` and optionally a `display` or `url` option. `url` can be used when you click on the service it will launch the `url`
 404
 405 Moonraker's API mimmicks a few of OctoPrint's endpoints which makes these services compatible. See https://moonraker.readthedocs.io/en/latest/web_api/#octoprint-api-emulation for details.
 406
 407 ```yaml
 408 - name: "Octoprint"
 409   logo: "https://cdn-icons-png.flaticon.com/512/3112/3112529.png"
 410   apikey: "xxxxxxxxxxxx" # insert your own API key here.
 411   endpoint: "http://192.168.0.151:8080"
 412   display: "text" # 'text' or 'bar'. Default to `text`.
 413   type: "OctoPrint"
 414 ```
 415
 416 ## Tdarr
 417
 418 The Tdarr service can allow you to show the number of currently queued items
 419 for transcoding on your Tdarr instance as well as the number of errored items.
 420
 421 ```yaml
 422 - name: "Tdarr"
 423   logo: "assets/tools/sample.png"
 424   url: "http://192.168.0.151:8265"
 425   type: "Tdarr"
 426   checkInterval: 5000 # (Optional) Interval (in ms) for updating the queue & error counts
 427 ```
 428
 429 ## PiAlert
 430
 431 The PiAlert service displays stats from your PiAlert server.
 432
 433 ```yaml
 434 - name: "PiAlert"
 435   type: "PiAlert"
 436   updateInterval: 5000 # (Optional) Interval (in ms) for updating the stats
 437 ```
 438
 439 ## Immich
 440
 441 The Immich service displays stats from your Immich server.
 442 The Immich server must be running at least version 1.85.0 for the correct api endpoint to work.
 443
 444 ```yaml
 445 - name: "Immich"
 446   type: "Immich"
 447   apikey: "<--- Your api key --->" # administrator user
 448   updateInterval: 5000 # (Optional) Interval (in ms) for updating the stats
 449 ```
 450
 451 ## OpenHAB
 452
 453 You need to set the type to OpenHAB, provide an api key and enable cors on OpenHAB.
 454
 455 ```yaml
 456 - name: "OpenHAB"
 457   logo: "assets/tools/sample.png"
 458   url: "http://192.168.0.151/"
 459   type: "OpenHAB"
 460   apikey: "<---insert-api-key-here--->"
 461   things: true # true will query the things API and report total and online things count. false will skip the call
 462   items: true # true will query the items API and report total items count. false will skip the call
 463 ```
 464 To create an API token on OpenHAB, follow the [official documentation here](https://www.openhab.org/docs/configuration/apitokens.html).
 465 To enable cors on OpenHAB, edit your services/runtime.cfg and uncomment or add this line: `org.openhab.cors:enable=true`