X-Git-Url: https://git.immae.eu/?a=blobdiff_plain;f=docs%2Fcustomservices.md;h=91c4051e9d83154eee52ce406a49403bd1a9285b;hb=8ede30411ed1726ed3885fd617364924e677abc2;hp=4a023a145fdf8cd3c18cc9b69b516679e34e0f7c;hpb=7129af3bda3a7a7d506bd8c8f122ad8995c2906c;p=github%2Fbastienwirtz%2Fhomer.git diff --git a/docs/customservices.md b/docs/customservices.md index 4a023a1..91c4051 100644 --- a/docs/customservices.md +++ b/docs/customservices.md @@ -1,11 +1,27 @@ # Custom Services Some service can use a specific a component that provides some extra features by adding a `type` key to the service yaml -configuration. Available services are in `src/components/`. Here is an overview of all custom services that are available +configuration and, where applicable, an apikey. Note that config.yml is exposed at /assets/config.yml via HTTP and any +apikey included in the configuration file is exposed to anyone who can access the homer instance. Only include an apikey +if your homer instance is secured behind some form of authentication or access restriction. + +Available services are in `src/components/`. Here is an overview of all custom services that are available within Homer. If you experiencing any issue, please have a look to the [troubleshooting](troubleshooting.md) page. + +## Common options + +```yaml +- name: "My Service" + logo: "assets/tools/sample.png" + url: "http://my-service-link" + endpoint: "http://my-service-endpoint" # Optional: alternative base URL used to fetch service data is necessary. + useCredentials: false # Optional: Override global proxy.useCredentials configuration. + type: "" +``` + ## PiHole Using the PiHole service you can display info about your local PiHole instance right on your Homer dashboard. @@ -13,12 +29,11 @@ Using the PiHole service you can display info about your local PiHole instance r The following configuration is available for the PiHole service. ```yaml - items: - - name: "Pi-hole" - logo: "assets/tools/sample.png" - # subtitle: "Network-wide Ad Blocking" # optional, if no subtitle is defined, PiHole statistics will be shown - url: "http://192.168.0.151/admin" - type: "PiHole" +- name: "Pi-hole" + logo: "assets/tools/sample.png" + # subtitle: "Network-wide Ad Blocking" # optional, if no subtitle is defined, PiHole statistics will be shown + url: "http://192.168.0.151/admin" + type: "PiHole" ``` ## OpenWeatherMap @@ -27,14 +42,13 @@ Using the OpenWeatherMap service you can display weather information about a giv The following configuration is available for the OpenWeatherMap service: ```yaml -items: - - name: "Weather" - location: "Amsterdam" # your location. - locationId: "2759794" # Optional: Specify OpenWeatherMap city ID for better accuracy - apiKey: "<---insert-api-key-here--->" # insert your own API key here. Request one from https://openweathermap.org/api. - units: "metric" # units to display temperature. Can be one of: metric, imperial, kelvin. Defaults to kelvin. - background: "square" # choose which type of background you want behind the image. Can be one of: square, cicle, none. Defaults to none. - type: "OpenWeather" +- name: "Weather" + location: "Amsterdam" # your location. + locationId: "2759794" # Optional: Specify OpenWeatherMap city ID for better accuracy + apikey: "<---insert-api-key-here--->" # insert your own API key here. Request one from https://openweathermap.org/api. + units: "metric" # units to display temperature. Can be one of: metric, imperial, kelvin. Defaults to kelvin. + background: "square" # choose which type of background you want behind the image. Can be one of: square, cicle, none. Defaults to none. + type: "OpenWeather" ``` **Remarks:** @@ -46,30 +60,68 @@ This service displays News (grey), Warning (orange) or Error (red) notifications Two lines are needed in the config.yml : ```yaml -type: "Medusa" -apikey: "01234deb70424befb1f4ef6a23456789" + type: "Medusa" + apikey: "01234deb70424befb1f4ef6a23456789" ``` The url must be the root url of Medusa application. The Medusa API key can be found in General configuration > Interface. It is needed to access Medusa API. -## Sonarr/Radarr +## Lidarr, Sonarr and Radarr -This service displays Activity (blue), Warning (orange) or Error (red) notifications bubbles from the Radarr/Sonarr application. +This service displays Activity (blue), Warning (orange) or Error (red) notifications bubbles from the Lidarr, Radarr or Sonarr application. Two lines are needed in the config.yml : ```yaml -type: "Radarr" or "Sonarr" -apikey: "01234deb70424befb1f4ef6a23456789" + type: "Lidarr", "Radarr" or "Sonarr" + apikey: "01234deb70424befb1f4ef6a23456789" ``` -The url must be the root url of Radarr/Sonarr application. -The Radarr/Sonarr API key can be found in Settings > General. It is needed to access the API. +The url must be the root url of Lidarr, Radarr or Sonarr application. +The Lidarr, Radarr or Sonarr API key can be found in Settings > General. It is needed to access the API. +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: + +```yaml +- name: "Radarr" + type: "Radarr" + url: "http://localhost:8989/" + apikey: "MY-SUPER-SECRET-API-KEY" + target: "_blank" # optional html tag target attribute + legacyApi: true +``` ## PaperlessNG -For Paperless you need an API-Key which you have to store at the item in the field `apikey`. +This service displays total number of documents stored. Two lines are required: + +```yaml + type: "PaperlessNG" + apikey: "0123456789abcdef123456789abcdef" +``` + +API key can be generated in Settings > Administration > Auth Tokens ## Ping -For Ping you need an API-Key which you have to store at the item in the field `apikey`. +For Ping you need to set the type to Ping and provide a url. + +```yaml +- name: "Awesome app" + type: Ping + logo: "assets/tools/sample.png" + subtitle: "Bookmark example" + tag: "app" + url: "https://www.reddit.com/r/selfhosted/" +``` + +## Prometheus + +For Prometheus you need to set the type to Prometheus and provide a url. + +```yaml +- name: "Prometheus" + type: Prometheus + logo: "assets/tools/sample.png" + url: "http://192.168.0.151/" + # subtitle: "Monitor data server" +```