Homepage

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

Configure Homepage

pi make homepage config

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

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:

? 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

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:

? 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

pi make homepage install wait

Add two new routes on the sentry

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

sentry route set pi \
  homepage.pi.example.com \
  --restart false

sentry route set pi \
  homepage-webhooks.pi.example.com \
  --restart true

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:

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:

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:

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.

pi make homepage dotenv_get \
  var=HOMEPAGE_RELOADER_HMAC_SECRET

xXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxX

• No extra authorization header is required.

Finally, redeploy homepage:

pi make homepage install