Homepage

Homepage is a customizable dashboard for all of your self-hosted apps and services.

Configure Homepage

Run this on your Raspberry Pi

pi make homepage config

You need to configure two sub-domains, one for homepage itself, and one for its webhooks:

(stdout)

HOMEPAGE_TRAEFIK_HOST: Enter the homepage domain name (eg. homepage.example.com)

: homepage.pi.example.com

HOMEPAGE_WEBHOOK_HOST: Enter the separate webhook domain name (eg. homepage-webhook.example.com)

: homepage-webhook.pi.example.com

It is recommended to enable some form of sentry authorization to protect homepage, e.g., with OAuth2:

(stdout)

? Do you want to enable sentry authorization in front of this app (effectively making the entire site private)?
  No
  Yes, with HTTP Basic Authentication
> Yes, with Oauth2
  Yes, with Mutual TLS (mTLS)

? Which authorization group do you want to permit access to this app?
> admin

Tip

This will allow only the admin authorization group to access this instance.

Remember, you can create extra authorization groups in the Traefik config, that way you can have separate user access per instance.

HOMEPAGE_AUTO_CONFIG

Homepage has optional auto configuration:

If HOMEPAGE_AUTO_CONFIG=true, homepage will create a template automatically that will discover all of your existing services.
If HOMEPAGE_AUTO_CONFIG=false, homepage will clone a default template from a git repository, or you may provide your own repository via HOMEPAGE_TEMPLATE_REPO.

For now, enable the auto-configuration:

(stdout)

? Do you want to auto-configure Homepage and to discover all of your
running d.rymcg.tech apps of the current docker context? (Y/n) Yes

Install Homepage

Run this on the Raspberry Pi

pi make homepage install wait

Add two new routes on the sentry (droplet)

You need to create two routes: one for homepage, and one for the webhooks:

Run this on the Raspberry Pi

sentry make traefik config

(stdout)

? Traefik:
> Config
  Install (make install)
  Admin
  Exit (ESC)

? Traefik Configuration:
^ Entrypoints (including dashboard)
  TLS certificates and authorities
  Middleware (including sentry auth)
> Advanced Routing (Layer 7 / Layer 4 / WireGuard)
  Error page template
  Logging level
  Access logs

? Traefik routes
> Configure layer 7 TLS proxy
  Configure layer 4 TCP/UDP proxy
  Configure wireguard VPN

? Layer 7 TLS Proxy:
  List layer 7 ingress routes
> Add new layer 7 ingress route
  Remove layer 7 ingress routes
  Disable layer 7 TLS Proxy

Enter the public domain (SNI) for the route:

: homepage.pi.example.com

Enter the destination IP address to forward to:

: 10.13.16.2

Enter the destination TCP port to forward to:

: 443

> Do you want to enable Proxy Protocol for this route? Yes

## Layer 7 TLS Proxy is ENABLED.
## Configured Layer 7 Routes:
Entrypoint               Destination_address  Destination_port  Proxy_protocol
----------               -------------------  ----------------  --------------
homepage.pi.example.com  10.13.16.2           443               2

? Layer 7 TLS Proxy:
  List layer 7 ingress routes
> Add new layer 7 ingress route
  Remove layer 7 ingress routes
  Disable layer 7 TLS Proxy

Enter the public domain (SNI) for the route:

: homepage-webhooks.pi.example.com

Enter the destination IP address to forward to:

: 10.13.16.2

Enter the destination TCP port to forward to:

: 443

> Do you want to enable Proxy Protocol for this route? Yes

## Layer 7 TLS Proxy is ENABLED.
## Configured Layer 7 Routes:
Entrypoint                       Destination_address  Destination_port  Proxy_protocol
----------                       -------------------  ----------------  --------------
homepage.pi.example.com           10.13.16.2           443               2
homepage-webhooks.pi.example.com  10.13.16.2           443               2

Press ESC three times to go back to the main menu, and re-install Traefik:

(stdout)

? Traefik:
  Config
> Install (make install)
  Admin
  Exit (ESC)

After installation, press ESC to quit the config tool.

Open Homepage

Open https://homepage.pi.example.com in your web browser.

Redeploy Homepage after you have installed new services

The Homepage auto-config only happens at install time. If you install or remove services, you should reinstall homepage to update the dashboard:

Run this on the Raspberry Pi

pi make homepage install

Customize Hompepage template

To customize your homepage template, you must set HOMEPAGE_AUTO_CONFIG=false and provide HOMEPAGE_TEMPLATE_REPO in the .env_{CONTEXT}_{INSTANCE} file:

Run this on the Raspberry Pi

pi make homepage reconfigure \
  var=HOMEPAGE_TEMPLATE_REPO=https://github.com/EnigmaCurry/d.rymcg.tech_homepage-template.git

pi make homepage reconfigure \
  var=HOMEPAGE_AUTO_CONFIG=false

Tip

You can fork the default template repository and provide your own HOMEPAGE_TEMPLATE_REPO and it will automatically pull the template from your URL.

If your template repository is not public, you must create a deploy key:

Run this on the Raspberry Pi

pi make homepage git-deploy-key

This will generate and save a new SSH key in the config volume (/app/config/ssh/id_rsa). It will print out the public key, which you need to copy and paste into your Forgejo, Github, or Gitlab repository settings (Search for Deploy Key in the settings, and add this public key to allow cloning from the private repository.)

Reloading webhook

An optional feature when using a custom template repository (HOMEPAGE_TEMPLATE_REPO) is you can send a webhook from your git forge to your homepage instance, telling it to restart and pull the changes automatically.

First you must enable HOMEPAGE_TEMPLATE_REPO_SYNC_ON_START=true in the homepage .env_{CONTEXT}_{INSTANCE} file. Note that this setting will delete your existing config everytime homepage restarts, and it will redownload the template repository from scratch:

Run this on the Raspberry Pi

pi make homepage reconfigure \
  var=HOMEPAGE_TEMPLATE_REPO_SYNC_ON_START=true

Next you must configure your Forgejo, Github, or Gitlab repository to send the webhook on git push events:

Webhook URL is of the format: https://homepage.example.com/reloader/restart
Choose the data type: application/json
Webhook Secret is found in your .env_{INSTANCE}_{CONTEXT} as HOMEPAGE_RELOADER_HMAC_SECRET. This secret is used to validate that the request is actually coming from your git host.

Run this on the Raspberry Pi

pi make homepage dotenv_get \
  var=HOMEPAGE_RELOADER_HMAC_SECRET

(stdout)

xXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxX

No extra authorization header is required.

Finally, redeploy homepage:

Run this on the Raspberry Pi

pi make homepage install