add mkdocs

docs/widgets/index.md

@@ -0,0 +1,35 @@
+---
+title: Widgets
+description: Homepage info and status widgets.
+---
+
+Homepage has two types of widgets: info and service. Below we'll cover each type and how to configure them.
+
+## Service Widgets
+
+Service widgets are used to display the status of a service, often a web service or API. Services (and their widgets) are defined in your `services.yml` file. Here's an example:
+
+```yaml
+- Plex:
+    icon: plex.png
+    href: https://plex.my.host
+    description: Watch movies and TV shows.
+    server: localhost
+    container: plex
+    widget:
+      type: tautulli
+      url: http://172.16.1.1:8181
+      key: aabbccddeeffgghhiijjkkllmmnnoo
+```
+
+## Info Widgets
+
+Info widgets are used to display information in the header, often about your system or environment. Info widgets are defined your `widgets.yml` file. Here's an example:
+
+```yaml
+- openmeteo:
+    label: Current
+    latitude: 36.66
+    longitude: -117.51
+    cache: 5
+```

docs/widgets/info/datetime.md

@@ -0,0 +1,51 @@
+---
+title: Date & Time
+description: Date & Time Information Widget Configuration
+---
+
+This allows you to display the date and/or time, can be heavily configured using [Intl.DateTimeFormat](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat/DateTimeFormat).
+
+Formatting is locale aware and will present your date in the regional format you expect, for example, `9/16/22, 3:03 PM` for locale `en` and `16.09.22, 15:03` for `de`. You can also specify a locale just for the datetime widget with the `locale` option (see below).
+
+```yaml
+- datetime:
+      text_size: xl
+      format:
+          timeStyle: short
+```
+
+Any options passed to `format` are passed directly to [Intl.DateTimeFormat](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat/DateTimeFormat), please reference the MDN documentation for all available options.
+
+Valid text sizes are `4xl`, `3xl`, `2xl`, `xl`, `md`, `sm`, `xs`.
+
+A few examples,
+
+```yaml
+# 13:37
+format:
+    timeStyle: short
+    hourCycle: h23
+```
+
+```yaml
+# 1:37 PM
+format:
+    timeStyle: short
+    hour12: true
+```
+
+```yaml
+# 1/23/22, 1:37 PM
+format:
+    dateStyle: short
+    timeStyle: short
+    hour12: true
+```
+
+```yaml
+# 4 januari 2023 om 13:51:25 PST
+locale: nl
+format:
+    dateStyle: long
+    timeStyle: long
+```

docs/widgets/info/glances.md

@@ -0,0 +1,33 @@
+---
+title: Glances
+description: Glances Information Widget Configuration
+---
+
+_(Find the Glances service widget [here](../services/glances.md))_
+
+The Glances widget allows you to monitor the resources (CPU, memory, storage, temp & uptime) of host or another machine, and is designed to match the `resources` info widget. You can have multiple instances by adding another configuration block. The `cputemp`, `uptime` & `disk` states require separate API calls and thus are not enabled by default. Glances needs to be running in "web server" mode to enable the API, see the [glances docs](https://glances.readthedocs.io/en/latest/quickstart.html#web-server-mode).
+
+```yaml
+- glances:
+      url: http://host.or.ip:port
+      username: user # optional if auth enabled in Glances
+      password: pass # optional if auth enabled in Glances
+      cpu: true # optional, enabled by default, disable by setting to false
+      mem: true # optional, enabled by default, disable by setting to false
+      cputemp: true # disabled by default
+      uptime: true # disabled by default
+      disk: / # disabled by default, use mount point of disk(s) in glances. Can also be a list (see below)
+      expanded: true # show the expanded view
+      label: MyMachine # optional
+```
+
+Multiple disks can be specified as:
+
+```yaml
+disk:
+  - /
+  - /boot
+  ...
+```
+
+_Added in v0.4.18, updated in v0.6.11, v0.6.21_

docs/widgets/info/greeting.md

@@ -0,0 +1,14 @@
+---
+title: Greeting
+description: Greeting Information Widget Configuration
+---
+
+This allows you to display simple text, can be configured like so:
+
+```yaml
+- greeting:
+      text_size: xl
+      text: Greeting Text
+```
+
+Valid text sizes are `4xl`, `3xl`, `2xl`, `xl`, `md`, `sm`, `xs`.

docs/widgets/info/index.md

@@ -0,0 +1,4 @@
+---
+title: Info Widgets
+description: Homepage info widgets.
+---

docs/widgets/info/kubernetes.md

@@ -0,0 +1,31 @@
+---
+title: Kubernetes
+description: Kubernetes Information Widget Configuration
+---
+
+This is very similar to the Resources widget, but provides resource information about a Kubernetes cluster.
+
+It provides CPU and Memory usage, by node and/or at the cluster level.
+
+```yaml
+- kubernetes:
+      cluster:
+          # Shows cluster-wide statistics
+          show: true
+          # Shows the aggregate CPU stats
+          cpu: true
+          # Shows the aggregate memory stats
+          memory: true
+          # Shows a custom label
+          showLabel: true
+          label: "cluster"
+      nodes:
+          # Shows node-specific statistics
+          show: true
+          # Shows the CPU for each node
+          cpu: true
+          # Shows the memory for each node
+          memory: true
+          # Shows the label, which is always the node name
+          showLabel: true
+```

docs/widgets/info/logo.md

@@ -0,0 +1,13 @@
+---
+title: Logo
+description: Logo Information Widget Configuration
+---
+
+This allows you to display the homepage logo, you can optionally specify your own icon using similar options as other icons, see [service icons](../../configs/services.md#icons).
+
+```yaml
+- logo:
+    icon: https://upload.wikimedia.org/wikipedia/commons/thumb/d/d5/I_Love_New_York.svg/1101px-I_Love_New_York.svg.png # optional
+```
+
+_Added in v0.4.18, updated in 0.X.X_

docs/widgets/info/longhorn.md

@@ -0,0 +1,29 @@
+---
+title: Longhorn
+description: Longhorn Storage Widget Configuration
+---
+
+The Longhorn widget pulls storage utilization metrics from the Longhorn storage driver on Kubernetes.
+It is designed to appear similar to the Resource widget's disk representation.
+
+The exact metrics should be very similar to what is seen on the Longhorn dashboard itself.
+
+It can show the aggregate metrics and/or the individual node metrics.
+
+```yaml
+- longhorn:
+      # Show the expanded view
+      expanded: true
+      # Shows a node representing the aggregate values
+      total: true
+      # Shows the node names as labels
+      labels: true
+      # Show the nodes
+      nodes: true
+      # An explicit list of nodes to show. All are shown by default if "nodes" is true
+      include:
+          - node1
+          - node2
+```
+
+The Longhorn URL and credentials are stored in the `providers` section of the `settings.yaml`.

docs/widgets/info/openmeteo.md

@@ -0,0 +1,18 @@
+---
+title: Open-Meteo
+description: Open-Meteo Information Widget Configuration
+---
+
+No registration is required at all! See [https://open-meteo.com/en/docs](https://open-meteo.com/en/docs)
+
+```yaml
+- openmeteo:
+      label: Kyiv # optional
+      latitude: 50.449684
+      longitude: 30.525026
+      timezone: Europe/Kiev # optional
+      units: metric # or imperial
+      cache: 5 # Time in minutes to cache API responses, to stay within limits
+```
+
+You can optionally not pass a `latitude` and `longitude` and the widget will use your current location (requires a secure context, eg. HTTPS).

docs/widgets/info/openweathermap.md

@@ -0,0 +1,19 @@
+---
+title: OpenWeatherMap
+description: OpenWeatherMap Information Widget Configuration
+---
+
+The free tier "One Call API" is all thats required, you will need to [subscribe](https://home.openweathermap.org/subscriptions/unauth_subscribe/onecall_30/base) and grab your API key.
+
+```yaml
+- openweathermap:
+      label: Kyiv #optional
+      latitude: 50.449684
+      longitude: 30.525026
+      units: metric # or imperial
+      provider: openweathermap
+      apiKey: youropenweathermapkey # required only if not using provider, this reveals api key in requests
+      cache: 5 # Time in minutes to cache API responses, to stay within limits
+```
+
+You can optionally not pass a `latitude` and `longitude` and the widget will use your current location (requires a secure context, eg. HTTPS).

docs/widgets/info/resources.md

@@ -0,0 +1,71 @@
+---
+title: Resources
+description: Resources Information Widget Configuration
+---
+
+You can include all or some of the available resources. If you do not want to see that resource, simply pass `false`.
+
+The disk path is the path reported by `df` (Mounted On), or the mount point of the disk.
+
+The cpu and memory resource information are the container's usage while [glances](glances.md) displays statistics for the host machine on which it is installed.
+
+_Note: unfortunately, the package used for getting CPU temp ([systeminformation](https://systeminformation.io)) is not compatibile with some setups and will not report any value(s) for CPU temp._
+
+**Any disk you wish to access must be mounted to your container as a volume.**
+
+```yaml
+- resources:
+      cpu: true
+      memory: true
+      disk: /disk/mount/path
+      cputemp: true
+      uptime: true
+      units: imperial # only used by cpu temp
+      refresh: 3000 # optional, in ms
+```
+
+You can also pass a `label` option, which allows you to group resources under named sections,
+
+```yaml
+- resources:
+      label: System
+      cpu: true
+      memory: true
+
+- resources:
+      label: Storage
+      disk: /mnt/storage
+```
+
+Which produces something like this,
+
+<img width="373" alt="Resource Groups" src="https://user-images.githubusercontent.com/82196/189524699-e9005138-e049-4a9c-8833-ac06e39882da.png">
+
+If you have more than a single disk and would like to group them together under the same label, you can pass an array of paths instead,
+
+```yaml
+- resources:
+      label: Storage
+      disk:
+          - /mnt/storage
+          - /mnt/backup
+          - /mnt/media
+```
+
+To produce something like this,
+
+<img width="369" alt="Screenshot 2022-09-11 at 2 15 42 PM" src="https://user-images.githubusercontent.com/82196/189524583-abdf4cc6-99da-430c-b316-16c567db5639.png">
+
+You can additionally supply an optional `expanded` property set to true in order to show additional details about the resources. By default the expanded property is set to false when not supplied.
+
+```yaml
+- resources:
+      label: Array Disks
+      expanded: true
+      disk:
+          - /disk1
+          - /disk2
+          - /disk3
+```
+
+![194136533-c4238c82-4d67-41a4-b3c8-18bf26d33ac2](https://user-images.githubusercontent.com/3441425/194728642-a9885274-922b-4027-acf5-a746f58fdfce.png)

docs/widgets/info/search.md

@@ -0,0 +1,31 @@
+---
+title: Search
+description: Search Information Widget Configuration
+---
+
+You can add a search bar to your top widget area that can search using Google, Duckduckgo, Bing, Baidu, Brave or any other custom provider that supports the basic `?q=` search query param.
+
+```yaml
+- search:
+      provider: google # google, duckduckgo, bing, baidu, brave or custom
+      focus: true # Optional, will set focus to the search bar on page load
+      target: _blank # One of _self, _blank, _parent or _top
+```
+
+or for a custom search:
+
+```yaml
+- search:
+      provider: custom
+      url: https://lougle.com/?q=
+      target: _blank
+```
+
+multiple providers is also supported via a dropdown (excluding custom):
+
+```yaml
+- search:
+      provider: [brave, google, duckduckgo]
+```
+
+_Added in v0.1.6, updated in 0.6.0_

docs/widgets/info/unifi_controller.md

@@ -0,0 +1,24 @@
+---
+title: Unifi Controller
+description: Unifi Controller Information Widget Configuration
+---
+
+_(Find the Unifi Controller service widget [here](../services/unifi-controller.md))_
+
+You can display general connectivity status from your Unifi (Network) Controller. When authenticating you will want to use a local account that has at least read privileges.
+
+An optional 'site' parameter can be supplied, if it is not the widget will use the default site for the controller.
+
+_Note: If you enter e.g. incorrect credentials and receive an "API Error", you may need to recreate the container to clear the cache._
+
+<img width="162" alt="unifi_infowidget" src="https://user-images.githubusercontent.com/4887959/197706832-f5a8706b-7282-4892-a666-b7d999752562.png">
+
+```yaml
+- unifi_console:
+    url: https://unifi.host.or.ip:port
+    username: user
+    password: pass
+    site: Site Name # optional
+```
+
+_Added in v0.4.18, updated in 0.6.7_

docs/widgets/info/weather.md

@@ -0,0 +1,20 @@
+---
+title: Weather API
+description: Weather API Information Widget Configuration
+---
+
+**Note: this widget is considered 'deprecated' since there is no longer a free Weather API tier for new members. See the openmeteo or openweathermap widgets for alternatives.**
+
+The free tier is all thats required, you will need to [register](https://www.weatherapi.com/signup.aspx) and grab your API key.
+
+```yaml
+- weatherapi:
+      label: Kyiv # optional
+      latitude: 50.449684
+      longitude: 30.525026
+      units: metric # or imperial
+      apiKey: yourweatherapikey
+      cache: 5 # Time in minutes to cache API responses, to stay within limits
+```
+
+You can optionally not pass a `latitude` and `longitude` and the widget will use your current location (requires a secure context, eg. HTTPS).

docs/widgets/services/adguard-home.md

@@ -0,0 +1,16 @@
+---
+title: Adguard Home
+description: Adguard Home Widget Configuration
+---
+
+The username and password are the same as used to login to the web interface.
+
+Allowed fields: `["queries", "blocked", "filtered", "latency"]`.
+
+```yaml
+widget:
+    type: adguard
+    url: http://adguard.host.or.ip
+    username: admin
+    password: password
+```

docs/widgets/services/atsumeru.md

@@ -0,0 +1,16 @@
+---
+title: Atsumeru
+description: Atsumeru Widget Configuration
+---
+
+Define same username and password that is used for login from web or supported apps
+
+Allowed fields: `["series", "archives", "chapters", "categories"]`.
+
+```yaml
+widget:
+    type: atsumeru
+    url: http://atsumeru.host.or.ip:port
+    username: username
+    password: password
+```

docs/widgets/services/audiobookshelf.md

@@ -0,0 +1,15 @@
+---
+title: Audiobookshelf
+description: Audiobookshelf Widget Configuration
+---
+
+You can find your API token by logging into the Audiobookshelf web app as an admin, go to the config → users page, and click on your account.
+
+Allowed fields: `["podcasts", "podcastsDuration", "books", "booksDuration"]`
+
+```yaml
+widget:
+    type: audiobookshelf
+    url: http://audiobookshelf.host.or.ip:port
+    key: audiobookshelflapikey
+```

docs/widgets/services/authentik.md

@@ -0,0 +1,24 @@
+---
+title: Authentik
+description: Authentik Widget Configuration
+---
+
+This widget reads the number of active users in the system, as well as logins for the last 24 hours.
+
+You will need to generate an API token for an existing user. To do so follow these steps:
+
+1. Navigate to the Authentik Admin Portal
+2. Expand Directory, the click Tokens & App passwords
+3. Click the Create button
+4. Fill out the dialog making sure to set Intent to API Token
+5. Click the Create button on the dialog
+6. Click the copy button on the far right of the newly created API Token
+
+Allowed fields: `["users", "loginsLast24H", "failedLoginsLast24H"]`.
+
+```yaml
+widget:
+    type: authentik
+    url: http://authentik.host.or.ip:22070
+    key: api_token
+```

docs/widgets/services/autobrr.md

@@ -0,0 +1,15 @@
+---
+title: Autobrr
+description: Autobrr Widget Configuration
+---
+
+Find your API key under `Settings > API Keys`.
+
+Allowed fields: `["approvedPushes", "rejectedPushes", "filters", "indexers"]`.
+
+```yaml
+widget:
+    type: autobrr
+    url: http://autobrr.host.or.ip
+    key: apikeyapikeyapikeyapikeyapikey
+```

docs/widgets/services/azuredevops.md

@@ -0,0 +1,26 @@
+---
+title: Azure DevOps
+description: Azure DevOps Widget Configuration
+---
+
+This widget has 2 functions:
+
+1. Pipelines: checks if the relevant pipeline is running or not, and if not, reports the last status.\
+   Allowed fields: `["result", "status"]`.
+
+2. Pull Requests: returns the amount of open PRs, the amount of the PRs you have open, and how many PRs that you open are marked as 'Approved' by atleast 1 person and not yet completed.\
+   Allowed fields: `["totalPrs", "myPrs", "approved"]`.
+
+You will need to generate a personal access token for an existing user, see the [azure documentation](https://learn.microsoft.com/en-us/azure/devops/organizations/accounts/use-personal-access-tokens-to-authenticate?view=azure-devops&tabs=Windows#create-a-pat)
+
+```yaml
+widget:
+    type: azuredevops
+    organization: myOrganization
+    project: myProject
+    definitionId: pipelineDefinitionId # required for pipelines
+    branchName: branchName # optional for pipelines, leave empty for all
+    userEmail: email # required for pull requests
+    repositoryId: prRepositoryId # required for pull requests
+    key: personalaccesstoken
+```

docs/widgets/services/bazarr.md

@@ -0,0 +1,15 @@
+---
+title: Bazarr
+description: Bazarr Widget Configuration
+---
+
+Find your API key under `Settings > General`.
+
+Allowed fields: `["missingEpisodes", "missingMovies"]`.
+
+```yaml
+widget:
+    type: bazarr
+    url: http://bazarr.host.or.ip
+    key: apikeyapikeyapikeyapikeyapikey
+```

docs/widgets/services/caddy.md

@@ -0,0 +1,12 @@
+---
+title: Caddy
+description: Caddy Widget Configuration
+---
+
+Allowed fields: `["upstreams", "requests", "requests_failed"]`.
+
+```yaml
+widget:
+    type: caddy
+    url: http://caddy.host.or.ip:adminport # default admin port is 2019
+```

docs/widgets/services/calendar.md

@@ -0,0 +1,25 @@
+---
+title: Calendar
+description: Calendar widget
+---
+
+<img alt="calendar" src="https://user-images.githubusercontent.com/5442891/271131282-6767a3ea-573e-4005-aeb9-6e14ee01e845.png">
+
+This widget shows monthly calendar, with optional integrations to show events from supported widgets.
+
+```yaml
+widget:
+  type: calendar
+  firstDayInWeek: sunday # optional - defaults to monday
+  integrations: # optional
+    - type: sonarr # active widget type that is currently enabled on homepage - possible values: radarr, sonarr, lidarr, readarr
+      service_group: Media # group name where widget exists
+      service_name: Sonarr # service name for that widget
+      color: teal # optional - defaults to pre-defined color for the service (teal for sonarr)
+      params: # optional - additional params for the service
+        unmonitored: true # optional - defaults to false, used with *arr stack
+```
+
+Currently integrated widgets are [sonarr](sonarr.md), [radarr](radarr.md), [lidarr](lidarr.md) and [readarr](readarr.md).
+
+Supported colors can be found on [color palette](../../configs/settings.md#color-palette).

docs/widgets/services/calibre-web.md

@@ -0,0 +1,16 @@
+---
+title: Calibre-web
+description: Calibre-web Widget Configuration
+---
+
+**Note: this widget requires a feature of calibre-web that has not yet been distributed in versioned release. The code is contained in ["nightly" lsio builds after 25/8/23](https://hub.docker.com/layers/linuxserver/calibre-web/nightly/images/sha256-b27cbe5d17503de38135d925e226eb3e5ba04c558dbc865dc85d77824d35d7e2) or running the calibre-web source code including commit [0499e57](https://github.com/janeczku/calibre-web/commit/0499e578cdd45db656da34cd2d7152c8d88ceb23).**
+
+Allowed fields: `["books", "authors", "categories", "series"]`.
+
+```yaml
+widget:
+    type: calibreweb
+    url: http://your.calibreweb.host:port
+    username: username
+    password: password
+```

docs/widgets/services/changedetectionio.md

@@ -0,0 +1,13 @@
+---
+title: Changedetection.io
+description: Changedetection.io Widget Configuration
+---
+
+Find your API key under `Settings > API`.
+
+```yaml
+widget:
+    type: changedetectionio
+    url: http://changedetection.host.or.ip:port
+    key: apikeyapikeyapikeyapikeyapikey
+```

docs/widgets/services/channelsdvrserver.md

@@ -0,0 +1,10 @@
+---
+title: Channels DVR Server
+description: Channels DVR Server Widget Configuration
+---
+
+```yaml
+widget:
+    type: channelsdvrserver
+    url: http://192.168.1.55:8089
+```

docs/widgets/services/cloudflared.md

@@ -0,0 +1,16 @@
+---
+title: Cloudflare Tunnels
+description: Cloudflare Tunnels Widget Configuration
+---
+
+_As of v0.6.10 this widget no longer accepts a Cloudflare global API key (or account email) due to security concerns. Instead, you should setup an API token which only requires the permissions `Account.Cloudflare Tunnel:Read`._
+
+Allowed fields: `["status", "origin_ip"]`.
+
+```yaml
+widget:
+    type: cloudflared
+    accountid: accountid # from zero trust dashboard url e.g. https://one.dash.cloudflare.com/<accountid>/home/quick-start
+    tunnelid: tunnelid # found in tunnels dashboard under the tunnel name
+    key: cloudflareapitoken # api token with `Account.Cloudflare Tunnel:Read` https://dash.cloudflare.com/profile/api-tokens
+```

docs/widgets/services/coin-market-cap.md

@@ -0,0 +1,25 @@
+---
+title: Coin Market Cap
+description: Coin Market Cap Widget Configuration
+---
+
+Get your API key from your [CoinMarketCap Pro Dashboard](https://pro.coinmarketcap.com/account).
+
+Allowed fields: no configurable fields for this widget.
+
+```yaml
+widget:
+    type: coinmarketcap
+    currency: GBP # Optional
+    symbols: [BTC, LTC, ETH]
+    key: apikeyapikeyapikeyapikeyapikey
+```
+
+You can also specify slugs instead of symbols (since symbols aren't garaunteed to be unique). If you supply both, slugs will be used. For example:
+
+```yaml
+widget:
+    type: coinmarketcap
+    slugs: [chia-network, uniswap]
+    key: apikeyapikeyapikeyapikeyapikey
+```

docs/widgets/services/customapi.md

@@ -0,0 +1,109 @@
+---
+title: Custom API
+description: Custom Widget Configuration from the API
+---
+
+This widget can show information from custom self-hosted or third party API.
+
+Fields need to be defined in the `mappings` section YAML object to correlate with the value in the APIs JSON object. Final field definition needs to be the key with the desired value information.
+
+```yaml
+widget:
+    type: customapi
+    url: http://custom.api.host.or.ip:port/path/to/exact/api/endpoint
+    refreshInterval: 10000 # optional - in milliseconds, defaults to 10s
+    username: username # auth - optional
+    password: password # auth - optional
+    method: GET # optional, e.g. POST
+    headers: # optional, must be object, see below
+    mappings:
+        - field: key # needs to be YAML string or object
+          label: Field 1
+          format: text # optional - defaults to text
+        - field: # needs to be YAML string or object
+              path:
+                  to: key2
+          format: number # optional - defaults to text
+          label: Field 2
+        - field: # needs to be YAML string or object
+              path:
+                  to:
+                      another: key3
+          label: Field 3
+          format: percent # optional - defaults to text
+```
+
+Supported formats for the values are `text`, `number`, `float`, `percent`, `bytes` and `bitrate`.
+
+## Example
+
+For the following JSON object from the API:
+
+```json
+{
+    "id": 1,
+    "name": "Rick Sanchez",
+    "status": "Alive",
+    "species": "Human",
+    "gender": "Male",
+    "origin": {
+        "name": "Earth (C-137)"
+    },
+    "locations": [
+        {
+            "name": "Earth (C-137)"
+        },
+        {
+            "name": "Citadel of Ricks"
+        }
+    ]
+}
+```
+
+Define the `mappings` section as an aray, for example:
+
+```yaml
+mappings:
+    - field: name # Rick Sanchez
+      label: Name
+    - field: status # Alive
+      label: Status
+    - field:
+          origin: name # Earth (C-137)
+      label: Origin
+    - field:
+          locations:
+              1: name # Citadel of Ricks
+      label: Location
+```
+
+## Data Transformation
+
+You can manipulate data with the following tools `remap`, `scale` and `suffix`, for example:
+
+```yaml
+- field: key4
+  label: Field 4
+  format: text
+  remap:
+      - value: 0
+        to: None
+      - value: 1
+        to: Connected
+      - any: true # will map all other values
+        to: Unknown
+- field: key5
+  label: Power
+  format: float
+  scale: 0.001 # can be number or string e.g. 1/16
+  suffix: kW
+```
+
+## Custom Headers
+
+Pass custom headers using the `headers` option, for example:
+
+```yaml
+headers:
+    X-API-Token: token
+```

docs/widgets/services/deluge.md

@@ -0,0 +1,15 @@
+---
+title: Deluge
+description: Deluge Widget Configuration
+---
+
+Uses the same password used to login to the webui, see [the deluge FAQ](https://dev.deluge-torrent.org/wiki/Faq#Whatisthedefaultpassword).
+
+Allowed fields: `["leech", "download", "seed", "upload"]`.
+
+```yaml
+widget:
+    type: deluge
+    url: http://deluge.host.or.ip
+    password: password # webui password
+```

docs/widgets/services/diskstation.md

@@ -0,0 +1,36 @@
+---
+title: Synology Disk Station
+description: Synology Disk Station Widget Configuration
+---
+
+Note: the widget is not compatible with 2FA.
+
+An optional 'volume' parameter can be supplied to specify which volume's free space to display when more than one volume exists. The value of the parameter must be in form of `volume_N`, e.g. to display free space for volume2, `volume_2` should be set as 'volume' value. If omitted, first returned volume's free space will be shown (not guaranteed to be volume1).
+
+Allowed fields: `["uptime", "volumeAvailable", "resources.cpu", "resources.mem"]`.
+
+To access these system metrics you need to connect to the DiskStation with an account that is a member of the default `Administrators` group. That is because these metrics are requested from the API's `SYNO.Core.System` part that is only available to admin users. In order to keep the security impact as small as possible we can set the account in DSM up to limit the user's permissions inside the Synology system. In DSM 7.x, for instance, follow these steps:
+
+1. Create a new user, i.e. `remote_stats`.
+2. Set up a strong password for the new user
+3. Under the `User Groups` tab of the user config dialogue check the box for `Administrators`.
+4. On the `Permissions` tab check the top box for `No Access`, effectively prohibiting the user from accessing anything in the shared folders.
+5. Under `Applications` check the box next to `Deny` in the header to explicitly prohibit login to all applications.
+6. Now _only_ allow login to the `Download Station` application, either by
+    - unchecking `Deny` in the respective row, or (if inheriting permission doesn't work because of other group settings)
+    - checking `Allow` for this app, or
+    - checking `By IP` for this app to limit the source of login attempts to one or more IP addresses/subnets.
+7. When the `Preview` column shows `Allow` in the `Download Station` row, click `Save`.
+
+Now configure the widget with the correct login information and test it.
+
+If you encounter issues during testing, make sure to uncheck the option for automatic blocking due to invalid logins under `Control Panel > Security > Protection`. If desired, this setting can be reactivated once the login is established working.
+
+```yaml
+widget:
+    type: diskstation
+    url: http://diskstation.host.or.ip:port
+    username: username
+    password: password
+    volume: volume_N # optional
+```

docs/widgets/services/downloadstation.md

@@ -0,0 +1,16 @@
+---
+title: Synology Download Station
+description: Synology Download Station Widget Configuration
+---
+
+Note: the widget is not compatible with 2FA.
+
+Allowed fields: `["leech", "download", "seed", "upload"]`.
+
+```yaml
+widget:
+    type: downloadstation
+    url: http://downloadstation.host.or.ip:port
+    username: username
+    password: password
+```

docs/widgets/services/emby.md

@@ -0,0 +1,17 @@
+---
+title: Emby
+description: Emby Widget Configuration
+---
+
+You can create an API key from inside Emby at `Settings > Advanced > Api Keys`.
+
+As of v0.6.11 the widget supports fields `["movies", "series", "episodes", "songs"]`. These blocks are disabled by default but can be enabled with the `enableBlocks` option, and the "Now Playing" feature (enabled by default) can be disabled with the `enableNowPlaying` option.
+
+```yaml
+widget:
+    type: emby
+    url: http://emby.host.or.ip
+    key: apikeyapikeyapikeyapikeyapikey
+    enableBlocks: true # optional, defaults to false
+    enableNowPlaying: true # optional, defaults to true
+```

docs/widgets/services/evcc.md

@@ -0,0 +1,12 @@
+---
+title: EVCC
+description: EVCC Widget Configuration
+---
+
+Allowed fields: `["pv_power", "grid_power", "home_power", "charge_power]`.
+
+```yaml
+widget:
+    type: evcc
+    url: http://evcc.host.or.ip:port
+```

docs/widgets/services/fileflows.md

@@ -0,0 +1,12 @@
+---
+title: Fileflows
+description: Fileflows Widget Configuration
+---
+
+Allowed fields: `["queue", "processing", "processed", "time"]`.
+
+```yaml
+widget:
+    type: fileflows
+    url: http://your.fileflows.host:port
+```

docs/widgets/services/flood.md

@@ -0,0 +1,14 @@
+---
+title: Flood
+description: Flood Widget Configuration
+---
+
+Allowed fields: `["leech", "download", "seed", "upload"]`.
+
+```yaml
+widget:
+    type: flood
+    url: http://flood.host.or.ip
+    username: username # if set
+    password: password # if set
+```

docs/widgets/services/freshrss.md

@@ -0,0 +1,16 @@
+---
+title: FreshRSS
+description: FreshRSS Widget Configuration
+---
+
+Please refer to [Enable the API in FreshRSS](https://freshrss.github.io/FreshRSS/en/users/06_Mobile_access.html#enable-the-api-in-freshrss) for the "API password" to be entered in the password field.
+
+Allowed fields: `["subscriptions", "unread"]`.
+
+```yaml
+widget:
+    type: freshrss
+    url: http://freshrss.host.or.ip:port
+    username: username
+    password: password
+```

docs/widgets/services/gamedig.md

@@ -0,0 +1,15 @@
+---
+title: GameDig
+description: GameDig Widget Configuration
+---
+
+Uses the [GameDig](https://www.npmjs.com/package/gamedig) library to get game server information for any supported server type.
+
+Allowed fields (limited to a max of 4): `["status", "name", "map", "currentPlayers", "players", "maxPlayers", "bots", "ping"]`.
+
+```yaml
+widget:
+    type: gamedig
+    serverType: csgo # see https://github.com/gamedig/node-gamedig#games-list
+    url: udp://server.host.or.ip:port
+```

docs/widgets/services/ghostfolio.md

@@ -0,0 +1,23 @@
+---
+title: Ghostfolio
+description: Ghostfolio Widget Configuration
+---
+
+Authentication requires manually obtaining a Bearer token which can be obtained by make a POST request to the API e.g.
+
+```
+curl -X POST http://localhost:3333/api/v1/auth/anonymous -H 'Content-Type: application/json' -d '{ "accessToken": "SECURITY_TOKEN_OF_ACCOUNT" }'
+```
+
+See the [official docs](https://github.com/ghostfolio/ghostfolio#authorization-bearer-token).
+
+_Note that the Bearer token is valid for 6 months, after which a new one must be generated._
+
+Allowed fields: `["gross_percent_today", "gross_percent_1y", "gross_percent_max"]`
+
+```yaml
+widget:
+    type: ghostfolio
+    url: http://ghostfoliohost:port
+    key: ghostfoliobearertoken
+```

docs/widgets/services/glances.md

@@ -0,0 +1,73 @@
+---
+title: Glances
+description: Glances Widget Configuration
+---
+
+<img width="1614" alt="glances" src="https://github.com/benphelps/homepage-docs/assets/82196/25648c97-2c1b-4db0-b5a5-f1509806079c">
+
+_(Find the Glances information widget [here](../services/glances.md))_
+
+The Glances widget allows you to monitor the resources (cpu, memory, diskio, sensors & processes) of host or another machine. You can have multiple instances by adding another service block.
+
+```yaml
+widget:
+  type: glances
+  url: http://glances.host.or.ip:port
+  username: user # optional if auth enabled in Glances
+  password: pass # optional if auth enabled in Glances
+  metric: cpu
+```
+
+_Please note, this widget does not need an `href`, `icon` or `description` on its parent service. To achive the same effect as the examples above, see as an example:_
+
+```yaml
+- CPU Usage:
+    widget:
+      type: glances
+      url: http://glances.host.or.ip:port
+      metric: cpu
+- Network Usage:
+    widget:
+      type: glances
+      url: http://glances.host.or.ip:port
+      metric: network:enp0s25
+```
+
+## Metrics
+
+The metric field in the configuration determines the type of system monitoring data to be displayed. Here are the supported metrics:
+
+`info`: System information. Shows the system's hostname, OS, kernel version, CPU type, CPU usage, RAM usage and SWAP usage.
+
+`cpu`: CPU usage. Shows how much of the system's computational resources are currently being used.
+
+`memory`: Memory usage. Shows how much of the system's RAM is currently being used.
+
+`process`: Top 5 processes based on CPU usage. Gives an overview of which processes are consuming the most resources.
+
+`network:<interface_name>`: Network data usage for the specified interface. Replace `<interface_name>` with the name of your network interface, e.g., `network:enp0s25`, as specificed in glances.
+
+`sensor:<sensor_id>`: Temperature of the specified sensor, typically used to monitor CPU temperature. Replace `<sensor_id>` with the name of your sensor, e.g., `sensor:Package id 0` as specificed in glances.
+
+`disk:<disk_id>`: Disk I/O data for the specified disk. Replace `<disk_id>` with the id of your disk, e.g., `disk:sdb`, as specificed in glances.
+
+`gpu:<gpu_id>`: GPU usage for the specified GPU. Replace `<gpu_id>` with the id of your GPU, e.g., `gpu:0`, as specificed in glances.
+
+`fs:<mnt_point>`: Disk usage for the specified mount point. Replace `<mnt_point>` with the path of your disk, e.g., `/mnt/storage`, as specificed in glances.
+
+## Views
+
+All widgets offer an alternative to the full or "graph" view, which is the compact, or "graphless" view.
+
+<img width="970" alt="Screenshot 2023-09-06 at 1 51 48 PM" src="https://github.com/benphelps/homepage-docs/assets/82196/cc6b9adc-4218-4274-96ca-36c3e64de5d0">
+
+To switch to the alternative "graphless" view, simply passs `chart: false` as an option to the widget, like so:
+
+```yaml
+- Network Usage:
+    widget:
+      type: glances
+      url: http://glances.host.or.ip:port
+      metric: network:enp0s25
+      chart: false
+```

docs/widgets/services/gluetun.md

@@ -0,0 +1,14 @@
+---
+title: Gluetun
+description: Gluetun Widget Configuration
+---
+
+Requires [HTTP control server options](https://github.com/qdm12/gluetun/wiki/HTTP-control-server-options) to be enabled.
+
+Allowed fields: `["public_ip", "region", "country"]`.
+
+```yaml
+widget:
+    type: gluetun
+    url: http://gluetun.host.or.ip
+```

docs/widgets/services/gotify.md

@@ -0,0 +1,15 @@
+---
+title: Gotify
+description: Gotify Widget Configuration
+---
+
+Get a Gotify client token from an existing client or create a new one on your Gotify admin page.
+
+Allowed fields: `["apps", "clients", "messages"]`.
+
+```yaml
+widget:
+    type: gotify
+    url: http://gotify.host.or.ip
+    key: clientoken
+```

docs/widgets/services/grafana.md

@@ -0,0 +1,14 @@
+---
+title: Grafana
+description: Grafana Widget Configuration
+---
+
+Allowed fields: `["dashboards", "datasources", "totalalerts", "alertstriggered"]`.
+
+```yaml
+widget:
+    type: grafana
+    url: http://grafana.host.or.ip:port
+    username: username
+    password: password
+```

docs/widgets/services/healthchecks.md

@@ -0,0 +1,20 @@
+---
+title: Health checks
+description: Health checks Widget Configuration
+---
+
+To use the Health Checks widget, you first need to generate an API key. To do this, follow these steps:
+
+1. Go to Settings in your check dashboard.
+2. Click on API key (read-only) and then click _Create_.
+3. Copy the API key that is generated for you.
+
+Allowed fields: `["status", "last_ping"]`.
+
+```yaml
+widget:
+    type: healthchecks
+    url: http://healthchecks.host.or.ip:port
+    key: <YOUR_API_KEY>
+    uuid: <YOUR_CHECK_UUID>
+```

docs/widgets/services/homeassistant.md

@@ -0,0 +1,36 @@
+---
+title: Home Assistant
+description: Home Assistant Widget Configuration
+---
+
+You will need to generate a long-lived access token for an existing Home Assistant user in its profile.
+
+Allowed fields: `["people_home", "lights_on", "switches_on"]`.
+
+---
+
+Up to a maximum of four custom states and/or templates can be queried via the `custom` property like in the example below.
+The `custom` property will have no effect as long as the `fields` property is defined.
+
+-   `state` will query the state of the specified `entity_id`
+    -   state labels and values can be user defined and may reference entity attributes in curly brackets
+    -   if no state label is defined it will default to `"{attributes.friendly_name}"`
+    -   if no state value is defined it will default to `"{state} {attributes.unit_of_measurement}"`
+-   `template` will query the specified template, see (Home Assistant Templating)[https://www.home-assistant.io/docs/configuration/templating]
+    -   if no template label is defined it will be empty
+
+```yaml
+widget:
+    type: homeassistant
+    url: http://homeassistant.host.or.ip:port
+    key: access_token
+    custom:
+        - state: sensor.total_power
+        - state: sensor.total_energy_today
+          label: energy today
+        - template: "{{ states.switch|selectattr('state','equalto','on')|list|length }}"
+          label: switches on
+        - state: weather.forecast_home
+          label: wind speed
+          value: "{attributes.wind_speed} {attributes.wind_speed_unit}"
+```

docs/widgets/services/homebridge.md

@@ -0,0 +1,16 @@
+---
+title: Homebridge
+description: Homebridge
+---
+
+The Homebridge API is actually provided by the Config UI X plugin that has been included with Homebridge for a while, still it is required to be installed for this widget to work.
+
+Allowed fields: `["updates", "child_bridges"]`.
+
+```yaml
+widget:
+    type: homebridge
+    url: http://homebridge.host.or.ip:port
+    username: username
+    password: password
+```

docs/widgets/services/immich.md

@@ -0,0 +1,15 @@
+---
+title: Immich
+description: Immich Widget Configuration
+---
+
+Allowed fields: `["users" ,"photos", "videos", "storage"]`.
+
+Note that API key must be from admin user.
+
+```yaml
+widget:
+    type: immich
+    url: http://immich.host.or.ip
+    key: adminapikeyadminapikeyadminapikey
+```

docs/widgets/services/index.md

@@ -0,0 +1,4 @@
+---
+title: Service Widgets
+description: Homepage service widgets.
+---

docs/widgets/services/jackett.md

@@ -0,0 +1,14 @@
+---
+title: Jackett
+description: Jackett Widget Configuration
+---
+
+Jackett must not have any authentication for the widget to work.
+
+Allowed fields: `["configured", "errored"]`.
+
+```yaml
+widget:
+    type: jackett
+    url: http://jackett.host.or.ip
+```

docs/widgets/services/jdownloader.md

@@ -0,0 +1,16 @@
+---
+title: JDownloader
+description: NextPVR Widget Configuration
+---
+
+Basic widget to show number of items in download queue, along with the queue size and current download speed.
+
+Allowed fields: `["downloadCount", "downloadTotalBytes","downloadBytesRemaining", "downloadSpeed"]`.
+
+```yaml
+widget:
+    type: jdownloader
+    username: JDownloader Username
+    password: JDownloader Password
+    client: Name of JDownloader Instance
+```

docs/widgets/services/jellyfin.md

@@ -0,0 +1,17 @@
+---
+title: Jellyfin
+description: Jellyfin Widget Configuration
+---
+
+You can create an API key from inside Jellyfin at `Settings > Advanced > Api Keys`.
+
+As of v0.6.11 the widget supports fields `["movies", "series", "episodes", "songs"]`. These blocks are disabled by default but can be enabled with the `enableBlocks` option, and the "Now Playing" feature (enabled by default) can be disabled with the `enableNowPlaying` option.
+
+```yaml
+widget:
+    type: jellyfin
+    url: http://jellyfin.host.or.ip
+    key: apikeyapikeyapikeyapikeyapikey
+    enableBlocks: true # optional, defaults to false
+    enableNowPlaying: true # optional, defaults to true
+```

docs/widgets/services/jellyseerr.md

@@ -0,0 +1,15 @@
+---
+title: Jellyseerr
+description: Jellyseerr Widget Configuration
+---
+
+Find your API key under `Settings > General > API Key`.
+
+Allowed fields: `["pending", "approved", "available"]`.
+
+```yaml
+widget:
+    type: jellyseerr
+    url: http://jellyseerr.host.or.ip
+    key: apikeyapikeyapikeyapikeyapikey
+```

docs/widgets/services/kavita.md

@@ -0,0 +1,16 @@
+---
+title: Kavita
+description: Kavita Widget Configuration
+---
+
+Uses the same username and password used to login from the web.
+
+Allowed fields: `["seriesCount", "totalFiles"]`.
+
+```yaml
+widget:
+    type: kavita
+    url: http://kavita.host.or.ip:port
+    username: username
+    password: password
+```

docs/widgets/services/komga.md

@@ -0,0 +1,16 @@
+---
+title: Komga
+description: Komga Widget Configuration
+---
+
+Uses the same username and password used to login from the web.
+
+Allowed fields: `["libraries", "series", "books"]`.
+
+```yaml
+widget:
+    type: komga
+    url: http://komga.host.or.ip:port
+    username: username
+    password: password
+```

docs/widgets/services/kopia.md

@@ -0,0 +1,18 @@
+---
+title: Kopia
+description: Kopia Widget Configuration
+---
+
+Allowed fields: `["status", "size", "lastrun", "nextrun"]`.
+
+You may optionally pass values for `snapshotHost` and / or `snapshotPath` to select a specific backup source for the widget.
+
+```yaml
+widget:
+    type: kopia
+    url: http://kopia.host.or.ip:port
+    username: username
+    password: password
+    snapshotHost: hostname # optional
+    snapshotPath: path # optional
+```

docs/widgets/services/lidarr.md

@@ -0,0 +1,15 @@
+---
+title: Lidarr
+description: Lidarr Widget Configuration
+---
+
+Find your API key under `Settings > General`.
+
+Allowed fields: `["wanted", "queued", "artists"]`.
+
+```yaml
+widget:
+    type: lidarr
+    url: http://lidarr.host.or.ip
+    key: apikeyapikeyapikeyapikeyapikey
+```

docs/widgets/services/mastodon.md

@@ -0,0 +1,14 @@
+---
+title: Mastodon
+description: Mastodon Widget Configuration
+---
+
+Use the base URL of the Mastodon instance you'd like to pull stats for. Does not require authentication as the stats are part of the public API endpoints.
+
+Allowed fields: `["user_count", "status_count", "domain_count"]`.
+
+```yaml
+widget:
+    type: mastodon
+    url: https://mastodon.host.name
+```

docs/widgets/services/mealie.md

@@ -0,0 +1,15 @@
+---
+title: Mealie
+description: Mealie Widget Configuration
+---
+
+Generate a user API key under `Profile > Manage Your API Tokens > Generate`.
+
+Allowed fields: `["recipes", "users", "categories", "tags"]`.
+
+```yaml
+widget:
+    type: mealie
+    url: http://mealie-frontend.host.or.ip
+    key: mealieapitoken
+```

docs/widgets/services/medusa.md

@@ -0,0 +1,13 @@
+---
+title: Medusa
+description: Medusa Widget Configuration
+---
+
+Allowed fields: `["wanted", "queued", "series"]`.
+
+```yaml
+widget:
+    type: medusa
+    url: http://medusa.host.or.ip:port
+    key: medusaapikeyapikeyapikeyapikeyapikey
+```

docs/widgets/services/mikrotik.md

@@ -0,0 +1,16 @@
+---
+title: Mikrotik
+description: Mikrotik Widget Configuration
+---
+
+HTTPS may be required, [per the documentation](https://help.mikrotik.com/docs/display/ROS/REST+API#RESTAPI-Overview)
+
+Allowed fields: `["uptime", "cpuLoad", "memoryUsed", "numberOfLeases"]`.
+
+```yaml
+widget:
+    type: mikrotik
+    url: https://mikrotik.host.or.ip
+    username: username
+    password: password
+```

docs/widgets/services/minecraft.md

@@ -0,0 +1,12 @@
+---
+title: Minecraft
+description: Minecraft Widget Configuration
+---
+
+Allowed fields: `["players", "version", "status"]`.
+
+```yaml
+widget:
+    type: minecraft
+    url: udp://minecraftserveripordomain:port
+```

docs/widgets/services/miniflux.md

@@ -0,0 +1,15 @@
+---
+title: Miniflux
+description: Miniflux Widget Configuration
+---
+
+Api key is found under Settings > API keys
+
+Allowed fields: `["unread", "read"]`.
+
+```yaml
+widget:
+    type: miniflux
+    url: http://miniflux.host.or.ip:port
+    key: minifluxapikey
+```

docs/widgets/services/mjpeg.md

@@ -0,0 +1,14 @@
+---
+title: MJPEG
+description: MJPEG Stream Widget Configuration
+---
+
+![camera-preview](https://github.com/benphelps/homepage-docs/assets/82196/dc375ae3-0670-489f-8db6-83ff1f423d12)
+
+Pass the stream URL from a service like [µStreamer](https://github.com/pikvm/ustreamer) or [camera-streamer](https://github.com/ayufan/camera-streamer).
+
+```yaml
+widget:
+    type: mjpeg
+    stream: http://mjpeg.host.or.ip/webcam/stream
+```

docs/widgets/services/moonraker.md

@@ -0,0 +1,12 @@
+---
+title: Moonraker (Klipper)
+description: Moonraker (Klipper) Widget Configuration
+---
+
+Allowed fields: `["printer_state", "print_status", "print_progress", "layers"]`.
+
+```yaml
+widget:
+    type: moonraker
+    url: http://moonraker.host.or.ip:port
+```

docs/widgets/services/mylar.md

@@ -0,0 +1,15 @@
+---
+title: Mylar3
+description: Mylar3 Widget Configuration
+---
+
+API must be enabled in Mylar3 settings.
+
+Allowed fields: `["series", "issues", "wanted"]`.
+
+```yaml
+widget:
+    type: mylar
+    url: http://mylar3.host.or.ip:port
+    key: yourmylar3apikey
+```

docs/widgets/services/navidrome.md

@@ -0,0 +1,17 @@
+---
+title: Navidrome
+description: Navidrome Widget Configuration
+---
+
+For detailed information about how to generate the token see http://www.subsonic.org/pages/api.jsp.
+
+Allowed fields: no configurable fields for this widget.
+
+```yaml
+widget:
+    type: navidrome
+    url: http://navidrome.host.or.ip:port
+    user: username
+    token: token #md5(password + salt)
+    salt: randomsalt
+```

docs/widgets/services/nextcloud.md

@@ -0,0 +1,25 @@
+---
+title: Nextcloud
+description: Nextcloud Widget Configuration
+---
+
+Use username & password, or the `NC-Token` key. Information about the token can be found under **Settings** > **System**. If both are provided, NC-Token will be used.
+
+Allowed fields: `["cpuload", "memoryusage", "freespace", "activeusers", "numfiles", "numshares"]`.
+
+Note "cpuload" and "memoryusage" were deprecated in v0.6.18 and a maximum of 4 fields can be displayed.
+
+```yaml
+widget:
+    type: nextcloud
+    url: https://nextcloud.host.or.ip:port
+    key: token
+```
+
+```yaml
+widget:
+    type: nextcloud
+    url: https://nextcloud.host.or.ip:port
+    username: username
+    password: password
+```

docs/widgets/services/nextdns.md

@@ -0,0 +1,13 @@
+---
+title: NextDNS
+description: NextDNS Widget Configuration
+---
+
+Api key is found under Account > API, profile ID is found under Setup > Endpoints > ID
+
+```yaml
+widget:
+    type: nextdns
+    profile: profileid
+    key: yourapikeyhere
+```

docs/widgets/services/nginx-proxy-manager.md

@@ -0,0 +1,16 @@
+---
+title: Nginx Proxy Manager
+description: Nginx Proxy Manager Widget Configuration
+---
+
+Login with the same admin username and password used to access the web UI.
+
+Allowed fields: `["enabled", "disabled", "total"]`.
+
+```yaml
+widget:
+    type: npm
+    url: http://npm.host.or.ip
+    username: admin_username
+    password: admin_password
+```

docs/widgets/services/nzbget.md

@@ -0,0 +1,16 @@
+---
+title: NZBget
+description: NZBget Widget Configuration
+---
+
+This widget uses the same authentication method as your browser when logging in (HTTP Basic Auth), and is often referred to as the ControlUsername and ControlPassword inside of Nzbget documentation.
+
+Allowed fields: `["rate", "remaining", "downloaded"]`.
+
+```yaml
+widget:
+    type: nzbget
+    url: http://nzbget.host.or.ip
+    username: controlusername
+    password: controlpassword
+```

docs/widgets/services/octoprint.md

@@ -0,0 +1,13 @@
+---
+title: OctoPrint
+description: OctoPrintWidget Configuration
+---
+
+Allowed fields: `["printer_state", "temp_tool", "temp_bed", "job_completion"]`.
+
+```yaml
+widget:
+    type: octoprint
+    url: http://octoprint.host.or.ip:port
+    key: youroctoprintapikey
+```

docs/widgets/services/omada.md

@@ -0,0 +1,17 @@
+---
+title: Omada
+description: Omada Widget Configuration
+---
+
+The widget supports controller versions 3, 4 and 5.
+
+Allowed fields: `["connectedAp", "activeUser", "alerts", "connectedGateways", "connectedSwitches"]`.
+
+```yaml
+widget:
+    type: omada
+    url: http://omada.host.or.ip:port
+    username: username
+    password: password
+    site: sitename
+```

docs/widgets/services/ombi.md

@@ -0,0 +1,15 @@
+---
+title: Ombi
+description: Ombi Widget Configuration
+---
+
+Find your API key under `Settings > Configuration > General`.
+
+Allowed fields: `["pending", "approved", "available"]`.
+
+```yaml
+widget:
+    type: ombi
+    url: http://ombi.host.or.ip
+    key: apikeyapikeyapikeyapikeyapikey
+```

docs/widgets/services/opendtu.md

@@ -0,0 +1,12 @@
+---
+title: OpenDTU
+description: OpenDTU Widget
+---
+
+Allowed fields: `["yieldDay", "relativePower", "absolutePower", "limit"]`.
+
+```yaml
+widget:
+    type: opendtu
+    url: http://opendtu.host.or.ip
+```

docs/widgets/services/openmediavault.md

@@ -0,0 +1,25 @@
+---
+title: OpenMediaVault
+description: OpenMediaVault Widget Configuration
+---
+
+Provides useful information from your OpenMediaVault
+
+```yaml
+widget:
+    type: openmediavault
+    url: http://omv.host.or.ip
+    username: admin
+    password: pass
+    method: services.getStatus # required
+```
+
+## Methods
+
+The method field determines the type of data to be displayed and is required. Supported methods:
+
+`services.getStatus`: Shows status of running services. Allowed fields: `["running", "stopped", "total"]`
+
+`smart.getListBg`: Shows S.M.A.R.T. status from disks. Allowed fields: `["passed", "failed"]`
+
+`downloader.getDownloadList`: Displays the number of tasks from the Downloader plugin currently being downloaded and total. Allowed fields: `["downloading", "total"]`

docs/widgets/services/opnsense.md

@@ -0,0 +1,21 @@
+---
+title: OPNSense
+description: OPNSense Widget Configuration
+---
+
+The API key & secret can be generated via the webui by creating a new user at _System/Access/Users_. Ensure "Generate a scrambled password to prevent local database logins for this user" is checked and then edit the effective privileges selecting **only**:
+
+-   Diagnostics: System Activity
+-   Status: Traffic Graph
+
+Finally, create a new API key which will download an `apikey.txt` file with your key and secret in it. Use the values as the username and password fields, respectively, in your homepage config.
+
+Allowed fields: `["cpu", "memory", "wanUpload", "wanDownload"]`.
+
+```yaml
+widget:
+    type: opnsense
+    url: http://opnsense.host.or.ip
+    username: key
+    password: secret
+```

docs/widgets/services/overseerr.md

@@ -0,0 +1,15 @@
+---
+title: Overseerr
+description: Overseerr Widget Configuration
+---
+
+Find your API key under `Settings > General`.
+
+Allowed fields: `["pending", "approved", "available", "processing"]`.
+
+```yaml
+widget:
+    type: overseerr
+    url: http://overseerr.host.or.ip
+    key: apikeyapikeyapikeyapikeyapikey
+```

docs/widgets/services/paperlessngx.md

@@ -0,0 +1,23 @@
+---
+title: Paperless-ngx
+description: Paperless-ngx Widget Configuration
+---
+
+Use username & password, or the token key. Information about the token can be found in the [Paperless-ngx API documentation](https://docs.paperless-ngx.com/api/#authorization). If both are provided, the token will be used.
+
+Allowed fields: `["total", "inbox"]`.
+
+```yaml
+widget:
+    type: paperlessngx
+    url: http://paperlessngx.host.or.ip:port
+    username: username
+    password: password
+```
+
+```yaml
+widget:
+    type: paperlessngx
+    url: http://paperlessngx.host.or.ip:port
+    key: token
+```

docs/widgets/services/pfsense.md

@@ -0,0 +1,25 @@
+---
+title: pfSense
+description: pfSense Widget Configuration
+---
+
+This widget requires the installation of the [pfsense-api](https://github.com/jaredhendrickson13/pfsense-api) which is a 3rd party package for pfSense routers.
+
+Once pfSense API is installed, you can set the API to be read-only in System > API > Settings.
+
+Currently the only supported authentication mode is 'Local Database'.
+
+WAN interface to monitor can be defined by updating the `wan` param.
+
+Load is returned instead of cpu utilization. This is a limitation in the pfSense API due to the complexity of this calculation. This may become available in future versions.
+
+Allowed fields: `["load", "memory", "temp", "wanStatus", "wanIP", "disk"]` (maximum of 4)
+
+```yaml
+widget:
+    type: pfsense
+    url: http://pfsense.host.or.ip:port
+    username: user
+    password: pass
+    wan: igb0
+```

docs/widgets/services/photoprism.md

@@ -0,0 +1,14 @@
+---
+title: PhotoPrism
+description: PhotoPrism Widget Configuration
+---
+
+Allowed fields: `["albums", "photos", "videos", "people"]`.
+
+```yaml
+widget:
+    type: photoprism
+    url: http://photoprism.host.or.ip:port
+    username: admin
+    password: password
+```

docs/widgets/services/pialert.md

@@ -0,0 +1,14 @@
+---
+title: PiAlert
+description: PiAlert Widget Configuration
+---
+
+Widget for [PiAlert](https://github.com/jokob-sk/Pi.Alert).
+
+Allowed fields: `["total", "connected", "new_devices", "down_alerts"]`.
+
+```yaml
+widget:
+    type: pialert
+    url: http://ip:port
+```

docs/widgets/services/pihole.md

@@ -0,0 +1,17 @@
+---
+title: PiHole
+description: PiHole Widget Configuration
+---
+
+As of v2022.12 [PiHole requires the use of an API key](https://pi-hole.net/blog/2022/11/17/upcoming-changes-authentication-for-more-api-endpoints-required/#page-content) if an admin password is set. Older versions do not require any authentication even if the admin uses a password.
+
+Allowed fields: `["queries", "blocked", "blocked_percent", "gravity"]`.
+
+```yaml
+widget:
+    type: pihole
+    url: http://pi.hole.or.ip
+    key: yourpiholeapikey # optional
+```
+
+_Added in v0.1.0, udpated in v0.6.18_

docs/widgets/services/plex-tautulli.md

@@ -0,0 +1,15 @@
+---
+title: Tautulli (Plex)
+description: Tautulli Widget Configuration
+---
+
+Provides detailed information about currently active streams. You can find the API key from inside Tautulli at `Settings > Web Interface > API`.
+
+Allowed fields: no configurable fields for this widget.
+
+```yaml
+widget:
+    type: tautulli
+    url: http://tautulli.host.or.ip
+    key: apikeyapikeyapikeyapikeyapikey
+```

docs/widgets/services/plex.md

@@ -0,0 +1,15 @@
+---
+title: Plex
+description: Plex Widget Configuration
+---
+
+The core Plex API is somewhat limited but basic info regarding library sizes and the number of active streams is supported. For more detailed info regarding active streams see the [Plex Tautulli widget](plex-tautulli.md).
+
+Allowed fields: `["streams", "albums", "movies", "tv"]`.
+
+```yaml
+widget:
+    type: plex
+    url: http://plex.host.or.ip:32400
+    key: mytokenhere # see https://www.plexopedia.com/plex-media-server/general/plex-token/
+```

docs/widgets/services/portainer.md

@@ -0,0 +1,16 @@
+---
+title: Portainer
+description: Portainer Widget Configuration
+---
+
+You'll need to make sure you have the correct environment set for the integration to work properly. From the Environments section inside of Portainer, click the one you'd like to connect to and observe the ID at the end of the URL (should be), something like `#!/endpoints/1`, here `1` is the value to set as the `env` value. In order to generate an API key, please follow the steps outlined here https://docs.portainer.io/api/access.
+
+Allowed fields: `["running", "stopped", "total"]`.
+
+```yaml
+widget:
+    type: portainer
+    url: https://portainer.host.or.ip:9443
+    env: 1
+    key: ptr_accesskeyaccesskeyaccesskeyaccesskey
+```

docs/widgets/services/prometheus.md

@@ -0,0 +1,12 @@
+---
+title: Prometheus
+description: Prometheus Widget Configuration
+---
+
+Allowed fields: `["targets_up", "targets_down", "targets_total"]`
+
+```yaml
+widget:
+    type: prometheus
+    url: http://prometheushost:port
+```

docs/widgets/services/prowlarr.md

@@ -0,0 +1,15 @@
+---
+title: Prowlarr
+description: Prowlarr Widget Configuration
+---
+
+Find your API key under `Settings > General`.
+
+Allowed fields: `["numberOfGrabs", "numberOfQueries", "numberOfFailGrabs", "numberOfFailQueries"]`.
+
+```yaml
+widget:
+    type: prowlarr
+    url: http://prowlarr.host.or.ip
+    key: apikeyapikeyapikeyapikeyapikey
+```

docs/widgets/services/proxmox.md

@@ -0,0 +1,50 @@
+---
+title: Proxmox
+description: Proxmox Widget Configuration
+---
+
+This widget shows the running and total counts of both QEMU VMs and LX Containers in the Proxmox cluster. It also shows the CPU and memory usage of the first node in the cluster.
+
+You will need to generate an API Token for new or an existing user. Here is an example of how to do this for a new user.
+
+1. Navigate to the Proxmox portal, click on Datacenter
+2. Expand Permissions, click on Groups
+3. Click the Create button
+4. Name the group something informative, like api-ro-users
+5. Click on the Permissions "folder"
+6. Click Add -> Group Permission
+    - Path: /
+    - Group: group from bullet 4 above
+    - Role: PVEAuditor
+    - Propagate: Checked
+7. Expand Permissions, click on Users
+8. Click the Add button
+    - User name: something informative like `api`
+    - Realm: Linux PAM standard authentication
+    - Group: group from bullet 4 above
+9. Expand Permissions, click on API Tokens
+10. Click the Add button
+    - User: user from bullet 8 above
+    - Token ID: something informative like the application or purpose like `homepage`
+    - Privilege Separation: Checked
+11. Go back to the "Permissions" menu
+12. Click Add -> API Token Permission
+    - Path: /
+    - API Token: select the Token ID created in Step 10
+    - Role: PVE Auditor
+    - Propagate: Checked
+
+Use `username@pam!Token ID` as the `username` (e.g `api@pam!homepage`) setting and `Secret` as the `password` setting.
+
+Allowed fields: `["vms", "lxc", "resources.cpu", "resources.mem"]`.
+
+You can set the optional `node` setting when you want to show metrics for a single node. By default it will show the average for the complete cluster.
+
+```yaml
+widget:
+    type: proxmox
+    url: https://proxmox.host.or.ip:8006
+    username: api_token_id
+    password: api_token_secret
+    node: pve-1 # optional
+```

docs/widgets/services/proxmoxbackupserver.md

@@ -0,0 +1,14 @@
+---
+title: Proxmox Backup Server
+description: Proxmox Backup Server Widget Configuration
+---
+
+Allowed fields: `["datastore_usage", "failed_tasks_24h", "cpu_usage", "memory_usage"]`.
+
+```yaml
+widget:
+    type: proxmoxbackupserver
+    url: https://proxmoxbackupserver.host:port
+    username: api_token_id
+    password: api_token_secret
+```

docs/widgets/services/pterodactyl.md

@@ -0,0 +1,13 @@
+---
+title: Pterodactyl
+description: Pterodactyl Widget Configuration
+---
+
+Allowed fields: `["nodes", "servers"]`
+
+```yaml
+widget:
+    type: pterodactyl
+    url: http://pterodactylhost:port
+    key: pterodactylapikey
+```

docs/widgets/services/pyload.md

@@ -0,0 +1,14 @@
+---
+title: Pyload
+description: Pyload Widget Configuration
+---
+
+Allowed fields: `["speed", "active", "queue", "total"]`.
+
+```yaml
+widget:
+    type: pyload
+    url: http://pyload.host.or.ip:port
+    username: username
+    password: password # only needed if set
+```

docs/widgets/services/qbittorrent.md

@@ -0,0 +1,16 @@
+---
+title: qBittorrent
+description: qBittorrent Widget Configuration
+---
+
+Uses the same username and password used to login from the web.
+
+Allowed fields: `["leech", "download", "seed", "upload"]`.
+
+```yaml
+widget:
+    type: qbittorrent
+    url: http://qbittorrent.host.or.ip
+    username: username
+    password: password
+```

docs/widgets/services/qnap.md

@@ -0,0 +1,22 @@
+---
+title: QNAP
+description: QNAP Widget Configuration
+---
+
+Allowed fields: `["cpuUsage", "memUsage", "systemTempC", "poolUsage", "volumeUsage"]`.
+
+```yaml
+widget:
+    type: qnap
+    url: http://qnap.host.or.ip:port
+    username: user
+    password: pass
+```
+
+If the QNAP device has multiple volumes, the _poolUsage_ will be a sum of all volumes.
+
+If only a single volume needs to be tracked, add the following to your configuration and the Widget will track this as _volumeUsage_:
+
+```yaml
+volume: Volume Name From QNAP
+```

docs/widgets/services/radarr.md

@@ -0,0 +1,18 @@
+---
+title: Radarr
+description: Radarr Widget Configuration
+---
+
+Find your API key under `Settings > General`.
+
+Allowed fields: `["wanted", "missing", "queued", "movies"]`.
+
+A detailed queue listing is disabled by default, but can be enabled with the `enableQueue` option.
+
+```yaml
+widget:
+    type: radarr
+    url: http://radarr.host.or.ip
+    key: apikeyapikeyapikeyapikeyapikey
+    enableQueue: true # optional, defaults to false
+```

docs/widgets/services/readarr.md

@@ -0,0 +1,15 @@
+---
+title: Readarr
+description: Readarr Widget Configuration
+---
+
+Find your API key under `Settings > General`.
+
+Allowed fields: `["wanted", "queued", "books"]`.
+
+```yaml
+widget:
+    type: readarr
+    url: http://readarr.host.or.ip
+    key: apikeyapikeyapikeyapikeyapikey
+```

docs/widgets/services/rutorrent.md

@@ -0,0 +1,16 @@
+---
+title: ruTorrent
+description: ruTorrent Widget Configuration
+---
+
+This requires the `httprpc` plugin to be installed and enabled, and is part of the default ruTorrent plugins. If you have not explicitly removed or disable this plugin, it should be available.
+
+Allowed fields: `["active", "upload", "download"]`.
+
+```yaml
+widget:
+    type: rutorrent
+    url: http://rutorrent.host.or.ip
+    username: username # optional, false if not used
+    password: password # optional, false if not used
+```

docs/widgets/services/sabnzbd.md

@@ -0,0 +1,15 @@
+---
+title: SABnzbd
+description: SABnzbd Widget Configuration
+---
+
+Find your API key under `Config > General`.
+
+Allowed fields: `["rate", "queue", "timeleft"]`.
+
+```yaml
+widget:
+    type: sabnzbd
+    url: http://sabnzbd.host.or.ip
+    key: apikeyapikeyapikeyapikeyapikey
+```

docs/widgets/services/scrutiny.md

@@ -0,0 +1,12 @@
+---
+title: Scrutiny
+description: Scrutiny Widget Configuration
+---
+
+Allowed fields: `["passed", "failed", "unknown"]`.
+
+```yaml
+widget:
+    type: scrutiny
+    url: http://scrutiny.host.or.ip
+```

docs/widgets/services/sonarr.md

@@ -0,0 +1,18 @@
+---
+title: Sonarr
+description: Sonarr Widget Configuration
+---
+
+Find your API key under `Settings > General`.
+
+Allowed fields: `["wanted", "queued", "series"]`.
+
+A detailed queue listing is disabled by default, but can be enabled with the `enableQueue` option.
+
+```yaml
+widget:
+    type: sonarr
+    url: http://sonarr.host.or.ip
+    key: apikeyapikeyapikeyapikeyapikey
+    enableQueue: true # optional, defaults to false
+```

docs/widgets/services/speedtest-tracker.md

@@ -0,0 +1,16 @@
+---
+title: Speedtest Tracker
+description: Speedtest Tracker Widget Configuration
+---
+
+No extra configuration is required.
+
+This widget is compatible with both [alexjustesen/speedtest-tracker](https://github.com/alexjustesen/speedtest-tracker) and [henrywhitaker3/Speedtest-Tracker](https://github.com/henrywhitaker3/Speedtest-Tracker).
+
+Allowed fields: `["download", "upload", "ping"]`.
+
+```yaml
+widget:
+    type: speedtest
+    url: http://speedtest.host.or.ip
+```