Skip to content

Commit

Permalink
Merge branch 'bastienwirtz:main' into main
Browse files Browse the repository at this point in the history
  • Loading branch information
@Bothari
Bothari authored Nov 1, 2024
2 parents 09ec5c5 + 779deed commit ba8177d
Show file tree
Hide file tree
Showing 19 changed files with 536 additions and 116 deletions.
53 changes: 23 additions & 30 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 All @@ -47,30 +38,32 @@
## Table of Contents

- [Features](#features)
- [Getting started](#getting-started)
- [Getting started](#get-started)
- [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 @@ -119,10 +112,10 @@ Download and extract the latest release (`homer.zip`) from the [release page](ht

```sh
wget https://github.com/bastienwirtz/homer/releases/latest/download/homer.zip
unzip 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 ...
pnpx http-server # or python -m http.server 8010 or any web server.
```

### Build manually
Expand Down
10 changes: 7 additions & 3 deletions docs/configuration.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -31,6 +31,10 @@ connectivityCheck: true # whether you want to display a message when the apps ar
# Optional: Proxy / hosting option
proxy:
useCredentials: false # send cookies & authorization headers when fetching service specific data. Set to `true` if you use an authentication proxy. Can be overrided on service level.
headers: # send custom headers when fetching service specific data. Can also be set on a service level.
Test: "Example"
Test1: "Example1"


# Set the default layout and color scheme
defaults:
Expand Down Expand Up @@ -95,6 +99,7 @@ message:
style: "is-warning"
title: "Optional message!"
icon: "fa fa-exclamation-triangle"
# The content also accepts HTML content, so you can add divs, images or whatever you want to make match your needs.
content: "Lorem ipsum dolor sit amet, consectetur adipiscing elit."

# Optional navbar
Expand Down Expand Up @@ -153,7 +158,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 @@ -182,7 +187,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 @@ -191,7 +196,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).
129 changes: 88 additions & 41 deletions docs/customservices.md
View file
Original file line number Diff line number Diff line change
@@ -1,45 +1,52 @@
# 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)
- [Nextcloud](#nextcloud)
- [Immich](#immich)
- [OpenHAB](#openhab)
- [Jellystat](#jellystat)
- [Home Assistant](#home-assistant)
- [FreshRSS](#freshrss)
- [Gotify](#gotify)

> [!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 All @@ -49,6 +56,7 @@ If you experiencing any issue, please have a look to the [troubleshooting](troub
url: "http://my-service-link"
endpoint: "http://my-service-endpoint" # Optional: alternative base URL used to fetch service data is necessary.
useCredentials: false # Optional: Override global proxy.useCredentials configuration.
headers: # Optional: Override global proxy.headers configuration.
type: "<type>"
```
Expand Down Expand Up @@ -162,7 +170,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 +299,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 @@ -427,6 +435,20 @@ for transcoding on your Tdarr instance as well as the number of errored items.
checkInterval: 5000 # (Optional) Interval (in ms) for updating the queue & error counts
```
## Nextcloud
This service displays a version string instead of a subtitle. The indicator
shows if Nextcloud is online, offline, or in [maintenance
mode](https://docs.nextcloud.com/server/stable/admin_manual/maintenance/upgrade.html#maintenance-mode).
Example configuration:
```yaml
- name: Nextcloud
type: Nextcloud
logo: assets/tools/sample.png
url: http://nextcloud.example.com
```
## PiAlert
The PiAlert service displays stats from your PiAlert server.
Expand Down Expand Up @@ -467,7 +489,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 Expand Up @@ -496,3 +518,28 @@ You need to set the type to HomeAssistant, provide an api key and enable cors on
```
To create an API token on HomeAssistant, follow the [official documentation here](https://developers.home-assistant.io/docs/auth_api/#long-lived-access-token).
To enable cors on HomeAssistant, edit your `configuration.yml` and add the IP of Homer to `https: cors_allowed_origins`

## FreshRSS

The FreshRSS service displays unread and subscriptions counts from your FreshRSS server.

```yaml
- name: "FreshRSS"
type: "FreshRSS"
username: "<-- Your username -->"
password: "<-- Your password -->"
updateInterval: 5000 # (Optional) Interval (in ms) for updating the stats
```

## Gotify

The Gotify service will show the number of currently oustanding messages
available as well as the overall health of the system.

Note that `apikey` must be a client token, not an app token.

```yaml
- name: "Gotify"
type: "Gotify"
apikey: "<api_key>" # Client token to retrieve messages
```
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
Loading

0 comments on commit ba8177d

Please sign in to comment.