Skip to content

Commit

Permalink
doc: review documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
@bastienwirtz
bastienwirtz committed Oct 25, 2024
1 parent ea12ee5 commit c6571b4
Show file tree
Hide file tree
Showing 7 changed files with 92 additions and 98 deletions.
49 changes: 21 additions & 28 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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"
Expand Down Expand Up @@ -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

- [yaml](http://yaml.org/) file configuration
- Installable (pwa)
- Search
- Grouping
- Theme customization
- Offline health check
- keyboard shortcuts:
## Highlights

- ⚡️ 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.

Expand All @@ -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
Expand All @@ -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
Expand Down
5 changes: 2 additions & 3 deletions docs/configuration.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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)):

Expand Down Expand Up @@ -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
Expand All @@ -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).
86 changes: 45 additions & 41 deletions docs/customservices.md
View file
Original file line number Diff line number Diff line change
@@ -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)

If you experiencing any issue, please have a look to the [troubleshooting](troubleshooting.md) page.
- [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)

> [!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

Expand Down Expand Up @@ -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"
Expand Down Expand Up @@ -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 |
|--------------------|------------|-------------------------------------------------------------------|
Expand Down Expand Up @@ -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
Expand Down
2 changes: 1 addition & 1 deletion docs/development.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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">
Expand Down Expand Up @@ -49,7 +50,6 @@ export default {
</script>
```


## Themes

Themes are meant to be simple customization (written in [scss](https://sass-lang.com/documentation/syntax)).
Expand Down
7 changes: 1 addition & 6 deletions docs/kubernetes.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down Expand Up @@ -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/):

Expand All @@ -82,7 +81,3 @@ kubectl apply -f operator.yaml
### Usage

- [usage](https://github.com/rajsinghtech/homer-operator?tab=readme-ov-file#usage)




6 changes: 3 additions & 3 deletions docs/theming.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -70,7 +70,7 @@ stylesheet:
- "assets/custom.css"
```

### Customization exemple
### Customization example

#### Max width modification

Expand All @@ -80,7 +80,7 @@ body #main-section .container {
}
```

#### Background gradiant
#### Background gradient

```css
#app {
Expand Down
35 changes: 19 additions & 16 deletions docs/troubleshooting.md
View file
Original file line number Diff line number Diff line change
@@ -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):

Expand All @@ -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.
Expand All @@ -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

0 comments on commit c6571b4

Please sign in to comment.