# Technical Documentation: bastienwirtz/homer
> ℹ️ **Provenance:** Hybrid Fusion: `bastienwirtz/homer` (README + 10 In-Tree Chapters) · [CodeWiki Reference](https://codewiki.google/github.com/bastienwirtz/homer) · Recency: Active (< 180 days)
## 1. Project Overview & Quickstart (bastienwirtz/homer)
Homer
A dead simple static **HOM**epage for your serv**ER** to keep your services on hand, from a simple `yaml` configuration file.
## 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 (or Option) + Enter Open the first matching result in a new tab.
## Table of Contents
- [Getting started](#get-started)
- [Kubernetes Installation](docs/kubernetes.md)
- [Configuration](docs/configuration.md)
- [Theming](docs/theming.md)
- [Smart cards](docs/customservices.md)
- [Tips & tricks](docs/tips-and-tricks.md)
- [Development](docs/development.md)
- [Troubleshooting](docs/troubleshooting.md)
## 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.
It's meant to be served by an HTTP server, **it will not work if you open the index.html directly over file:// protocol**.
### Using docker
The configuration directory is bind mounted to make your dashboard easy to maintain.
**Start the container with `docker run`**
```sh
# Make sure your local config directory exists
docker run -d \
--name homer \
-p 8080:8080 \
--mount type=bind,source="/path/to/config/dir",target=/www/assets \
--restart=unless-stopped \
b4bz/homer:latest
```
> [!NOTE]
> The container will run using a user uid and gid 1000 by default, add `--user :` to the docker command to adjust it if necessary. Make sure this match the permissions of your assets directory.
**or `docker-compose`**
```yaml
services:
homer:
image: b4bz/homer
container_name: homer
volumes:
- /path/to/config/dir:/www/assets # Make sure your local config directory exists
ports:
- 8080:8080
user: 1000:1000 # default
environment:
- INIT_ASSETS=1 # default, requires the config directory to be writable for the container user (see user option)
restart: unless-stopped
```
**Environment variables:**
- **`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: **), set this to the subfolder path (ex `/homer`).
- **`PORT`** (default: `8080`)
If you would like to change internal port of Homer from default `8080` to your port choice.
- **`IPV6_DISABLE`** (default: 0)
Set to `1` to disable listening on IPv6.
### Using the release tarball (prebuilt, ready to use)
Download and extract the latest release (`homer.zip`) from the [release page](https://github.com/bastienwirtz/homer/releases), rename the `assets/config.yml.dist` file to `assets/config.yml`, and put it behind a web server.
```sh
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
pnpx http-server # or python -m http.server 8010 or any web server.
```
### Build manually
```sh
pnpm install
pnpm build
```
Then your dashboard is ready to use in the `/dist` directory.
## 2. In-Tree Documentation Chapters (bastienwirtz/homer)
## File: README.md
Homer
A dead simple static **HOM**epage for your serv**ER** to keep your services on hand, from a simple `yaml` configuration file.
## 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 (or Option) + Enter Open the first matching result in a new tab.
## Table of Contents
- [Getting started](#get-started)
- [Kubernetes Installation](docs/kubernetes.md)
- [Configuration](docs/configuration.md)
- [Theming](docs/theming.md)
- [Smart cards](docs/customservices.md)
- [Tips & tricks](docs/tips-and-tricks.md)
- [Development](docs/development.md)
- [Troubleshooting](docs/troubleshooting.md)
## 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.
It's meant to be served by an HTTP server, **it will not work if you open the index.html directly over file:// protocol**.
### Using docker
The configuration directory is bind mounted to make your dashboard easy to maintain.
**Start the container with `docker run`**
```sh
# Make sure your local config directory exists
docker run -d \
--name homer \
-p 8080:8080 \
--mount type=bind,source="/path/to/config/dir",target=/www/assets \
--restart=unless-stopped \
b4bz/homer:latest
```
> [!NOTE]
> The container will run using a user uid and gid 1000 by default, add `--user :` to the docker command to adjust it if necessary. Make sure this match the permissions of your assets directory.
**or `docker-compose`**
```yaml
services:
homer:
image: b4bz/homer
container_name: homer
volumes:
- /path/to/config/dir:/www/assets # Make sure your local config directory exists
ports:
- 8080:8080
user: 1000:1000 # default
environment:
- INIT_ASSETS=1 # default, requires the config directory to be writable for the container user (see user option)
restart: unless-stopped
```
**Environment variables:**
- **`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: **), set this to the subfolder path (ex `/homer`).
- **`PORT`** (default: `8080`)
If you would like to change internal port of Homer from default `8080` to your port choice.
- **`IPV6_DISABLE`** (default: 0)
Set to `1` to disable listening on IPv6.
### Using the release tarball (prebuilt, ready to use)
Download and extract the latest release (`homer.zip`) from the [release page](https://github.com/bastienwirtz/homer/releases), rename the `assets/config.yml.dist` file to `assets/config.yml`, and put it behind a web server.
```sh
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
pnpx http-server # or python -m http.server 8010 or any web server.
```
### Build manually
```sh
pnpm install
pnpm build
```
Then your dashboard is ready to use in the `/dist` directory.
---
## File: docs/configuration.md
# Configuration
Homer relies on a single [yaml](http://yaml.org/) configuration file, located in the `/assets` directory.
`.dist` sample configuration files are available to help you get started. Alternatively, the example below can be
copied into the config file.
> [!NOTE]
> On docker installations, the sample configuration is automatically installed when no configuration is found **if**
> the configuration directory is writable to the docker user. If no configuration has been installed, check your
> container logs and your mounted configuration directory ownership & permissions
```
/* Detailed source-code truncated for AI context efficiency. */
```
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)):
```json
{
"style": null,
"title": "Lorem ipsum 42",
"content": "LA LA LA Lorem ipsum dolor sit amet, ....."
}
```
`null` value or missing keys will be ignored and value from the `config.yml` will be used if available.
Empty values (either in `config.yml` or the endpoint data) will hide the element (ex: set `"title": ""` to hide the title bar).
## Connectivity checks
As a webapp (PWA) the dashboard can still be displayed when your homer server is offline.
The connectivity checker periodically sends a HEAD request bypassing the PWA cache to the dashboard page to make sure it's still reachable.
It can be useful when you access your dashboard through a VPN or ssh tunnel for example, to know if your connection is up. It also helps when using an authentication proxy, it will reload the page if the authentication expires (when a redirect is send in response to the HEAD request).
## Style Options
Homer uses [bulma CSS](https://bulma.io/), which provides a [modifiers syntax](https://bulma.io/documentation/start/syntax/). You'll notice in the config there is a `tagstyle` option. It can be set to any of the bulma modifiers. You'll probably want to use one of these 4 main colors:
- `is-info` (blue)
- `is-success` (green)
- `is-warning` (yellow)
- `is-danger` (red)
You can read the [bulma modifiers page](https://bulma.io/documentation/start/syntax/) for other options regarding size, style, or state.
## Theming & customization
See `colors` settings in the configuration example above.
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
- [Catppuccin theme](https://github.com/mrpbennett/catppucin-homer) by [@mrpbenett](https://github.com/mrpbennett)
- [DietPi theme](https://codeberg.org/Cs137/homer-theme-dietpi) by [@Cs137](https://codeberg.org/Cs137)
- [Dracula theme](https://draculatheme.com/homer) by [@Tuetenk0pp](https://github.com/Tuetenk0pp)
- [Homer Theme v2](https://github.com/walkxcode/homer-theme) by [@walkxcode](https://github.com/walkxcode)
## PWA Icons
See icons documentation [here](https://github.com/bastienwirtz/homer/blob/main/public/assets/icons/README.md).
---
## File: docs/customservices.md
# Smart cards
Smart cards provide specific integration for external services. They display additional information and extra features beyond basic service card. Smart cards are enabled by adding a `type` key to the service item in your YAML configuration.
Each service integration has different requirements and may need additional configuration parameters (see card list below).
> [!WARNING]
> Your `config.yml` file is exposed at `/assets/config.yml` via HTTP. Any sensitive information (like API keys)
> in this file is visible to anyone who can access your Homer instance. Only include API keys if your Homer
> instance is protected by authentication or access controls **or use a proxy like [`CORSair`](https://github.com/bastienwirtz/corsair)
> to inject your credentials safely**, using environment variable on the server side.
Available services are located in `src/components/`:
- [Common options](#common-options)
- [AdGuard Home](#adguard-home)
- [CopyToClipboard](#copy-to-clipboard)
- [Docuseal](#docuseal)
- [Docker Socket Proxy](#docker-socket-proxy)
- [Emby / Jellyfin](#emby--jellyfin)
- [FreshRSS](#freshrss)
- [Gatus](#gatus)
- [Gitea / Forgejo](#gitea--forgejo)
- [Glances](#glances)
- [Gotify](#gotify)
- [Healthchecks](#healthchecks)
- [Hyper HDR](#hyper-hdr)
- [Home Assistant](#home-assistant)
- [Immich](#immich)
- [Jellystat](#jellystat)
- [Lidarr, Prowlarr, Sonarr, Readarr and Radarr](#lidarr-prowlarr-sonarr-readarr-and-radarr)
- [LibrisLog](#librislog)
- [Linkding](#linkding)
- [Matrix](#matrix)
- [Mealie](#mealie)
- [Medusa](#medusa)
- [Miniflux](#miniflux)
- [NetAlertx](#netalertx)
- [Nextcloud](#nextcloud)
- [OctoPrint / Moonraker](#octoprintmoonraker)
- [Olivetin](#olivetin)
- [OpenHAB](#openhab)
- [OpenWeatherMap](#openweathermap)
- [Paperless-NGX](#paperless-ngx)
- [PeaNUT](#peanut)
- [PiAlert](#pialert)
- [PiHole](#pihole)
- [Ping](#ping)
- [Plex](#plex)
- [Portainer](#portainer)
- [Prometheus](#prometheus)
- [Proxmox](#proxmox)
- [qBittorrent](#qbittorrent)
- [rTorrent](#rtorrent)
- [SABnzbd](#sabnzbd)
- [Scrutiny](#scrutiny)
- [Speedtest Tracker](#speedtesttracker)
- [Tautulli](#tautulli)
- [Tdarr](#tdarr)
- [Traefik](#traefik)
- [Transmission](#transmission)
- [TrueNas Scale](#truenas-scale)
- [Uptime Kuma](#uptime-kuma)
- [Vaultwarden](#vaultwarden)
- [Wallabag](#wallabag)
- [What's Up Docker](#whats-up-docker)
> [!IMPORTANT]
> Smart cards that interact with external services are subject to CORS restrictions, therefore require one of the following:
>
> - All services hosted on the **same domain** as Homer (mydomain.tld/pihole, mydomain.tld/proxmox) to avoid cross-domain request entirely.
> - All services configured to **accept cross-site requests** by sending the necessary CORS headers (either directly in service configuration or via proxy).
> - **Use a proxy** to add the necessary CORS headers (lot of options, some of them described [here](https://enable-cors.org/server.html). Also check [`CORSair`](https://github.com/bastienwirtz/corsair), a light and simple solution).
>
> If you experience any issues, see the [troubleshooting](troubleshooting.md#my-service-card-doesnt-work-nothing-appears-or-offline-status-is-displayed-pi-hole-sonarr-ping-) page.
## Common options
```yaml
- name: "My Service"
type: ""
logo: "assets/tools/sample.png" # Optional
url: https://my-service.url # Optional: Card link and API base url unless 'endpoint' is provided (see below)
endpoint: https://my-service-api.url # Optional: alternative base URL used to fetch service data when necessary.
useCredentials: false # Optional: Override global proxy.useCredentials configuration.
headers: # Optional: Override global proxy.headers configuration.
```
If a subtitle is provided, (using the `subtitle` configuration key), **it will override (hide)** any custom information displayed on the subtitle line by the custom integration.
> [!TIP]
> **Auto refresh of the card data**: Some cards support periodic update (see indication in detail below). It can be enabled or disabled globally for all service, or individually for each service using the `updateIntervalMs` configuration option.
## AdGuard Home
Displays AdGuard Home protection status and blocked query statistics.
```yaml
- name: "AdGuard Home"
type: "AdGuardHome"
logo: "assets/tools/sample.png"
url: https://my-service.url
```
> **Note**: If AdGuard Home’s web user is password-protected, you must pass Authorization HTTP header along with all requests. It can be done using a proxy or adding the following to the item configuration:
>
> ```yaml
> headers:
> Authorization: "Basic "
> ```
Auto refresh is supported by this integration.
## Copy to Clipboard
Displays a service card with a copy button that copies the specified text to your clipboard when clicked.
```yaml
- name: "Copy me!"
type: "CopyToClipboard"
logo: "assets/tools/sample.png"
subtitle: "Click the copy icon to copy text"
clipboard: "this text will be copied to your clipboard"
url: "https://optional-link.com" # optional: opens when clicking the card (not the copy button)
```
## Docker Socket Proxy
Displays counts of running, stopped, and error containers from Docker Socket Proxy.
```yaml
- name: "Docker"
type: "DockerSocketProxy"
logo: "assets/tools/sample.png"
endpoint: "https://my-service-api.url:port"
```
Auto refresh is supported by this integration.
## Docuseal
Displays the Docuseal version.
```yaml
- name: Docuseal
type: Docuseal
logo: "assets/tools/sample.png"
url: https://my-service.url
```
## Emby / Jellyfin
Displays stats from your Emby or Jellyfin server.
The `libraryType` configuration let you choose which stats to show.
```yaml
- name: "Emby"
type: "Emby"
logo: "assets/tools/sample.png"
url: https://my-service.url
apikey: "<---insert-api-key-here--->"
libraryType: "music" # Choose which stats to show. Can be one of: music, series or movies.
```
Auto refresh is supported by this integration.
## FreshRSS
Displays unread article count and total subscriptions from your FreshRSS server.
```yaml
- name: "FreshRSS"
type: "FreshRSS"
url: https://my-service.url
username: "<---your-username--->"
password: "<---your-password--->"
```
Auto refresh is supported by this integration.
## Gatus
The Gatus service displays information about the configured services from the defined Gatus server.
Two lines are needed in the config.yml :
```yaml
type: "Gatus"
url: "http://192.168.0.151/gatus"
```
Optionally, the results can be filtered to only include jobs in the defined groups:
```yaml
groups: [Services, External]
```
The average times can be hidden (saves their calculation also) by setting the following:
```yaml
hideaverages: true
```
Auto refresh is supported by this integration.
## Gitea / Forgejo
Displays a Gitea / Forgejo version.
```yaml
- name: Forgejo
type: Gitea
logo: "assets/tools/sample.png"
url: https://my-service.url
```
## Glances
Displays system metrics (CPU, memory, swap, load) from a Glances server.
```yaml
- name: "System Metrics"
type: "Glances"
icon: "fa-solid fa-heart-pulse"
url: https://my-service.url
stats: [cpu, mem] # Options: load, cpu, mem, swap
```
Auto refresh is supported by this integration.
If you don't already have a glances server up and running, here is a sample Docker compose file to get you started:
```yml
---
services:
glances:
image: nicolargo/glances:latest
container_name: glances
environment:
- TZ=Europe/Rome
- GLANCES_OPT=-w
ports:
- 61208:61208
restart: unless-stopped
```
## Gotify
Displays the number of outstanding messages and system health status.
```yaml
- name: "Gotify"
type: "Gotify"
url: https://my-service.url
apikey: "<---insert-client-token-here--->"
```
Auto refresh is supported by this integration.
**API Token**: Use a **client token** (not an app token).
## Healthchecks
Displays status counts (up/down/grace) from your Healthchecks monitoring service.
```yaml
- name: "Healthchecks"
type: "Healthchecks"
url: https://my-service.url
apikey: "<---insert-api-key-here--->"
```
Auto refresh is supported by this integration.
**API Key**: Found in Healthchecks web interface under **Settings > API Access > API key (read-only)**.
## Home Assistant
Displays Home Assistant instance status, version, location, and entity count.
```yaml
- name: "Home Assistant"
type: "HomeAssistant"
logo: "assets/tools/sample.png"
url: https://my-service.url
apikey: "<---insert-long-lived-access-token-here--->"
items: [] # optional: "name", "version", "entities"
separator: " " # optional
```
**API Token**: Create a long-lived access token in Home Assistant:
1. Go to **Profile > Security > Long-lived access tokens**
2. Click **Create Token**
**CORS Configuration**: Edit Home Assistant `configuration.yml` and add Homer's IP:
```yaml
http:
cors_allowed_origins:
- "http://homer.local:8080"
- "https://your-homer-domain.com"
```
## Hyper HDR
Display Hyper HDR instance name and status.
```yaml
- name: "HyperHDR"
type: "HyperHDR"
logo: "assets/tools/sample.png"
url: https://my-service.url
```
## Immich
Displays user count, photo/video counts, and storage usage from your Immich server.
```yaml
- name: "Immich"
type: "Immich"
logo: "assets/tools/sample.png"
url: https://my-service.url
apikey: "<---insert-api-key-here--->"
```
Auto refresh is supported by this integration.
**Requirements**: Immich server version `1.118.0` or later
**API Key**: Create an API key in Immich web interface under **Administration > API Keys**
## Jellystat
Display the number of concurrent streams on your Jellyfin server.
```yaml
- name: "Jellystat"
type: "Jellystat"
logo: "assets/tools/sample.png"
url: https://my-service.url
apikey: "<---insert-api-key-here--->"
```
Auto refresh is supported by this integration.
**API Key**: You can create an API key in the dashboard of you Jellystat server: settings/API Keys -> Add Key
## Lidarr, Prowlarr, Sonarr, Readarr and Radarr
Displays Activity (blue), Missing (purple) Warning (orange) or Error (red) notifications bubbles from the Lidarr, Readarr, Radarr or Sonarr application.
Two lines are needed in the `config.yml`:
```yaml
- name: "Lidarr"
type: "Lidarr" # "Lidarr" "Prowlarr", "Radarr" or "Sonarr"
logo: "assets/tools/sample.png"
url: https://my-service.url
apikey: "<---insert-api-key-here--->"
```
Auto refresh is supported by this integration.
The url must be the root url of Lidarr, Prowlarr, Readarr, Radarr or Sonarr application.
**API Key**: The Lidarr, Prowlarr, Readarr, Radarr or Sonarr API key can be found in `Settings` > `General`. It is needed to access the API.
> [!IMPORTANT]
> **Radarr API V3 support**: 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"`
## Linkding
This integration makes it possible to query Linkding and list multiple results from Linkding.
Linkding has to be configured with CORS enabled. Linkding does not support that, but a reverse proxy in front can fix that.
This integration supports at max 15 results from Linkding, but you can add it multiple times to you dashboard with different queries to retrieve what you need.
```yaml
- name: "Linkding"
type: "Linkding"
url: https://my-service.url
token: "<---insert-api-key-here--->"
limit: 10 # Maximum number of items returned by Linkding, minimal 1 and max 15
query: "#ToDo #Homer" # query to do on Linkding. Use #tagname to search for tags
```
Auto refresh is supported by this integration.
## LibrisLog
Displays library statistics from your LibrisLog book tracker: total books, books read, currently reading, and want-to-read counts.
```yaml
- name: "LibrisLog"
type: "LibrisLog"
logo: "https://docs.librislog.app/logo.png"
url: "https://my-service.url"
apikey: "<---insert-api-key-here--->"
```
Auto refresh is supported by this integration.
**API Key**: Generate an API key in your LibrisLog instance settings.
## Matrix
Displays a Matrix version, and shows if the server is online.
```yaml
- name: "Matrix - Server"
type: "Matrix"
logo: "assets/tools/sample.png"
url: "http://matrix.example.com"
```
## Mealie
Displays the number of recipes Mealie is keeping organized or the planned meal for today if one is planned.
```yaml
- name: "Mealie"
type: "Mealie"
logo: "assets/tools/sample.png"
url: https://my-service.url
apikey: "<---insert-api-key-here--->"
```
**API Key**: You will have to set an API key in the field `apikey` which can be created in your Mealie installation.
The API page can be found: Click on hamburger menu -> Click on your profile -> Click on "Manage your API Tokens"
## Medusa
Displays News (gray), Warning (orange) or Error (red) notifications bubbles from the Medusa application.
```yaml
- name: "Medusa"
type: "Medusa"
logo: "assets/tools/sample.png"
url: https://my-service.url
apikey: "<---insert-api-key-here--->"
```
The url must be the root url of Medusa application.
**API Key**: The Medusa API key can be found in General configuration > Interface. It is needed to access Medusa API.
## Miniflux
Displays the number of unread articles from your Miniflux RSS reader.
```yaml
- name: "Miniflux"
type: "Miniflux"
logo: "assets/tools/sample.png"
url: https://my-service.url
apikey: "<---insert-api-key-here--->"
style: "status" # Either "status" or "counter"
```
Auto refresh is supported by this integration.
**API Key**: Generate an API key in Miniflux web interface under **Settings > API Keys > Create a new API key**
## NetAlertx
Displays network monitoring stats (connected devices, alerts, network activity) from your NetAlertx server.
```yaml
- name: "NetAlertx"
type: "NetAlertx"
logo: "assets/tools/sample.png"
url: https://my-service.url
apikey: "<---insert-api-key-here--->"
# endpoint: "https://my-service-api.url" # Optional: alternative base URL used to fetch service data when necessary.
```
Auto refresh is supported by this integration.
**API Key**: Get your API key in NetAlertx web interface under **Settings > General > API token** or in your installation documentation.
**Note**: NetAlertx is the modern fork/rename of PiAlert. Both integrations are available in Homer for compatibility.
## Nextcloud
Displays Nextcloud version and shows if Nextcloud is online, offline, or in [maintenance
mode](https://docs.nextcloud.com/server/stable/admin_manual/maintenance/upgrade.html#maintenance-mode).
```yaml
- name: Nextcloud
type: Nextcloud
logo: assets/tools/sample.png
url: https://my-service.url
```
## OctoPrint/Moonraker
The OctoPrint/Moonraker service only needs an `apikey` & `endpoint` and optionally a `display` or `url` option. `url` can be used when you click on the service it will launch the `url`
Moonraker's API mimics a few of OctoPrint's endpoints which makes these services compatible. See for details.
```yaml
- name: "Octoprint"
type: "OctoPrint"
logo: assets/tools/sample.png
endpoint: "https://my-service-api.url:port"
apikey: "<---insert-api-key-here--->"
display: "text" # 'text' or 'bar'. Default to `text`.
```
Auto refresh is supported by this integration.
## Olivetin
Displays a Olivetin version.
```yaml
- name: Olivetin
type: Olivetin
logo: assets/tools/sample.png
url: https://my-service.url
```
## OpenHAB
Displays OpenHAB system status, things count, and items count.
```yaml
- name: "OpenHAB"
type: "OpenHAB"
logo: "assets/tools/sample.png"
url: https://my-service.url
apikey: "<---insert-api-key-here--->"
things: true # query things API for counts
items: true # query items API for counts
```
**API Token**: Create an API token following the [official OpenHAB documentation](https://www.openhab.org/docs/configuration/apitokens.html)
**CORS Configuration**: Edit `services/runtime.cfg` and add:
```ini
org.openhab.cors:enable=true
```
## OpenWeatherMap
Using the OpenWeatherMap service you can display weather information about a given location.
The following configuration is available for the OpenWeatherMap service:
```yaml
- name: "Weather"
type: "OpenWeather"
apikey: "<---insert-api-key-here--->" # Request one from https://openweathermap.org/api.
location: "Amsterdam" # your location.
locationId: "2759794" # Optional: Specify OpenWeatherMap city ID for better accuracy
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, circle, none. Defaults to none.
```
**Remarks:**
If for some reason your city can't be found by entering the name in the `location` property, you could also try to configure the OWM city ID in the `locationId` property. To retrieve your specific City ID, go to the [OWM website](https://openweathermap.org), search for your city and retrieve the ID from the URL (for example, the City ID of Amsterdam is 2759794).
## Paperless-NGX
Displays total number of documents stored.
```yaml
- name: "Paperless"
type: "PaperlessNG"
logo: "assets/tools/sample.png"
url: https://my-service.url
apikey: "<---insert-api-key-here--->"
```
**API Key**: API key can be generated in Settings > Administration > Auth Tokens
## PeaNUT
Displays current status and UPS load of the UPS device.
```yaml
- name: "PeaNUT"
type: PeaNUT
logo: "assets/tools/sample.png"
url: https://my-service.url
# device: "ups" # The ID of the device
```
Auto refresh is supported by this integration.
## PiAlert
Displays stats from your PiAlert server.
```yaml
- name: "PiAlert"
type: "PiAlert"
logo: "assets/tools/sample.png"
url: https://my-service.url
```
Auto refresh is supported by this integration.
## PiHole
Displays info about your local PiHole instance right on your Homer dashboard.
```yaml
- name: "Pi-hole"
type: "PiHole"
logo: "assets/tools/sample.png"
url: https://my-service.url
# endpoint: "https://my-service-api.url" # optional, For v6 API, this is the base URL used to fetch Pi-hole data overwriting the url
apikey: "<---insert-api-key-here--->" # optional, needed if web interface is password protected
apiVersion: 5 # optional, defaults to 5. Use 6 if your PiHole instance uses API v6
```
Auto refresh is supported by this integration.
**API Key**: Required only if Pi-hole web interface is password protected. Go to **Settings > API/Web Interface > Show API token**
**API Versions**:
- **v5** (default): Uses legacy API endpoints
- **v6**: Uses modern API with session management - set `apiVersion: 6`
## Ping
Checks if the target link is available and displays the round trip time (RTT) of the request.
By default the HEAD method is used but it can be configured to use GET using the optional `method` property.
Optionally, use `successCodes` to define which HTTP response status codes should be considered as available status.
```yaml
- name: "Awesome app"
type: Ping
logo: "assets/tools/sample.png"
url: "https://www.wikipedia.org/"
# method: "head"
# successCodes: [200, 418] # Optional, default to all 2xx HTTP response status codes
# timeout: 500 # Timeout in ms before ping is aborted. Default 2000
# subtitle: "Bookmark example" # By default, request round trip time is displayed when subtitle is not set
# endpoint: "https://www.wikimediastatus.net" # Optional, will override url for pinging
```
Auto refresh is supported by this integration.
## Plex
Displays active streams, total movies, and total TV series from your Plex server.
```yaml
- name: "Plex"
type: "Plex"
logo: "assets/tools/sample.png"
url: "https://my-service.url/web"
endpoint: "https://my-service.url"
token: "<---insert-plex-token-here--->"
```
Auto refresh is supported by this integration.
**Plex Token**: See [How to find your Plex token](https://www.plexopedia.com/plex-media-server/general/plex-token/)
## Portainer
Displays container counts (running/dead/misc), version, and online status from your Portainer instance.
```yaml
- name: "Portainer"
type: "Portainer"
logo: "assets/tools/sample.png"
url: https://my-service.url
apikey: "<---insert-api-key-here--->"
environments: # optional: specific environments to check
- "raspberry"
- "local"
```
Auto refresh is supported by this integration.
**Requirements**: Portainer version 1.11 or later
**API Key**: Generate an access token in Portainer UI. See [Creating an Access Token](https://docs.portainer.io/api/access#creating-an-access-token)
## Prometheus
```yaml
- name: "Prometheus"
type: "Prometheus"
logo: "assets/tools/sample.png"
url: https://my-service.url
```
Auto refresh is supported by this integration.
## Proxmox
Displays status information of a Proxmox node (VMs running and disk, memory and cpu used).
```yaml
- name: "Proxmox - Node"
type: "Proxmox"
logo: "assets/tools/sample.png"
url: https://my-service.url
node: "your-node-name"
warning_value: 50
danger_value: 80
api_token: "PVEAPIToken=root@pam!your-api-token-name=your-api-token-key"
# values below this line are optional (default value are false/empty):
hide_decimals: true # removes decimals from stats values.
hide: [] # hides information. Possible values are "vms", "vms_total", "lxcs", "lxcs_total", "disk", "mem" and "cpu".
small_font_on_small_screens: true # uses small font on small screens (like mobile)
small_font_on_desktop: true # uses small font on desktops (just in case you're showing much info)
```
Auto refresh is supported by this integration.
**API Key**: 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 assigned to that token if not separated permissions is checked) are this:
| Path | Permission | Comments |
|---------------------|------------|-------------------------------------------------------------------|
| /nodes/\ | Sys.Audit | |
| /vms/\ | VM.Audit | You need to have this permission on any VM you want to be counted |
It is highly recommended that you create and API Token with only these permissions on a read-only mode.
## qBittorrent
Displays the global upload and download rates, as well as the number of torrents
listed. The service communicates with the qBittorrent API interface which needs
to be accessible from the browser. Please consult
[the instructions](https://github.com/qbittorrent/qBittorrent/pull/12579)
for setting up qBittorrent.
```yaml
- name: "qBittorrent"
type: "qBittorrent"
logo: "assets/tools/sample.png"
url: https://my-service.url # Your rTorrent web UI, f.e. ruTorrent or Flood.
```
Auto refresh is supported by this integration.
## rTorrent
Displays the global upload and download rates, as well as the number of torrents
listed in rTorrent. The service communicates with the rTorrent XML-RPC interface which needs
to be accessible from the browser. Please consult
[the instructions](https://github.com/rakshasa/rtorrent-doc/blob/master/RPC-Setup-XMLRPC.md)
for setting up rTorrent.
```yaml
- name: "rTorrent"
type: "Rtorrent"
logo: "assets/tools/sample.png"
url: "https://my-service.url" # Your rTorrent web UI, f.e. ruTorrent or Flood.
xmlrpc: "https://my-service.url:port" # Reverse proxy for rTorrent's XML-RPC.
username: "username" # Username for logging into rTorrent (if applicable).
password: "password" # Password for logging into rTorrent (if applicable).
```
Auto refresh is supported by this integration.
## SABnzbd
Displays the number of currently active downloads on your SABnzbd instance.
```yaml
- name: "SABnzbd"
type: "SABnzbd"
logo: "assets/tools/sample.png"
url: https://my-service.url
apikey: "<---insert-api-key-here--->"
```
Auto refresh is supported by this integration.
**API Key**: An API key is required, and can be obtained from the "Config" > "General" section of the SABnzbd config in the web UI.
## Scrutiny
Displays info about the total number of disk passed and failed S.M.A.R.T and scrutiny checks
```yaml
- name: "Scrutiny"
type: "Scrutiny"
logo: "assets/tools/sample.png"
url: https://my-service.url
```
Auto refresh is supported by this integration.
## SpeedtestTracker
Displays the download and upload speeds in Mbit/s and the ping in ms.
```yaml
- name: "Speedtest Tracker"
type: "SpeedtestTracker"
logo: "assets/tools/sample.png"
url: https://my-service.url
```
## Tautulli
Displays the number of currently active streams on you Plex instance.
```yaml
- name: "Tautulli"
type: "Tautulli"
logo: "assets/tools/sample.png"
url: https://my-service.url
apikey: "<---insert-api-key-here--->"
```
Auto refresh is supported by this integration.
**API Key**: An API key is required, and can be obtained from the "Web Interface" section of settings on the Tautulli web UI.
Because the service type and link don't necessarily have to match, you could
even make the service type Tautulli on your Plex card and provide a separate
endpoint pointing to Tautulli!
```yaml
- name: "Plex"
type: "Tautulli"
logo: "assets/tools/sample.png"
url: https://my-plex.url/web # Plex
endpoint: https://my-tautulli.url # Tautulli
apikey: "<---insert-api-key-here--->"
```
## Tdarr
Displays the number of currently queued items for transcoding on your Tdarr instance as well as the number of errored items.
```yaml
- name: "Tdarr"
type: "Tdarr"
logo: "assets/tools/sample.png"
url: https://my-service.url
```
Auto refresh is supported by this integration.
## Traefik
Displays Traefik.
```yaml
- name: "Traefik"
type: "Traefik"
logo: "assets/tools/sample.png"
url: "http://traefik.example.com"
# basic_auth: "admin:password" # (Optional) Send Authorization header.
```
**Authentication**: If BasicAuth is set, credentials will be encoded in Base64 and sent as an Authorization header (`Basic `). The value must be formatted as "admin:password".
## Transmission
Displays the global upload and download rates, as well as the number of active torrents from your Transmission daemon.
The service communicates with the Transmission RPC interface which needs to be accessible from the browser.
```yaml
- name: "Transmission"
logo: "assets/tools/sample.png"
url: "http://192.168.1.2:9091" # Your Transmission web interface URL
type: "Transmission"
auth: "username:password" # Optional: HTTP Basic Auth
target: "_blank" # Optional: HTML a tag target attribute
```
Auto refresh is supported by this integration.
The service automatically handles Transmission's session management and CSRF protection.
## Truenas Scale
Displays TrueNAS version.
1. In the TrueNAS web interface, click your user avatar in the top-right corner and select "API Keys".
2. Click "Add", give the key a name such as "homer", and confirm.
3. Copy the generated key immediately - TrueNAS only shows it once - and paste it as the API Key when creating the integration in homer.
```yaml
- name: "Truenas"
type: "TruenasScale"
logo: "assets/tools/sample.png"
url: https://my-service.url
api_token: "<---insert-api-key-here--->"
```
## Uptime Kuma
Displays overall status, uptime percentage, and incident information from your Uptime Kuma status page.
```yaml
- name: "Uptime Kuma"
type: "UptimeKuma"
logo: "assets/tools/sample.png"
url: https://my-service.url
slug: "default" # status page the stats are read from, defaults to "default"
```
`slug` selects which status page the card reads its status and uptime from. It does not affect where the
card links to: as with any other service, that is whatever `url` is set to, which in most cases points at
the status page.
> [!IMPORTANT]
> **Potentially breaking change**: on version `26.04.2` and earlier, this card rewrote `url` and always
> sent you to `/status/`. It no longer does, so a card that used to open a status page now
> opens `url` as configured.
>
> If you want the card to keep opening a status page, either:
>
> - point `url` straight at the status page. In that case `endpoint` must be set to the Uptime Kuma base
> url, otherwise the API calls are made against the status page path and fail:
>
> ```yaml
> - name: "Uptime Kuma"
> type: "UptimeKuma"
> url: https://my-service.url/status/my-slug # where the card links to
> endpoint: https://my-service.url # where the API lives
> slug: "my-slug"
> ```
>
> - or set **Settings > General > Entry Page** in Uptime Kuma to that status page, which sends everyone
> landing on the base url there, and leaves the Homer config untouched.
Auto refresh is supported by this integration.
**Requirements**: Uptime Kuma version `1.13.1` or later (for [multiple status pages support](https://github.com/louislam/uptime-kuma/releases/tag/1.13.1))
## Vaultwarden
Displays Vaultwarden version and status.
```yaml
- name: "Vaultwarden - Server"
type: "Vaultwarden"
logo: "assets/tools/sample.png"
url: https://my-service.url
```
## Wallabag
Displays Wallabag version.
```yaml
- name: Wallabag
type: Wallabag
logo: "assets/tools/sample.png"
url: https://my-service.url
```
## What's up Docker
Display info about the number of container running and the number for which an update is available on your Homer dashboard.
```yaml
- name: "What's Up Docker"
type: "WUD"
logo: "assets/tools/sample.png"
url: https://my-service.url
subtitle: "Docker image update notifier"
```
Auto refresh is supported by this integration.
---
## File: docs/development.md
# Development
If you want to contribute to Homer, please read the [contributing guidelines](https://github.com/bastienwirtz/homer/blob/main/CONTRIBUTING.md) first.
```sh
pnpm install
pnpm dev
```
## Custom services
Custom services are small VueJs component (see `src/components/services/`) that add little features to a classic, "static", dashboard item. It should be very simple.
A dashboard can contain a lot of items, so performance is very important.
The [`Generic`](https://github.com/bastienwirtz/homer/blob/main/src/components/services/Generic.vue) service provides a typical card layout which
you can extend to add specific features. Unless you want a completely different design, extended the generic service is the recommended way. It gives you 3 [slots](https://vuejs.org/v2/guide/components-slots.html#Named-Slots) to extend: `icon`, `content` and `indicator`.
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
```
## Themes
Themes are meant to be simple customization (written in [scss](https://sass-lang.com/documentation/syntax)).
To add a new theme, just add a file in the theme directory, and put all style in the `body #app.theme-` scope. Then import it in the main style file.
```scss
// `src/assets/themes/my-awesome-theme.scss`
body #app.theme-my-awesome-theme. { ... }
```
```scss
// `src/assets/app.scss`
// Themes import
@import "./themes/sui.scss";
...
@import "./themes/my-awesome-theme.scss";
```
---
## File: docs/kubernetes.md
# Kubernetes Installation
We have different solution to install Homer on Kubernetes Cluster, each solution responds to a specific need.
## Table of Contents
- [Helm Chart](#helm-chart)
- [Controller With CRDs](#controller-crds)
- [Controller With Ingress Annotations](#controller-annotations)
- [Operator](#Operator)
## Helm Chart
To deploy Homer in Kubernetes
Thanks to [@djjudas21](https://github.com/djjudas21) [charts](https://github.com/djjudas21/charts/tree/main/charts/homer):
### Installation
```sh
helm repo add djjudas21 https://djjudas21.github.io/charts/
helm repo update djjudas21
# install with all defaults
helm install homer djjudas21/homer
# install with customisations
wget https://raw.githubusercontent.com/djjudas21/charts/main/charts/homer/values.yaml
# edit values.yaml
helm install homer djjudas21/homer -f values.yaml
```
## Controller CRDs
To deploy Homer in Kubernetes with [Custom Resources Definition](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/) to dynamic declaration for Homer Service
Thanks to [@jplanckeel](https://github.com/jplanckeel) [homer-k8s](https://github.com/bananaops/homer-k8s/tree/main/):
### Installation
```sh
helm repo add bananaops https://bananaops.github.io/homer-k8s/
helm repo update bananaops
# install with all defaults
helm install homer bananaops/homer-k8s
# install with customisations
wget https://raw.githubusercontent.com/bananaops/homer-k8s/main/helm/homer-k8s/values.yaml
# edit values.yaml
helm install homer bananaops/homer-k8s -f values.yaml
```
### Usage
- [usage](https://github.com/bananaops/homer-k8s/tree/main/?tab=readme-ov-file#crds-homerservices)
## Controller Annotations
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/):
## Operator
To deploy many Homer in Kubernetes with [Custom Resources Definition](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/)
Thanks to [@rajsinghtech](https://github.com/rajsinghtech) [homer-operator](https://github.com/rajsinghtech/homer-operator/tree/main/):
### Installation
```sh
# install with customisations
wget https://raw.githubusercontent.com/rajsinghtech/homer-operator/main/deploy/operator.yaml
# Apply operator file
kubectl apply -f operator.yaml
```
### Usage
- [usage](https://github.com/rajsinghtech/homer-operator?tab=readme-ov-file#usage)
---
## File: docs/theming.md
# Theming
## Change theme
The default theme can be changed using the yaml configuration file
```yaml
theme: default # 'default', 'walkxcode', or 'neon' see files in 'src/assets/themes'.
```
## Favicon
Use your own favicon by changing the icons files in the `assets/icons` directory. More information on the format [here](https://github.com/bastienwirtz/homer/blob/main/public/assets/icons/README.md).
## Colors and background customization
Default colors and background can be customized for each theme variant (light and dark), using either the yaml config file, or the css variables (see "Additional stylesheets" below).
### Available options
| yaml | css | description |
| --------------------- | ----------------------- | --- |
| `highlight-primary` | `--highlight-primary` | header background, group title icons |
| `highlight-secondary` | `--highlight-secondary` | navbar background, default tag color |
| `highlight-hover` | `--highlight-hover` | navbar links hover, search input background |
| `background` | `--background` | page background color |
| `card-background` | `--card-background` | service card background color |
| `text` | `--text` | main text color |
| `text-header` | `--text-header` | header text color |
| `text-title` | `--text-title` | service card title color |
| `text-subtitle` | `--text-subtitle` | service card subtitle color |
| `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()` instead of just the url. see example below)|
YAML example
```yml
colors:
light:
highlight-primary: "#3367d6"
background-image: "assets/your/light/bg.webp"
...
dark:
highlight-primary: "#3367d6"
background-image: "assets/your/dark/bg.webp"
...
```
CSS example
```css
.light {
--highlight-primary: #3367d6;
--background-image: url("assets/your/light/bg.webp");
...
}
.dark {
--highlight-primary: #3367d6;
--background-image: url("assets/your/dark/bg.webp");
...
}
```
## Additional stylesheets
One or more additional stylesheets can be loaded to add or override style from the current theme. Use the 'stylesheet' option in the yaml configuration file to load your own CSS file.
```yml
stylesheet:
- "assets/custom.css"
```
### Customization example
#### Max width modification
```css
body #main-section .container {
max-width: 2000px; // adjust to your needs (eg: calc(100% - 100px), none, ...)
}
```
#### Background gradient
```css
#app {
height: 100%;
background: linear-gradient(90deg, #5c2483, #0095db);
}
```
---
## File: docs/tips-and-tricks.md
# Tips & Tricks
Here is a collection of neat tips and tricks that Homer users have come up with!
## Dashboard icons
Great source to find service icons
-
-
## Use Homer as a custom "new tab" page
#### `by @vosdev`
These extensions for [Firefox](https://addons.mozilla.org/firefox/addon/custom-new-tab-page) and [Chrome & Friends](https://chrome.google.com/webstore/detail/new-tab-changer/occbjkhimchkolibngmcefpjlbknggfh) allow you to have your homer dashboard in your new tab page, while leaving focus on the address bar meaning you can still type right away if you want to search or go to a page that is not on your homer dash.
The Firefox extension loads Homer in an iframe on your new tab page, meaning you have to add `target: '_top'` to each of your items.
```yaml
- name: "Reddit"
logo: "assets/daily/reddit.png"
url: "https://reddit.com"
target: '_top'
- name: "YouTube"
logo: "assets/daily/youtube.png"
url: "https://youtube.com"
target: '_top'
```
## YAML Anchors
#### `by @JamiePhonic`
Since Homer is configured using YAML, it supports all of YAML's helpful features, such as anchoring!
For example, you can define tags and tag styles for each "item" in a service.
Using Anchoring, you can define all your tags and their styles once like this: (for example)
```yaml
# Some pre-defined tag styles. reference these using <<: *{NAME} inside an item definition; For Example, <<: *Apps
tags:
Favourite: &Favourite
- tag: "Favourite"
tagstyle: "is-medium is-primary"
CI: &CI
- tag: "CI"
tagstyle: "is-medium is-success"
Apps: &Apps
- tag: "App"
tagstyle: "is-medium is-info"
```
and then simply reference these pre-defined (anchored) tags in each item like so:
```yaml
- name: "VS Code"
logo: "/assets/vscode.png"
subtitle: "Develop Code Anywhere, On Anything!"
<<: *Apps # Reference to the predefined "App" Tag
url: "https://vscode.example.com/"
target: "_blank" # optional html tag target attribute
````
Then when Homer reads your config, it will substitute your anchors automatically, the above example is equal to:
```yaml
- name: "VS Code"
logo: "/assets/vscode.png"
subtitle: "Develop Code Anywhere, On Anything!"
tag: "App"
tagstyle: "is-medium is-info"
url: "https://vscode.example.com/"
target: "_blank" # optional html tag target attribute
```
The end result is that if you want to update the name or style of any particular tag, just update it once, in the tags section!
Great if you have a lot of services or a lot of tags!
## YAML auto complete with a YAML schema
A lot of editor support auto completion, see
The homer schema is available here:
For example with IntelliJ you can define:
```yaml
# $schema: https://raw.githubusercontent.com/bastienwirtz/homer/main/.schema/config-schema.json
```
With VSCode you can define it like this:
```yaml
# yaml-language-server: $schema=https://raw.githubusercontent.com/bastienwirtz/homer/main/.schema/config-schema.json
```
## Remotely edit your config with Code Server
#### `by @JamiePhonic`
Homer doesn't yet provide a way to edit your configuration from inside Homer itself, but that doesn't mean it can't be done!
You can setup and use [Code-Server](https://github.com/cdr/code-server) to edit your `config.yml` file from anywhere!
If you're running Homer in docker, you can setup a Code-Server container and pass your homer config directory into it.
Simply pass your homer config directory as an extra -v parameter to your code-server container:
```sh
-v '/your/local/homer/config-dir/':'/config/homer':'rw'
```
This will map your homer config directory (For example, /docker/appdata/homer/) into code-server's `/config/` directory, in a sub folder called `homer`
As a bonus, Code-Server puts the "current folder" as a parameter in the URL bar, so you could add a `links:` entry in Homer that points to your code-server instance with the directory pre-filled for essentially 1 click editing!
For example:
```yml
links:
- name: Edit config
icon: fas fa-cog
url: https://vscode.example.net/?folder=/config/homer
target: "_blank" # optional html tag target attribute
```
where the path after `?folder=` is the path to the folder where you mounted your homer config INSIDE the Code-Server container.
### Example Code-Server docker create command
```sh
docker create \
--name=code-server \
-e PUID=1000 \
-e PGID=1000 \
-e TZ=Europe/London \
-e PASSWORD={YOUR_PASSWORD} `#optional` \
-e SUDO_PASSWORD={YOUR SUDO_PASSWORD} `#optional` \
-p 8443:8443 \
-v /path/to/appdata/config:/config \
-v /your/local/homer/config-dir/:/config/homer \
--restart unless-stopped \
linuxserver/code-server
```
## Get the news headlines in Homer
### Mapping Fields
Most times, the url you're getting headlines from follows a different schema than the one expected by Homer.
For example, if you would like to show jokes from ChuckNorris.io, you'll find that the url is giving you info like this:
```json
{
"categories": [],
"created_at": "2020-01-05 13:42:22.089095",
"icon_url": "https://assets.chucknorris.host/img/avatar/chuck-norris.png",
"id": "MR2-BnMBR667xSpQBIleUg",
"updated_at": "2020-01-05 13:42:22.089095",
"url": "https://api.chucknorris.io/jokes/MR2-BnMBR667xSpQBIleUg",
"value": "Chuck Norris can quitely sneak up on himself"
}
```
but... you need that info to be transformed to something like this:
```json
{
"title": "MR2-BnMBR667xSpQBIleUg",
"content": "Chuck Norris can quitely sneak up on himself"
}
```
Now, you can do that using the `mapping` field in your `message` configuration. This example would be something like this:
```yml
message:
url: https://api.chucknorris.io/jokes/random
mapping:
title: 'id'
content: 'value'
```
As you would see, using the ID as a title doesn't seem nice, that's why when a field is empty it would keep the default values, like this:
```yml
message:
url: https://api.chucknorris.io/jokes/random
mapping:
content: 'value'
title: "Chuck Norris Facts!"
```
and even an error message in case the `url` didn't respond or threw an error:
```yml
message:
url: https://api.chucknorris.io/jokes/random
mapping:
content: 'value'
title: "Chuck Norris Facts!"
content: "Message could not be loaded"
```
#### `by @JamiePhonic`
Homer allows you to set a "message" that will appear at the top of the page, however, you can also supply a `url:`.
If the URL you specified returns a JSON object that defines a `title` and `content` item, homer will replace these values from your `config.yml` with the ones in the returned object.
So, using [Node-Red](https://nodered.org/docs/getting-started/) and a quick flow, you can process an RSS feed to replace the message with a news item!
To get started, simply import [this flow](https://flows.nodered.org/flow/4b6406c9a684c26ace0430dd1826e95d) into your Node-Red instance and change the RSS feed in the "Get News RSS Feed" node to one of your choosing!
So far, the flow has been tested with BBC News and Sky News, however it should be easy to modify the flow to work with other RSS feeds if they don't work out of the box!
## Write HTML into the dashboard
### Show latest camera feed
#### `by @matheusvellone`
The `message.content` config entry accepts HTML code, so you can add images.
If you use Frigate, or have any `latest.jpg` URL for your camera, you can add it to your dashboard. You can also style the `div`/`img` tags to look nicer on your dashboard.
```yml
message:
title: Cameras
content: >
```
When using Frigate you can even add a live feed to your dashboard, like this:
```yml
message:
title: Cameras
content: >
```
---
## File: docs/troubleshooting.md
# Troubleshooting
## 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):
```sh
$ docker logs homer
[...]
Assets directory not writable. Check assets directory permissions & docker user or skip default assets install by setting the INIT_ASSETS env var to 0
```
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:
- 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.
> [!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 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.
Web browsers will not allow to fetch information from a different site without explicit permissions (the targeted service
must include a special `Access-Control-Allow-Origin: *` HTTP headers).
If this happens your web console (`ctrl+shift+i` or `F12`) will be filled with this kind of errors:
```text
Access to fetch at 'https://' from origin 'https://' has been blocked by CORS policy: No 'Access-Control-Allow-Origin' header is present on the requested resource. If an opaque response serves your needs, set the request's mode to 'no-cors' to fetch the resource with CORS disabled.
```
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: *` (). 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 proxy** to add the necessary CORS headers (lot of options, some of them described [here](https://enable-cors.org/server.html). Also check [`CORSair`](https://github.com/bastienwirtz/corsair), a light and simple solution)
## 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.
## 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
---
## File: dummy-data/README.md
# Dummy data
This directory content makes possible to test custom services cards or create a demo without actually running the service.
The principle is simple: save a sample output of the API used in the service in a static file in this directory. The path must be identical as the service endpoint to be used seamlessly.
## Start the mock server to expose dummy data
```sh
pnpm mock
```
## How to add a new services sample
- create a directory for your service, and any sub-folder existing in the service api path.
- save the api output in a file named after the service endpoint.
Example:
```sh
mkdir pihole
curl http://my-pihole.me/admin/api.php -o pihole/api.php # /admin is omitted because for PiHole, the implementation expect it to be in the base url (`url` or `endpoint` property)
```
---
## File: public/assets/icons/README.md
# PWA Icons / Images
We suggest you to create a svg or png icon (if it is a png icon, with the maximum resolution possible) for your application and use it to generate a favicon package in [Favicon Generator](https://realfavicongenerator.net/).
Once generated, download the ZIP and use android-* icons for pwa-*:
- use `android-chrome-192x192.png` for `pwa-192x192.png`
- use `android-chrome-512x512.png` for `pwa-512x512.png`
- `apple-touch-icon.png` is `apple-touch-icon.png`
- `favicon.ico` is `favicon.ico`
--- METRICS ---
- Files Extracted: 11
- Estimated Token Budget: ~15468 tokens
- Recency Window: Active (< 180 days)
- Canonical Reference: https://codewiki.google/github.com/bastienwirtz/homer