Creating an Application Dashboard for your Home Lab

Overview

This is the sixth post in the series of blog posts on building a Kubernetes Home Lab. In the previous posts we’ve seen various things about home labs, starting from why and how to build one for yourself, to hosting a couple of applications on your home lab. In this post we are going to build an application dashboard to manage the applications in your home lab.

As you continue using and upgrading your home lab, you’re bound to have multiple applications hosted on it. As the number of applications grows, managing the application URLs and accessing them easily on multiple devices becomes cumbersome. Using browser bookmarks is one of the first solutions that comes to mind to manage this issue. Although they too raise additional problems. First of all, you would have to have the same bookmarks on every device. Even if you choose to sync your bookmarks to your web accounts, e.g. Google, Firefox, etc. you’d still need to sign in to it on each device to have them synced. This is impractical and also poses security risk by increasing your attack surface.

What if you could host an application that would let you store all of your applications in one place and all you would need to do is to open that application URL to navigate to the one you need? Application dashboards let you do exactly that. Heimdall is one of the application dashboards available, others being Homer, Flame, Dashy, etc.

In this post I’ll walk you through installing and configuring the Heimdall application dashboard on my home lab.

Heimdall Application Dashboard

Heimdall is an application dashboard which is aimed at being your browser home page. It is a free and open source, self hosted application. It is a light-weight application that lets you add and manage your application bookmarks. It lets you group similar applications with tags, which comes in handy if you have a large number of bookmarks added to it.

You can also add a search bar to it, to execute web searches with a search engine of your choice. The search bar along with the easy to manage list of bookmarks, makes it perfect for your browser home page.

You can set Heimdall as a home page to all your devices or open the URL from any device to access all your bookmarks. Also, the bookmarks don’t need to be self hosted application bookmarks. You can add any and all urls that you would usually save using the browser’s bookmarks facility.

In addition to this, Heimdall also supports a number of “Enhanced Apps”. These apps let you connect to the application’s APIs to give you the application stats at a glance on the Heimdall dashboard.

Installing Heimdall

As with other applications in this series, Heimdall also offers a container image to install it. You may refer to Heimdall’s GitHub readme for additional ways to install it.

Using container images to install applications is ideal for me for two reasons:

1. Container images contain pre-packaged applications with all of its dependencies included.
2. My home lab is already set up with K3s to host containerized applications.

Hence, in this post, we’ll use the container image along with Acorn to install Heimdall. Acorn is an open-source application deployment framework for Kubernetes. It lets you deploy and manage applications uniformly across environments using a single artifact and a simple CLI. Please refer to Acorn documentation for more details.

Here are all the things you need to install Heimdall using Acorn:

• A kubernetes cluster with kubectl pointing to it
• Acorn CLI installed on local machine
• Acorn installed on the kubernetes cluster
• An Acornfile containing application configuration details
• A persistent volume to mount on the application container

As you can see in my previous posts, I already have the first three items set up in my home lab. Hence let’s proceed to the next step and write an Acornfile for Heimdall.

Creating the Acornfile for Heimdall

An Acornfile is a description of how to build and/or deploy your application to Kubernetes. It contains easy and concise instructions to pull different containers and configure them on Kubernetes so that they can run as a single application.

Heimdall only needs a single container, hence the Acornfile for it is very simple as you can see below. Create a directory for Heimdall application deployment. Copy and paste the below text in a file named Acornfile in that directory.

containers: {
  heimdall: {
    env: {
      "TZ": "Asia/Kolkata"
      "PUID": "1000"
      "PGID": "1000"
    }
    image: "lscr.io/linuxserver/heimdall:latest"
    ports: {
      publish: [
        "8081:80/http",
        "9443:443/http"
      ]
    }
    dirs: {
      "/config": "volume://heimdall-pv-nfs-config"
    }
  }
}

volumes: {
  "heimdall-pv-nfs-config": {
    size: 1G
    class: "nfs-heimdall-conf"
    accessModes: "readWriteMany"
  }
}

The first section in the above file is to define the different containers used in this application. Heimdall only needs a single container, but you may include additional containers here if needed for other applications. As you can see above, the container objects are used to define the various container configurations. In the above case, we have used it to configure the environment variables, the image name, the ports to publish and the volumes to be mounted.

The second object in the file above defines the volumes to use for mounting on the application containers and the specifications for the same. We need to make sure that Kubernetes either has a matching persistent volume available or the storage class specified has a volume provisioner to create a new volume.

We are going to use an NFS volume with this application. It would let us utilize the dedicated storage capacity available on one of the home lab servers, while the application pod is scheduled on any available kubernetes nodes.

Provisioning NFS volume for the Application

Before creating an NFS persistent volume, we first need to create an NFS share on the required server, that has the required storage space. As you have seen in the previous posts, one of my home lab servers has an additional 2TB storage capacity, hence I would be creating my NFS share on that server.

Follow the instructions in my previous post to create an NFS shared directory. Once it is created we can then use below instructions to create the NFS persistent volumes.

First let’s clone my deploy-heimdall repo and update the sc.yaml and pv.yaml files with the NFS share details. Replace the placeholders <YOUR_NFS_SERVER_IP> and <CONF_DIR_PATH_ON_SERVER> with the server IP and shared directory path on the server.

$ git clone https://github.com/samkulkarni20/heimdall-acorn.git    #clone the repo
$ cd heimdall-acorn
$ sed -i 's/NFS_SERVER_IP/<YOUR_NFS_SERVER_IP>/g' {sc.yaml,pv.yaml}
$ sed -i 's/HEIMDALL_CONF_NFS_PATH/<CONF_DIR_PATH_ON_SERVER>/g' {sc.yaml,pv.yaml}

Now create the storage class and persistent volume on Kubernetes with below commands.

$ kubectl create -f sc.yaml     # Create storage classes
$ kubectl create -f pv.yaml     # Create the persistent volumes
Install Application

With the above steps done we can now run the application. Run below acorn command for the same.

$ acorn run -n heimdall .

Once you run the above command, Acorn will download the required container images and configure them according to the specifications in the Acornfile and upload the packaged artifact to the local container registry. The Acorn packaged artifact contains the downloaded container image(s), the application configurations as per the Acornfile and the required Kubernetes object specifications needed to run it.

Once the above command runs successfully, it would print out the application endpoints on which you can access the same. You may also get the application endpoints by running the below command.

Get Heimdall application url

Configuring Heimdall

Once heimdall is installed successfully, use the endpoints provided by Acorn to access the application. At which point you can start configuring it and adding new bookmarks. Click on the “Add an application here” link below or “Application list” menu on the bottom right corner to add a new application link.

Add an application on Heimdall screen

Choose the application type, paste the application link and choose the appropriate tags for the required application. For some applications, which are part of Heimdall’s “Enhanced Apps”, you can also configure the application’s API URL and credentials on this screen. Heimdall will use the additional configuration to show you a quick summary of the same on the dashboard.

Below I’m configuring my Plex Server running in my home lab. Plex is one of the Heimdall enhanced apps, that is why I can configure API URL and a token for authentication. Heimdall will use this info to show some metadata on the Plex bookmark.

Add an application details to Heimdall

Along with adding the applications to the dashboard, you can also enable the web search bar at the top of the dashboard, as well as change the background image.

Enable the search bar and choose web search provider

Update background image setting

You may also choose to customize the CSS and JavaScript for the dashboard by updating it in the Advanced Settings section.

With all the required configurations done, this is how my Heimdall dashboard looks now.

My Heimdall page after configuration

Heimdall as your Homepage / New Tab Page

You can now use the Heimdall application URL and configure it as your browser home page. This would let you open the Heimdall dashboard every time you open a new browser window. Although, in this age of tabbed browsers, you seldom open a new window, making the home page setting almost useless and needing to click on the home icon every time you open a new tab.

If you do want to save yourself that extra click, you can install some extensions such as New Tab Redirect for chrome/chromium and New Tab Override for Firefox.

Conclusion

In this post we saw what an application dashboard is and why you need it. We talked about Heimdall, which is one of the available application dashboards and what it offers. We then installed Heimdall on my home lab using Acorn and we also went over the Heimdall configuration options.

This was the sixth post in our series on home labs for If you haven’t checked out the other posts in this series you can go through them using the list below.

1. Building a Kubernetes Home Lab from the Ground Up
2. Hardware and Networking Setup for My Home Lab
3. Software Setup for My Home Lab
4. Hosting Plex Media Server On My Home Lab
5. Hosting Pi-hole on My Home Lab
6. Creating an Application Dashboard for your Home Lab
7. DIY Cloud Storage: Running Nextcloud on a Kubernetes Home Lab

In my next post, I explain how to deploy a cloud storage solution on your home lab. If you want to learn more about Acorn you can go through the Acorn documentation or join an upcoming Acorn training class.

Sameer Kulkarni is a software engineer with 14+ years of experience and is working as a Principal Engineer at InfraCloud. You can chat with him on Twitter and read more of his work on Medium.

Header Photo by Farzad on Unsplash