mirror of
https://github.com/bastienwirtz/homer.git
synced 2024-11-07 08:44:00 +01:00
doc: review documentation
This commit is contained in:
Bastien Wirtz
parent
ea12ee520b
commit
c6571b48b4
47
README.md
47
README.md
@ -10,18 +10,9 @@
|
||||
<h4 align="center">
|
||||
A dead simple static <strong>HOM</strong>epage for your serv<strong>ER</strong> to keep your services on hand, from a simple <code>yaml</code> configuration file.
|
||||
</h4>
|
||||
<p align="center">
|
||||
<p align="center">
|
||||
<a href="https://www.buymeacoffee.com/bastien" target="_blank"><img src="https://cdn.buymeacoffee.com/buttons/default-yellow.png" alt="Buy Me A Coffee" height="41" width="174"></a>
|
||||
<p>
|
||||
<p align="center">
|
||||
<strong>
|
||||
<a href="https://homer-demo.netlify.app">Demo</a>
|
||||
•
|
||||
<a href="https://gitter.im/homer-dashboard/community">Chat</a>
|
||||
•
|
||||
<a href="#getting-started">Getting started</a>
|
||||
</strong>
|
||||
</p>
|
||||
<p align="center">
|
||||
<a href="https://opensource.org/licenses/Apache-2.0"><img
|
||||
alt="License: Apache 2"
|
||||
@ -51,26 +42,28 @@
|
||||
- [Kubernetes Installation](docs/kubernetes.md)
|
||||
- [Configuration](docs/configuration.md)
|
||||
- [Theming](docs/theming.md)
|
||||
- [Custom services](docs/customservices.md)
|
||||
- [Smart cards](docs/customservices.md)
|
||||
- [Tips & tricks](docs/tips-and-tricks.md)
|
||||
- [Development](docs/development.md)
|
||||
- [Troubleshooting](docs/troubleshooting.md)
|
||||
|
||||
## Features
|
||||
## Highlights
|
||||
|
||||
- [yaml](http://yaml.org/) file configuration
|
||||
- Installable (pwa)
|
||||
- Search
|
||||
- Grouping
|
||||
- Theme customization
|
||||
- Offline health check
|
||||
- keyboard shortcuts:
|
||||
- ⚡️ Lightweight & Fast
|
||||
- 🥱 Low / No maintenance
|
||||
- 📄 Simple [yaml](http://yaml.org/) file configuration
|
||||
- ➕ Installable (pwa)
|
||||
- 🧠 Smart cards
|
||||
- 🔍️ Fuzzy search
|
||||
- 📂 Multi pages & item grouping
|
||||
- 🎨 Theme customization
|
||||
- ⌨️ keyboard shortcuts:
|
||||
- `/` Start searching.
|
||||
- `Escape` Stop searching.
|
||||
- `Enter` Open the first matching result (respects the bookmark's `_target` property).
|
||||
- `Alt`/`Option` + `Enter` Open the first matching result in a new tab.
|
||||
|
||||
## Getting started
|
||||
## Get started
|
||||
|
||||
Homer is a full static html/js dashboard, based on a simple yaml configuration file. See [documentation](docs/configuration.md) for information about the configuration (`assets/config.yml`) options.
|
||||
|
||||
@ -88,18 +81,18 @@ docker run -d \
|
||||
|
||||
The container will run using a user uid and gid 1000. Add `--user <your-UID>:<your-GID>` 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: *<http://my-domain/homer>*), 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
|
||||
|
||||
@ -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).
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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
|
||||
<template>
|
||||
<Generic :item="item">
|
||||
@ -49,7 +50,6 @@ export default {
|
||||
</script>
|
||||
```
|
||||
|
||||
|
||||
## Themes
|
||||
|
||||
Themes are meant to be simple customization (written in [scss](https://sass-lang.com/documentation/syntax)).
|
||||
|
||||
@ -2,7 +2,6 @@
|
||||
|
||||
We have different solution to install Homer on Kubernetes Cluster, each solution responds to a specific need.
|
||||
|
||||
|
||||
## Table of Contents
|
||||
|
||||
- [Helm Chart](#helm-chart)
|
||||
@ -58,7 +57,7 @@ helm install homer bananaops/homer-k8s -f values.yaml
|
||||
|
||||
## Controller Annotations
|
||||
|
||||
To deploy Homer in Kubernetes with controller to check ingress annoation and modify homer configuration
|
||||
To deploy Homer in Kubernetes with controller to check ingress annotation and modify homer configuration
|
||||
|
||||
Thanks to [@paulfantom](https://github.com/paulfantom) [homer-reloader](https://github.com/paulfantom/homer-reloader/tree/main/):
|
||||
|
||||
@ -82,7 +81,3 @@ kubectl apply -f operator.yaml
|
||||
### Usage
|
||||
|
||||
- [usage](https://github.com/rajsinghtech/homer-operator?tab=readme-ov-file#usage)
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
@ -28,7 +28,7 @@ Default colors and background can be customized for each theme variant (light an
|
||||
| `card-shadow` | `--card-shadow` | Service card `box-shadow` |
|
||||
| `link` | `--link` | Links color (footer & message), service card icon color |
|
||||
| `link-hover` | `--link-hover` | Links hover color (footer & message), service card icon hover color |
|
||||
| `background-image` | `--background-image` | page background image url (when used in css, set `url(<image-url>)` insted of just the url. see exemple below)|
|
||||
| `background-image` | `--background-image` | page background image url (when used in css, set `url(<image-url>)` instead of just the url. see example below)|
|
||||
|
||||
|
||||
YAML example
|
||||
@ -70,7 +70,7 @@ stylesheet:
|
||||
- "assets/custom.css"
|
||||
```
|
||||
|
||||
### Customization exemple
|
||||
### Customization example
|
||||
|
||||
#### Max width modification
|
||||
|
||||
@ -80,7 +80,7 @@ body #main-section .container {
|
||||
}
|
||||
```
|
||||
|
||||
#### Background gradiant
|
||||
#### Background gradient
|
||||
|
||||
```css
|
||||
#app {
|
||||
|
||||
@ -1,6 +1,6 @@
|
||||
# Troubleshooting
|
||||
|
||||
## My docker container refuse to start / is stuck at restarting.
|
||||
## My docker container refuse to start / is stuck at restarting
|
||||
|
||||
You might be facing a permission issue. First of all, check your container logs (adjust the container name if necessary):
|
||||
|
||||
@ -12,19 +12,20 @@ Assets directory not writable. Check assets directory permissions & docker user
|
||||
|
||||
In this case you need to make sure your mounted assets directory have the same GID / UID the container user have (default 1000:1000), and that the read and write permission is granted for the user or the group.
|
||||
|
||||
You can either:
|
||||
You can either:
|
||||
|
||||
- Update your assets directory permissions (ex: `chown -R 1000:1000 /your/assets/folder/`, `chmod -R u+rw /your/assets/folder/`)
|
||||
- Change the docker user by using the `--user` arguments with docker cli or `user: 1000:1000` with docker compose.
|
||||
|
||||
⚠️ Notes:
|
||||
|
||||
- **Do not** use env var to set the GID / UID of the user running container. Use the Docker `user` option.
|
||||
- **Do not** use 0:0 as a user value, it would be a security risk, and it's not guaranty to work.
|
||||
> [!NOTE]
|
||||
>
|
||||
> - **Do not** use env var to set the GID / UID of the user running container. Use the Docker `user` option.
|
||||
> - **Do not** use 0:0 as a user value, it would be a security risk, and it's not guaranty to work.
|
||||
|
||||
Check this [thread](https://github.com/bastienwirtz/homer/issues/459) for more information about debugging
|
||||
permission issues.
|
||||
|
||||
## My custom service card doesn't work, nothing appears or offline status is displayed (pi-hole, sonarr, ping, ...)
|
||||
## My service card doesn't work, nothing appears or offline status is displayed (pi-hole, sonarr, ping, ...)
|
||||
|
||||
You might be facing a [CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) (Cross Origin Request Sharing) issue.
|
||||
It happens when the targeted service is hosted on a different domain or port.
|
||||
@ -38,21 +39,23 @@ Access to fetch at 'https://<target-service>' from origin 'https://<homer>' has
|
||||
|
||||
To resolve this, you can either:
|
||||
|
||||
* Host all your target service under the same domain & port.
|
||||
* Modify the target server configuration so that the response of the server included following header- `Access-Control-Allow-Origin: *` (<https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS#simple_requests>). It might be an option in the targeted service, otherwise depending on how the service is hosted, the proxy or web server can seamlessly add it.
|
||||
* Use a cors proxy server like [`cors-container`](https://github.com/imjacobclark/cors-container), [`cors-anywhere`](https://github.com/Rob--W/cors-anywhere) or many others.
|
||||
- Host all your target service under the same domain & port.
|
||||
- Modify the target server configuration so that the response of the server included following header- `Access-Control-Allow-Origin: *` (<https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS#simple_requests>). It might be an option in the targeted service, otherwise depending on how the service is hosted, the proxy or web server can seamlessly add it.
|
||||
- Use a cors proxy server like [`cors-container`](https://github.com/imjacobclark/cors-container), [`cors-anywhere`](https://github.com/Rob--W/cors-anywhere) or many others.
|
||||
|
||||
## I am using an authentication proxy and homer says I am offline
|
||||
|
||||
This should be a configuration issue.
|
||||
* Make sure the option `connectivityCheck` is set to `true` in configuration.
|
||||
* Check your proxy configuration, the expected behavior is to redirect user using a 302 to the login page when user is not authenticated.
|
||||
|
||||
- Make sure the option `connectivityCheck` is set to `true` in configuration.
|
||||
- Check your proxy configuration, the expected behavior is to redirect user using a 302 to the login page when user is not authenticated.
|
||||
|
||||
## I put my API key into the OpenWeather service and it still isn't working
|
||||
|
||||
If you have just made an OpenWeatherMap account and/or a newly-made API key, there is a high chance that you need to wait for it to be activated (often a few hours). If after waiting it still doesn't work, make sure to check the location you have provided since it may be an invalid location.
|
||||
|
||||
For some basic debugging steps, you can:
|
||||
* Check with a large city such as Amsterdam as the specified location within your configuration.
|
||||
* Make sure your web browser is running the latest version of the homer configuration after updating the location (Ctrl + Shift + R).
|
||||
* Check for errors within the browser console (Ctrl + Shift + I) relating to api.openweathermap.org
|
||||
For some basic debugging steps, you can:
|
||||
|
||||
- Check with a large city such as Amsterdam as the specified location within your configuration.
|
||||
- Make sure your web browser is running the latest version of the homer configuration after updating the location (Ctrl + Shift + R).
|
||||
- Check for errors within the browser console (Ctrl + Shift + I) relating to api.openweathermap.org
|
||||
|
||||
Loading…
Reference in New Issue
Block a user