Build

Application Dashboard - 3

Homepage dashboard is a modern, secure, highly customizable application dashboard. Easily configured via YAML files or discovery via docker labels. The number of apps it supports with widgets is impressive. And the way of using API Tokens in stead of user/password is admirable. #dashboard

Nalle

Nalle

— 9 min read
Application Dashboard - 3

Homepage is a modern (fully static, fast), secure (fully proxied), highly customizable application dashboard with integrations for more than 25 services and translations for over 15 languages. Easily configured via YAML files (or discovery via docker labels).

The number of apps it supports with widgets is impressive. And the way of using API Tokens instead of user/password is admirable.

Homepage uses walkxcode dashboard-icons (xxx[.png or .svg]) but also Materia Design Icons (mdi-xxx) and Simple Icons (si-xxx). Use of external icons is supported (https://...). Icon colors can be changed in the settings.

Install Hompage Dashboard

Homepage has been my go-to dashboard for quite some time now. I just ❤️ it.

Install in Docker

This is for running as root. If not, you need to add to the example below, the environment variables $PUID and $PGID or set them in a .env file.

Running apps as root is not recommended if they are facing the internet.

Docker-compose.yml

version: "3.3"
services:
  homepage:
    image: ghcr.io/gethomepage/homepage:latest
    container_name: homepage
    restart: unless-stopped
    ports:
      - 3008:3000
    volumes:
      - ./configs:/app/config # Make sure your local config directory exists
      - /var/run/docker.sock:/var/run/docker.sock:ro # (optional) For docker integrations

Configure

You need to set up your environment by editing at least these 3 files in .../configs
For configuration options and examples, please see: link

Settings

---
# Use providers to not reveal the key in request
providers:
  openweathermap: openweathermapapikey
  weatherapi: weatherapiapikey

title: My Dashboard by Homepage
theme: dark # or light
color: purple #purple #slate or many more
headerStyle: underlined #boxed
showStats: true
background: https://images.unsplash.com/photo-1502790671504-542ad42d5189?auto=format&fit=crop&w=2560&q=80
fiveColumns: true
layout:
  Proxmox VE:
    icon: proxmox.svg
  Proxmox Backup Servers:
    icon: proxmox-light
  My Generic Applications:
    icon: terminal.svg
  Network Services:
    icon: firefox.svg
  Network Infra:
    icon: netbox.svg

Services

Here, you add the Services you like to access and monitor. Basic monitoring is by ping, but by widgets you can go deeper into the status of a server/service.

- Proxmox VE:
    - Pve-1:
        icon: proxmox
        href: https://pve-1:8006
        description: Web facing services
        ping: pve-1.lab.casaursus.net:8006
        widget:
            type: proxmox
            url: https://10.10.10.41:8006
            username: api@pam!apiToken
            password: <The Token>
            node: pve-1 # optional to specify a node instead of a cluster
    - Pve-2:
        icon: proxmox
        href: https://pve-2:8006
        description: Test Server A
        ping: https://10.10.10.42:8006
    - Pve-3:
        icon: proxmox
        href: https://pve-3:8006
        description: Test Server B
        ping: https://10.10.10.43:8006
        
- Proxmox Backup Servers:
    - pbs-1:
        icon: proxmox-light
        href: https://pbs-1:8007
        description: Main Backup Server
        ping: https://10.10.40.59:8007
        widget:
            type: proxmoxbackupserver
            url: https://10.10.40.59:8007
            username: api-user@pam!apiToken
            password: <The Token>
            
- Network Services:
    - pfSense:
        icon: pfsense 
        href: https://fw1
        description: Firewall
        ping: https://fw1
        widget:
          type: pfsense
          url: https://fw1
          username: joe
          password: password
          wan: vtnet0 
          
     - HomeLab Blog:
         icon: ghost
         href: https://homelab.casaursus.net
         description: my HomeLab Journey Blog
         ping: https://homelab.casaursus.net
    - Navidrone:
        icon: navidrome
        href: https://musa.casaursus.net/
        description: My Music on the Road
        ping: https://music.example.com
        widget:
            type: navidrome
            url: https://musicexample.com
            user: joe
            token: 26719a1196d2a940705a59634eb18eab
            salt: c19b2d

Bookmarks

---
- Blog - homelab.casaursus.net:
  - my HomeLab blog:
    - abbr: blog
      href: https://homelab.casaursus.net
  - myHomelab Journey on Github:
    - abbr: git
      href: https://github.com/nallej/MyJourney

- Developer of Homepage:
  - Homepage:
    - abbr: page
      https://gethomepage.dev/
  - benphelps/homepage on Github:
    - abbr: git
      href: https://github.com/gethomepage/homepage

- Social:
  - Reddit:
    - abbr: r/
      href: https://reddit.com/

- Entertainment:
  - YouTube:
    - abbr: YT
      href: https://youtube.com/

Widgets

---
- logo
- greeting:
    text_size: 2xl                                                      
    text: CasaUrsus
- resources:
    cpu: true
    memory: true
    disk: /
    cputemp: true
    #uptime: true
- search:
    provider: duckduckgo
    target: _blank
- datetime:
    locale: fi
    text_size: 4xl
    format:
      timeStyle: short
    #  dateStyle: short
    #  hourCycle: h23
- openmeteo:
    label: Dublin # optional
    latitude: 53.34412
    longitude: 6.26734
    #timezone: Europe/Dublin # optional
    units: metric # or imperial
    cache: 5 # Time in minutes to cache API responses, to stay within limits
- openmeteo:
    label: Kiev
    latitude: 50.42929
    longitude: 30.53806
    #timezone: Europe/Kiev # optional
    units: metric # or imperial
    cache: 5 # Time in minutes to cache API responses, to stay within limits

Usage

In your browser, go to the page <IP:3008> and see the status and/or go to a server or service.

Proxmox widget

With the widget, you may choose to see the cluster or individual node's metrics. By default, it will show the average for the complete cluster.

widget:
    type: proxmox
    url: https://proxmox.host.or.ip:8006
    username: api_token_id
    password: api_token_secret
    node: pve-1 # optional

Use username@pam!Token ID as the username (e.g api@pam!homepage) setting and Secret as the password setting.

Allowed fields: ["vms", "lxc", "resources.cpu", "resources.mem"].

Click to show: How to Setup an API Token for an user 

  1. Navigate to the Proxmox portal, click on Datacenter
  2. Expand Permissions, click on Groups
  3. Click the Create button
  4. Name the group something informative, like api-ro-users
  5. Click on the Permissions “folder”
  6. Click Add -> Group Permission
  • Path: /
  • Group: group from bullet 4 above
  • Role: PVEAuditor
  • Propagate: Checked
  1. Expand Permissions, click on Users
  2. Click the Add button
  • User name: something informative like api
  • Realm: Linux PAM standard authentication
  • Group: group from bullet 4 above
  1. Expand Permissions, click on API Tokens
  2. Click the Add button
  • User: user from bullet 8 above
  • Token ID: something informative like the application or purpose like homepage
  • Privilege Separation: Checked
  1. Go back to the “Permissions” menu
  2. Click Add -> API Token Permission
  • Path: /
  • API Token: select the Token ID created in Step 10
  • Role: PVE Auditor
  • Propagate: Checked

Proxmox Backup Server Widget

First, you need to create a user in the Shell adduser api-user 

adduser api-user
proxmox-backup-manager user create api-user@pam --email [email protected]

Now set the Permissions for the User, create a Token and add its Permissions.
See Configuration / Access Control / Permissions Tab. Use role Audit for read only.

Add permissions to the user. Use Audit for r/o
Create a Token
Add permissions to the Token Use Audit for r/o

send an authentication token, calculated as a one-way salted hash of the password. Use this MD5 generator tool or the manual way.

This involves two steps:

  1. For each REST call, generate a random string called the salt. Use a salt length of at least 6–32 characters.
  2. Calculate the authentication token as follows: token = md5(password + salt). The md5() function takes a string and returns the 32-byte ASCII hexadecimal representation of the MD5 hash, using lower case characters for the hex values.
 #!/bin/bash
 # Script> salt.sh It generates a MD5 hash from a input
 echo   -n   $1 | md5sum | awk '{print $1}'
 # Usage ./salt.sh "sesamec19b2d"

For example: password is sesame and the salt is c19b2d. The token for md5("sesamec19b2d") = 26719a1196d2a940705a59634eb18eab.
The corresponding widget then becomes: 

widget:
    type: navidrome
    url: http://navidrome.host.or.ip:port
    user: username
    token: 26719a1196d2a940705a59634eb18eab # Token md5(password + salt)
    salt: c19b2d #randomsalt

NginX Widget

Allowed fields: ["enabled", "disabled", "total"].

widget:
    type: npm
    url: http://npm.host.or.ip
    username: admin_username
    password: admin_password

pfSense Widget

This widget requires the installation of the pfSense-API, which is a 3rd party package for pfSense routers. Set the API to read-only in System → API → Settings.

Allowed fields (max 4): ["load", "memory", "temp", "wanStatus", "wanIP", "disk"] If your IP is fixed you do not need the wan IP, otherwise it's important.

widget:
    type: pfsense
    url: http://pfsense.host.or.ip:port
    username: user
    password: pass
    wan: igb0

Portainer Widget

Go to an Environment and check what URL it's pointing to. At the end of the URL after the port number should be, something like #!/endpoints/2, here 2 is the value to set as the env value. In order to generate an API key, please follow the steps outlined here https://docs.portainer.io/api/access.

Allowed fields: ["running", "stopped", "total"]. Port, usually 9000 or 9443.

widget:
    type: portainer
    url: https://portainer.host.or.ip:9443
    env: 2
    key: ptr_accesskeyaccesskeyaccesskeyaccesskey

Authentik Widget

You will need to generate an API token for an existing user. Port usually 22070.

Allowed fields: ["users", "loginsLast24H", "failedLoginsLast24H"].

widget:
    type: authentik
    url: http://authentik.host.or.ip:22070
    key: api_token

TrueNAS

Allowed fields: ["load", "uptime", "alerts"].

Set up the widget is easy, just give it the IP and Api-Key. Other solutions are to use DNS name and/or user and password. A key is more secure.

To create an API Key, follow the official TrueNAS documentation.

widget:
    type: truenas
    url: http://truenas.host.or.ip
    #username: user # not required if using api key
    #password: pass # not required if using api key
    key: <your-truenas-apikey> # not required if using username / password

Cloudflare Tunnels

You need to set up an API token which only requires the permissions Account.Cloudflare Tunnel:Read.

Allowed fields: ["status", "origin_ip"].

widget:
    type: cloudflared
    accountid: accountid # from zero trust dashboard url e.g. https://one.dash.cloudflare.com/<accountid>/home/quick-start
    tunnelid: tunnelid # found in tunnels dashboard under the tunnel name
    key: cloudflareapitoken # api token with `Account.Cloudflare Tunnel:Read` https://dash.cloudflare.com/profile/api-tokens

Watchtower

To use this widget, Watchtower needs to be configured to enable metrics.

💡
Metrics in Watchtower is a Experimental feature
This feature was added in v1.0.4 and is still considered experimental. 

Allowed fields: ["containers_scanned", "containers_updated", "containers_failed"]. 

widget:
    type: watchtower
    url: http://your-ip-address:8080
    key: demotoken

Service Widgets I'm using

Like the ones for: Authentik, Cloudflare Tunnels, Grafana, Gotify, Navidrome, NginX, Nginx Proxy Manager, OPNSense, pfSense, Portainer, Prometheus, Proxmox, Proxmox Backup Server, Traefik, Transmission, TrueNAS, Uptime Kuma, Watchtower, Whats Up Docker and some of the Information Widgets.

References

The homepage app[1] icons [2] icons 1 [3] icons 2 [4]
Docker [5] Docker-Compose [6] Portainer [7]
Authelia[8] Autentik [9] Clodflare Tunnels [10] Navidrome [11] NginX NPM [12] pfSense [13] Proxmox VE [14] Proxmox Backup Server [15] TrueNAS [16] Whatchtower [17]
See my blog post on Uptime-Kuma

  1. Homepage dashboard config help homepage and on Github ↩︎

  2. Homepage uses dashboard-icons as a base github ↩︎

  3. Material Design Icons page ↩︎

  4. Simple icons page ↩︎

  5. Docker home page Docker-ce Github and Documentation ↩︎

  6. Doccker-Compose home page and on Github ↩︎

  7. Portainer home page and Documentation and Portainer-ce on Github ↩︎

  8. Authelia home page and on Github and on Github ↩︎

  9. Autentik home page Documentation ↩︎

  10. Clodflare Tunnels home page ↩︎

  11. Navidrome home page Documentation and on Github ↩︎

  12. NginX Proxy Manager NPM Home page and on Github and Guide ↩︎

  13. See pfSense home page and
    jaredhendrickson13s API on GitHub ↩︎

  14. Proxmox VE [home page]https://www.proxmox.com/en/proxmox-ve) Documentation and wiki ↩︎

  15. Proxmox Backup Server home page Documentation and wiki ↩︎

  16. TrueNAS home page on Wikipedis ↩︎

  17. Watchtower home page metrics warning ↩︎

Read more