If you are running multiple self-hosted services, you will most likely want some quick way to access them, and whilst there are various options, such as dashy, or heimdall, I decided that homepage was the best one for me.
In short, homepage is a dashboard of interactive shortcuts you access via a webpage. However it’s much more than that, as I’ll explain.
The image I deployed for my homepage is available here – https://github.com/gethomepage/homepage
The compose.yaml file I have is shown below:
As a compose file, it’s pretty basic. The power of homepage isn’t revealed until you deploy it and start configuring the various settings.
Once homepage is deployed, you will have a number of files to configure:
As you can see, most of these are also YAML files – so they can easily be altered in your editor of choice. Personally, for small edits I use nano, but I find it easier to copy the data into something like notepad and then copy back across once I’ve finished any larger edits.
The services.yaml file is the one which you use to configure the links to the sites and services you want to have on your homepage.
The bookmarks.yaml file is similar to services, but is simplified and can only contain links, whereas services is more flexible with what you can configure. I don’t use the bookmarks file in my deployment.
The settings.yaml file is used to define how you want the services to display.
The widgets.yaml file is used to add other components to your homepage, such as a clock, weather, system information, and much more.
The docker.yaml file allows you to specify other containers you can link to homepage which will allow you to show statistics, and other data about those containers.
The settings.yaml file allows for you to define how the items on your homepage are displayed. The background section is self-explanatory – in my case, I have an image hosted on one of my other containers (an apache web server) which I use as my background
In my services.yaml file I have a number of groups – The values in the settings file defines how those groups are displayed, so here we can see that the group named Media is to be shown on a tab called personal, and I’ve defined it to show the services in rows of data across 2 columns.
The Services group is also on the Personal tab, but is configured across 4 columns – as shown below:
I have these configured like this just so that it adds a bit of variance to the homepage, plus it consumes less screen estate by having smaller tabs.
To add data to a different tab, simply use a different name for the tab you want to show. In the example below, I have another tab called cyber
Which produces the below page:
As mentioned, services are defined in the services.yaml file:
Services are grouped using the same name as those you use in the settings.yaml file – This allows homepage to place the data in the correct place.
Services have a number of values:
- href – This is the URL to the service – This is the only mandatory value
- icon: This is used to show an image for the service – optional
- description: allows you to add a description of what the service is – optional
When viewing your homepage, you can collapse / expand groups by clicking the group name. Groups will be displayed in expanded mode by default, however you can add an additional values that shows groups in a collapsed state on page load.
You can specify individual groups to be collapsed (initiallyCollapsed:true), or all groups (groupsInitiallyCollapsed:true). These values need to be added to the settings.yaml file
Additional values for the services include ping & sitemonitor. Both values achieve the same thing, but work slightly differently – ping uses the ping command of the host and may not always get a response if ICMP is being blocked by the service you are pinging, whereas sitemonitor utilises HTTP HEAD & GET requests
If you use either of these options, by default they will show the response time for the resource in milliseconds, however you can configure this in the settings.yaml file to show either a coloured dot, or the words up / down
By default, when you click any of the services on your homepage, the service will open in a new tab – this can be configured with the target value. Options for this are _blank to open in a new tab, _self to open in the same tab, and _top to open in a new window.
The widgets.yaml file allows you to add content to your homepage that shows data from either your system, or the services you link to.
Widgets you can add include:
- Date & Time – Display the date and time in a style of your choosing
- Glances – Display resource data of the host, or another machine in your network – to use this the machine needs to be running glances in webserver mode
- Greeting – Displays a greeting message
- Kubernetes – Displays information about your Kubernetes cluster
- Logo – Display a logo of your choosing
- Longhorn – Pulls storage utilization metrics from the Longhorn storage driver on Kubernetes
- OpenMeteo – Displays weather for the location(s) of your choice from the OpenMeteo API
- OpenWeatherMap – Displays weather for the location(s) of your choice from the OpenWeatherMap API
- Resources – Displays system resources
- Search – Displays a search box for the search provider of your choice
- Stocks – Displays stocks information via the Finnhub.io API
- UniFi Controller – Allows you to display network data form a configured UniFi device
