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 and Radarr](#lidarr-prowlarr-sonarr-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
  32 If you experiencing any issue, please have a look to the [troubleshooting](troubleshooting.md) page.
  33
  34 ## Common options
  35
  36 ```yaml
  37 - name: "My Service"
  38   logo: "assets/tools/sample.png"
  39   url: "http://my-service-link"
  40   endpoint: "http://my-service-endpoint" # Optional: alternative base URL used to fetch service data is necessary.
  41   useCredentials: false # Optional: Override global proxy.useCredentials configuration.
  42   type: "<type>"
  43 ```
  44
  45 ## PiHole
  46
  47 Using the PiHole service you can display info about your local PiHole instance right on your Homer dashboard.
  48
  49 The following configuration is available for the PiHole service.
  50
  51 ```yaml
  52 - name: "Pi-hole"
  53   logo: "assets/tools/sample.png"
  54   # subtitle: "Network-wide Ad Blocking" # optional, if no subtitle is defined, PiHole statistics will be shown
  55   url: "http://192.168.0.151/admin"
  56   type: "PiHole"
  57 ```
  58
  59 ## OpenWeatherMap
  60
  61 Using the OpenWeatherMap service you can display weather information about a given location.
  62 The following configuration is available for the OpenWeatherMap service:
  63
  64 ```yaml
  65 - name: "Weather"
  66   location: "Amsterdam" # your location.
  67   locationId: "2759794" # Optional: Specify OpenWeatherMap city ID for better accuracy
  68   apikey: "<---insert-api-key-here--->" # insert your own API key here. Request one from https://openweathermap.org/api.
  69   units: "metric" # units to display temperature. Can be one of: metric, imperial, kelvin. Defaults to kelvin.
  70   background: "square" # choose which type of background you want behind the image. Can be one of: square, circle, none. Defaults to none.
  71   type: "OpenWeather"
  72 ```
  73
  74 **Remarks:**
  75 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).
  76
  77 ## Medusa
  78
  79 This service displays News (grey), Warning (orange) or Error (red) notifications bubbles from the Medusa application.
  80 Two lines are needed in the config.yml :
  81
  82 ```yaml
  83   type: "Medusa"
  84   apikey: "01234deb70424befb1f4ef6a23456789"
  85 ```
  86
  87 The url must be the root url of Medusa application.
  88 The Medusa API key can be found in General configuration > Interface. It is needed to access Medusa API.
  89
  90 ## Lidarr, Prowlarr, Sonarr and Radarr
  91
  92 This service displays Activity (blue), Warning (orange) or Error (red) notifications bubbles from the Lidarr, Radarr or Sonarr application.
  93 Two lines are needed in the config.yml :
  94
  95 ```yaml
  96   type: "Lidarr", "Prowlarr", "Radarr" or "Sonarr"
  97   apikey: "01234deb70424befb1f4ef6a23456789"
  98 ```
  99
 100 The url must be the root url of Lidarr, Prowlarr, Radarr or Sonarr application.
 101 The Lidarr, Prowlarr, Radarr or Sonarr API key can be found in Settings > General. It is needed to access the API.
 102 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:
 103
 104 ```yaml
 105 - name: "Radarr"
 106   type: "Radarr"
 107   url: "http://localhost:7878/"
 108   apikey: "MY-SUPER-SECRET-API-KEY"
 109   target: "_blank"
 110   legacyApi: true
 111 ```
 112
 113 ## PaperlessNG
 114
 115 This service displays total number of documents stored. Two lines are required:
 116
 117 ```yaml
 118   type: "PaperlessNG"
 119   apikey: "0123456789abcdef123456789abcdef"
 120 ```
 121
 122 API key can be generated in Settings > Administration > Auth Tokens
 123
 124 ## Ping
 125
 126 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.
 127
 128 ```yaml
 129 - name: "Awesome app"
 130   type: Ping
 131   logo: "assets/tools/sample.png"
 132   subtitle: "Bookmark example"
 133   tag: "app"
 134   url: "https://www.reddit.com/r/selfhosted/"
 135   method: "head"
 136 ```
 137
 138 ## Prometheus
 139
 140 For Prometheus you need to set the type to Prometheus and provide a url.
 141
 142 ```yaml
 143 - name: "Prometheus"
 144   type: Prometheus
 145   logo: "assets/tools/sample.png"
 146   url: "http://192.168.0.151/"
 147   # subtitle: "Monitor data server"
 148 ```
 149
 150 ## AdGuard Home
 151 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.
 152
 153 ```yaml
 154 - name: "Adguard"
 155   logo: "assets/tools/adguardhome.png"
 156   url: "https://adguard.exemple.com"
 157   target: "_blank"
 158   type: "AdGuardHome"
 159 ```
 160
 161 ## Portainer
 162
 163 This service displays info about the total number of containers managed by your Portainer instance.
 164 In order to use it, you must be using Portainer version 1.11 or later. Generate an access token from the UI and pass
 165 it to the apikey field.
 166 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.
 167
 168 See https://docs.portainer.io/v/ce-2.11/user/account-settings#access-tokens
 169
 170 ```yaml
 171 - name: "Portainer"
 172   logo: "assets/tools/sample.png"
 173   url: "http://192.168.0.151/"
 174   type: "Portainer"
 175   apikey: "MY-SUPER-SECRET-API-KEY"
 176   # environments:
 177   #   - "raspberry"
 178   #   - "local"
 179 ```
 180
 181 ## Emby / Jellyfin
 182
 183 You need to set the type to Emby, provide an api key and choose which stats to show if the subtitle is disabled.
 184
 185 ```yaml
 186 - name: "Emby"
 187   logo: "assets/tools/sample.png"
 188   url: "http://192.168.0.151/"
 189   type: "Emby"
 190   apikey: "MY-SUPER-SECRET-API-KEY"
 191   libraryType: "music" #Choose which stats to show. Can be one of: music, series or movies.
 192 ```
 193
 194 ## Uptime Kuma
 195
 196 Using the Uptime Kuma service you can display info about your instance uptime right on your Homer dashboard.
 197
 198 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).
 199
 200 ```yaml
 201 - name: "Uptime Kuma"
 202   logo: "assets/tools/sample.png"
 203   # subtitle: "A fancy self-hosted monitoring tool" # optional, if no subtitle is defined, Uptime Kuma incidents, if any, will be shown
 204   url: "http://192.168.0.151:3001"
 205   slug: "myCustomDashboard" # Defaults to "default" if not provided.
 206   type: "UptimeKuma"
 207 ```
 208
 209 ## Tautulli
 210
 211 The Tautulli service can allow you to show the number of currently active
 212 streams on you Plex instance. An API key is required, and can be obtained from
 213 the "Web Interface" section of settings on the Tautulli web UI.
 214
 215 ```yaml
 216 - name: "Tautulli"
 217   logo: "assets/tools/sample.png"
 218   url: "http://192.168.0.151:8181"
 219   type: "Tautulli"
 220   apikey: "MY-SUPER-SECRET-API-KEY"
 221 ```
 222
 223 Because the service type and link don't necessarily have to match, you could
 224 even make the service type Tautulli on your Plex card and provide a separate
 225 endpoint pointing to Tautulli!
 226
 227 ```yaml
 228 - name: "Plex"
 229   logo: "assets/tools/sample.png"
 230   url: "http://192.168.0.151:32400/web" # Plex
 231   endpoint: "http://192.168.0.151:8181" # Tautulli
 232   type: "Tautulli"
 233   apikey: "MY-SUPER-SECRET-API-KEY"
 234 ```
 235
 236 ## Mealie
 237
 238 First off make sure to remove an existing `subtitle` as it will take precedence if set.
 239 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.
 240
 241 ## Healthchecks
 242
 243 This service displays information about the configured status checks from the Healthchecks application.
 244 Two lines are needed in the config.yml :
 245
 246 ```yaml
 247   type: "Healthchecks"
 248   apikey: "01234deb70424befb1f4ef6a23456789"
 249 ```
 250
 251 The url must be the root url of the Healthchecks application.
 252 The Healthchecks API key can be found in Settings > API Access > API key (read-only). The key is needed to access Healthchecks API.
 253
 254 ## rTorrent
 255
 256 This service displays the global upload and download rates, as well as the number of torrents
 257 listed in rTorrent. The service communicates with the rTorrent XML-RPC interface which needs
 258 to be accessible from the browser. Please consult
 259 [the instructions](https://github.com/rakshasa/rtorrent-doc/blob/master/RPC-Setup-XMLRPC.md)
 260 for setting up rTorrent and make sure the correct CORS-settings are applied. Examples for various
 261 servers can be found at https://enable-cors.org/server.html.
 262
 263 ```yaml
 264 - name: "rTorrent"
 265   logo: "assets/tools/sample.png"
 266   url: "http://192.168.0.151" # Your rTorrent web UI, f.e. ruTorrent or Flood.
 267   xmlrpc: "http://192.168.0.151:8081" # Reverse proxy for rTorrent's XML-RPC.
 268   type: "Rtorrent"
 269   rateInterval: 5000 # Interval for updating the download and upload rates.
 270   torrentInterval: 60000 # Interval for updating the torrent count.
 271   username: "username" # Username for logging into rTorrent (if applicable).
 272   password: "password" # Password for logging into rTorrent (if applicable).
 273
 274
 275 ## Proxmox
 276
 277 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).
 278
 279 The API Token (or the user asigned to that token if not separated permissions is checked) are this:
 280
 281 | Path               | Permission | Comments                                                          |
 282 |--------------------|------------|-------------------------------------------------------------------|
 283 | /nodes/<your-node> | Sys.Audit  |                                                                   |
 284 | /vms/<id-vm>       | VM.Audit   | You need to have this permission on any VM you want to be counted |
 285
 286 It is highly recommended that you create and API Token with only these permissions on a read-only mode.
 287
 288 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.
 289
 290 Configuration example:
 291
 292 ```yaml
 293 - name: "Proxmox - Node"
 294   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"
 295   type: "Proxmox"
 296   url: "https://your.proxmox.server"
 297   node: "your-node-name"
 298   warning_value: 50
 299   danger_value: 80
 300   api_token: "PVEAPIToken=root@pam!your-api-token-name=your-api-token-key"
 301 ```
 302
 303 ## qBittorrent
 304
 305 This service displays the global upload and download rates, as well as the number of torrents
 306 listed. The service communicates with the qBittorrent API interface which needs
 307 to be accessible from the browser. Please consult
 308 [the instructions](https://github.com/qbittorrent/qBittorrent/pull/12579)
 309 for setting up qBittorrent and make sure the correct CORS-settings are applied. Examples for various
 310 servers can be found at [enable-cors.org](https://enable-cors.org/server.html).
 311
 312 ```yaml
 313 - name: "qBittorrent"
 314   logo: "assets/tools/sample.png"
 315   url: "http://192.168.1.2:8080" # Your rTorrent web UI, f.e. ruTorrent or Flood.
 316   type: "qBittorrent"
 317   rateInterval: 2000 # Interval for updating the download and upload rates.
 318   torrentInterval: 5000 # Interval for updating the torrent count.
 319   target: "_blank" # optional html a tag target attribute
 320 ```
 321
 322 ## Copy to Clipboard
 323
 324 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.
 325
 326 You can still provide an `url` that would be open when clicked anywhere but on the icon button.
 327
 328 Configuration example:
 329
 330 ```yaml
 331 - name: "Copy me!"
 332   logo: "assets/tools/sample.png"
 333   subtitle: "Subtitle text goes here"
 334   url: "#"
 335   type: "CopyToClipboard"
 336   clipboard: "this text will be copied to your clipboard"
 337 ```