From c6571b48b4a7cb668c68bccc71a8d077ec8d3aea Mon Sep 17 00:00:00 2001 From: Bastien Wirtz Date: Fri, 25 Oct 2024 21:58:32 +0200 Subject: [PATCH] doc: review documentation --- README.md | 47 ++++++++++------------- docs/configuration.md | 5 +-- docs/customservices.md | 84 +++++++++++++++++++++-------------------- docs/development.md | 2 +- docs/kubernetes.md | 7 +--- docs/theming.md | 6 +-- docs/troubleshooting.md | 35 +++++++++-------- 7 files changed, 90 insertions(+), 96 deletions(-) diff --git a/README.md b/README.md index 660b59c..ea4eb72 100644 --- a/README.md +++ b/README.md @@ -10,18 +10,9 @@

A dead simple static HOMepage for your servER to keep your services on hand, from a simple yaml configuration file.

-

+

Buy Me A Coffee

-

- - Demo - • - Chat - • - Getting started - -

License: Apache 2:` to the docker command to adjust it. Make sure this match the ownership of your assets directory. -**Environment variables:** +**Environment variables:** -* **`INIT_ASSETS`** (default: `1`) +- **`INIT_ASSETS`** (default: `1`) Install example configuration file & assets (favicons, ...) to help you get started. -* **`SUBFOLDER`** (default: `null`) -If you would like to host Homer in a subfolder, (ex: *http://my-domain/**homer***), set this to the subfolder path (ex `/homer`). +- **`SUBFOLDER`** (default: `null`) +If you would like to host Homer in a subfolder, (ex: **), set this to the subfolder path (ex `/homer`). -* **`PORT`** (default: `8080`) +- **`PORT`** (default: `8080`) If you would like to change internal port of Homer from default `8080` to your port choice. -* **`IPV6_DISABLE`** (default: 0) +- **`IPV6_DISABLE`** (default: 0) Set to `1` to disable listening on IPv6. #### With docker-compose @@ -122,7 +115,7 @@ wget https://github.com/bastienwirtz/homer/releases/latest/download/homer.zip unzip homer.zip -d homer cd homer cp assets/config.yml.dist assets/config.yml -npx serve # or python -m http.server 8010 or apache, nginx ... +npx serve # or python -m http.server 8010 or any web server. ``` ### Build manually diff --git a/docs/configuration.md b/docs/configuration.md index 9a88e1e..15976ea 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -154,7 +154,7 @@ services: # background: red # optional color for card to set color directly without custom stylesheet ``` -View **[Custom Services](customservices.md)** for details about all available custom services (like `PiHole`) and how to configure them. +View **[smart cards](customservices.md)** for details about all available cards (like `PiHole`) and how to configure them. If you choose to fetch message information from an endpoint, the output format should be as follows (or you can [custom map fields as shown in tips-and-tricks](./tips-and-tricks.md#mapping-fields)): @@ -183,7 +183,7 @@ You can read the [bulma modifiers page](https://bulma.io/documentation/modifiers ## Theming & customization See `colors` settings in the configuration example above. -Favicon et application icon (pwa) are located in the `assets/icons` directory and can be replaced by any image you want (just keep the same name & size). +Favicon and application icon (pwa) are located in the `assets/icons` directory and can be replaced by any image you want (just keep the same name & size). The `/assets/manifest.json` can also be edited to change the app (pwa) name, description and other settings. ### Community theme @@ -192,7 +192,6 @@ The `/assets/manifest.json` can also be edited to change the app (pwa) name, des - [Homer Theme v2](https://github.com/walkxcode/homer-theme) by [walkxcode](https://github.com/walkxcode) - [Catppuccin theme](https://github.com/mrpbennett/catppucin-homer) by [@mrpbenett](https://github.com/mrpbennett) - ## PWA Icons See icons documentation [here](https://github.com/bastienwirtz/homer/blob/main/public/assets/icons/README.md). diff --git a/docs/customservices.md b/docs/customservices.md index fb038d1..bd024f7 100644 --- a/docs/customservices.md +++ b/docs/customservices.md @@ -1,45 +1,49 @@ -# Custom Services +# Smart cards -Some service can use a specific a component that provides some extra features by adding a `type` key to the service yaml -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. +Some cards can use a specific a component that provides some extra features by adding a `type` key to the service yaml +configuration and other parameters when needed. -Available services are in `src/components/`. Here is an overview of all custom services that are available +> [!WARNING] +> Note that `config.yml` is exposed at `/assets/config.yml` via HTTP and any sensitive information, like api keys, +> included in the configuration file is exposed to anyone who can access the homer instance. Only include an api key +> 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 smart cards that are available within Homer: -- [Custom Services](#custom-services) - - [Common options](#common-options) - - [PiHole](#pihole) - - [OpenWeatherMap](#openweathermap) - - [Medusa](#medusa) - - [Lidarr, Prowlarr, Sonarr, Readarr and Radarr](#lidarr-prowlarr-sonarr-readarr-and-radarr) - - [PaperlessNG](#paperlessng) - - [Ping](#ping) - - [Prometheus](#prometheus) - - [AdGuard Home](#adguard-home) - - [Portainer](#portainer) - - [Emby / Jellyfin](#emby--jellyfin) - - [Uptime Kuma](#uptime-kuma) - - [Tautulli](#tautulli) - - [Mealie](#mealie) - - [Healthchecks](#healthchecks) - - [Proxmox](#proxmox) - - [rTorrent](#rtorrent) - - [qBittorrent](#qbittorrent) - - [CopyToClipboard](#copy-to-clipboard) - - [Speedtest Tracker](#SpeedtestTracker) - - [What's Up Docker](#whats-up-docker) - - [SABnzbd](#sabnzbd) - - [OctoPrint](#octoprint) - - [Tdarr](#tdarr) - - [PiAlert](#pialert) - - [Immich](#immich) - - [OpenHAB](#openhab) - - [Jellystat](#jellystat) - - [Home Assistant](#home-assistant) +- [Common options](#common-options) +- [PiHole](#pihole) +- [OpenWeatherMap](#openweathermap) +- [Medusa](#medusa) +- [Lidarr, Prowlarr, Sonarr, Readarr and Radarr](#lidarr-prowlarr-sonarr-readarr-and-radarr) +- [PaperlessNG](#paperlessng) +- [Ping](#ping) +- [Prometheus](#prometheus) +- [AdGuard Home](#adguard-home) +- [Portainer](#portainer) +- [Emby / Jellyfin](#emby--jellyfin) +- [Uptime Kuma](#uptime-kuma) +- [Tautulli](#tautulli) +- [Mealie](#mealie) +- [Healthchecks](#healthchecks) +- [Proxmox](#proxmox) +- [rTorrent](#rtorrent) +- [qBittorrent](#qbittorrent) +- [CopyToClipboard](#copy-to-clipboard) +- [Speedtest Tracker](#SpeedtestTracker) +- [What's Up Docker](#whats-up-docker) +- [SABnzbd](#sabnzbd) +- [OctoPrint](#octoprint) +- [Tdarr](#tdarr) +- [PiAlert](#pialert) +- [Immich](#immich) +- [OpenHAB](#openhab) +- [Jellystat](#jellystat) +- [Home Assistant](#home-assistant) -If you experiencing any issue, please have a look to the [troubleshooting](troubleshooting.md) page. +> [!IMPORTANT] +> Using smart cards will probably requires +> If you experiencing any issue, please have a look to the [troubleshooting](troubleshooting.md#my-service-card-doesnt-work-nothing-appears-or-offline-status-is-displayed-pi-hole-sonarr-ping-) page. ## Common options @@ -162,7 +166,7 @@ For Prometheus you need to set the type to Prometheus and provide a url. ``` ## AdGuard Home -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. +For AdGuard Home you need to set the type to AdGuard, if you have some issues as 403 responses on requests you need to provide authentication in headers for locations needed as below. ```yaml - name: "Adguard" @@ -291,7 +295,7 @@ servers can be found at https://enable-cors.org/server.html. 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). -The API Token (or the user asigned to that token if not separated permissions is checked) are this: +The API Token (or the user assigned to that token if not separated permissions is checked) are this: | Path | Permission | Comments | |--------------------|------------|-------------------------------------------------------------------| @@ -467,7 +471,7 @@ To enable cors on OpenHAB, edit your services/runtime.cfg and uncomment or add t ## Jellystat -The Jellystat serice display the number of concurrent streams on your jellyfin server. +The Jellystat service display the number of concurrent streams on your jellyfin server. The Jellystat server must be running behind a reverse proxy to add some cors headers: - Access-Control-Allow-Origin: ${your_domain} - Access-Control-Allow-Headers: Authorization diff --git a/docs/development.md b/docs/development.md index 5c05bcc..7d02a49 100644 --- a/docs/development.md +++ b/docs/development.md @@ -19,6 +19,7 @@ Each one is **optional**, and will display the usual information if omitted. Each service must implement the `item` [property](https://vuejs.org/v2/guide/components-props.html) and bind it the Generic component if used. ### Skeleton + ```Vue