Constructing a Simple Homelab Dashboard with Homepage

Introduction

As we get further into homelabbing, there comes an abundance of tools and services that we might have a hard time keeping track of. In times like these, it would be most convenient to create our own dashboard. This is where Homepage will come in handy. Homepage is a highly customizable homepage (or startpage / application dashboard) with Docker and service API integrations. Simply put, we can have an application dashboard to manage all of our homelab services.

Having previously installed Portainer and Adguard Home, I'll login to the Portainer dashboard and remove port 3000 from Adguard Home's port mapping settings. This is because Homepage currently runs on port 3000, and Adguard Home's setup page ran on port 3000—that of which we don't need anymore.

Installation

We'll be needing to create the config volume for Homepage. Navigate to Volumes > Create Volume, then name it whatever you'd like. I'll be naming it 'homepage_conf'.

Once the volume is created, pull the Homepage image from Docker Hub. The image name we'll be using is 'gethomepage/homepage:latest'

Next, we'll go to create the container. Add port 3000:3000 for TCP and UDP

Map the previously made config volume to the /app/config volume inside of the container

Set the DNS server to Adguard's IP address.

Since I want to access this over the host IP address, I'll be adding my server's IP address as the HOMEPAGE_ALLOWED_HOSTS environmental variable.

Last, set the restart policy to 'unless stopped'

Finally, deploy the container. After deployment, you will be able to visit the page at http://<YOUR_SERVER_IP>:3000.

This is the default homepage template. We can customize the layout following their documentation.

Customizing Homepage to Your Needs

You can customize Homepage to however you'd like, but continuing on from the homelabbing series, I'll be setting up an information widget for weather, along with service widgets for Portainer, Adguard Home, and future services I configure.

To get started, I'll SSH into my home server and connect to a shell in my container.

Configuring a Weather Widget

Reference

I want my weather widget to sit at the top right of the screen, adjacent to the search bar. We'll be using Open-Meteo, Homepage's recommended weather widget. In our docker container shell, navigate to /app/config

We're going to edit the widgets.yaml file. Here's the template of what I'm going to use.

1- openmeteo:
2    label: Kyiv # optional
3    latitude: 50.449684
4    longitude: 30.525026
5    timezone: Europe/Kiev # optional
6    units: metric # or imperial
7    cache: 5 # Time in minutes to cache API responses, to stay within limits
8    format: # optional, Intl.NumberFormat options
9      maximumFractionDigits: 1

I'll just be including the latitude, longitude, units, and cache into the config. I changed the latitude and longitude to my preferred location. This block will be placed at the end of the file to be rendered the way I want it to.

After waiting a few minutes, changes can be seen reflected in Homepage.

Configuring Service Widgets

Supported Service Widgets

Aside from creating adding services, I'll also be customizing the look and feel of the layout. The default services configuration is as follows

1---
2# For configuration options and examples, please see:
3# https://gethomepage.dev/configs/services/
4
5- My First Group:
6    - My First Service:
7        href: http://localhost/
8        description: Homepage is awesome
9
10- My Second Group:
11    - My Second Service:
12        href: http://localhost/
13        description: Homepage is the best
14
15- My Third Group:
16    - My Third Service:
17        href: http://localhost/
18        description: Homepage is 😎

I'm just going to have one group, with first service being Portainer.

After following this guide, this is what it looks like.

You can repeat this for other services, and make custom layouts for your own taste.