Be it helping you organize your often-used services or granting your non-technical roommates/family members access to all your self-hosted apps, dashboards can be a great addition to any home lab's repertoire. But with tons of these apps floating around, it can be a bit hard to find the right one for your tinkering needs.

When I came across Homepage a while ago, I was mesmerized by the features offered by this neat dashboard tool. If you’ve never heard of it or are looking for a detailed guide to help you set it up on your home lab, you’ve come to the right place!

What’s so special about Homepage?

All the customization options you could ask for

If I were to use a word to describe Homepage, it’d be flexible. That’s because you can customize every aspect of the Homepage UI to your liking with the help of YAML files. Besides the obvious aesthetic perks, you can modify certain configuration files to track the key metrics of your apps, meaning Homepage can also double as a makeshift monitoring service. Plus, you can even add custom bookmarks and modify their appearance using just a few lines of code.

Deploying a Homepage container

Using Proxmox

Homepage can be run as a containerized app in a handful of ways. As usual, Proxmox users have the simplest installation procedure, as you can leverage the simple Proxmox VE-Helper Scripts to get the container up and running in mere seconds.

1. Head to the Shell tab of your Proxmox node.
2. Paste the following code inside to begin the Homepage installation process.

   bash -c "$(wget -qLO - https://github.com/community-scripts/ProxmoxVE/raw/main/ct/homepage.sh)"

3. Tap Yes twice and wait for the script to initialize the container.
4. Use the IP address displayed in the terminal to access the Homepage UI.

On a typical desktop OS

But if you’re on a Linux distro, you can deploy the Homepage container using Docker Engine. To do so,

1. Launch the terminal app.
2. Use the nano editor to create and access the docker-compose.yml file for Homepage.

   sudo nano docker-compose.yml

3. Open the official Homepage repo on your browser and copy the code under the Using docker compose section into the file you created earlier.
4. Create a new folder for the Homepage configuration files using the File Manager and copy its Path.
5. Head back to the docker-compose.yml file and replace the /path/to/config field under the volumes header with the path of the same folder you created in the last step.
6. Spin up the Homepage container with the docker compose command.

   sudo docker compose up -d

7. You can access the container by entering the IP address of your system followed by a colon (:) and the port number 3000 into a web browser.

For those on Windows, you can follow along using Docker. But if you haven’t set up Docker yet, you can run the same scripts inside a Linux VM deployed using a Type-2 hypervisor.

Configuring the Homepage UI

By now, you may have noticed that the web UI is rather barebones, meaning you’ll have to modify a couple of YAML files to calibrate Homepage to your liking. Regardless of the method you’ve used to create the Homepage container, the overall procedure is largely the same.

1. If you’ve used the Proxmox VE-Helper Script, you’ll have to open the Console tab of the newly Homepage container and use the cd command with the /opt/homepage/config/ path to access the config files.

   cd /opt/homepage/config/

   But if you're using a desktop OS, you'll have to enter the path of the Homepage configuration folder instead of /opt/homepage/config/

   sudo cd /location_of_config/

2. Open the settings.yaml file using the nano text editor.

   nano settings.yaml

   On a normal distro, you’ll have to add sudo before the command or run sudo -s to run the commands as the root user.
3. If you wish to modify the background of the dashboard, you can add the background field alongside a colon (:) and the URL of the background image.
4. Be sure to press Ctrl+X, followed by Y and Enter to save and exit the file.
5. Next, launch the services.yaml file with the help of the nano editor.

   nano services.yaml

6. You can add the name, href (IP address) tag, description, and other details of your services under the Group name before using the Ctrl+X, Y, and Enter keys to head back to the terminal/container Console.
7. When you want to add the bookmarks to your Homepage web UI, you can open the bookmarks.yaml file using the nano text editor.

   nano bookmarks.yaml

8. Once inside, you can add the abbr (abbreviation) and href (URL) tags to link your favorite websites to Homepage.
9. Remember to tap Ctrl+X, Y, and Enter to head back to the terminal.
10. Enter reboot into the terminal to apply the changes to your Homepage Dashboard.

    reboot

Building your ideal dashboard with Homepage

Aside from these modifications, you can also import widgets for your self-hosted apps with the widget keyword followed by a colon (:), name, href, and a couple of other elements inside the services.yaml file. Since these extra fields vary from one app to the other, you’ll have to consult the official Homepage page to find the specific elements needed for your favorite widgets. Just make sure you follow the correct indentation, as even a single mistake in the formatting will result in a broken dashboard. But if Homepage seems too challenging, it might be a good idea to put together a dashboard using a beginner-friendly Heimdall container instead.