by In this tutorial, we will show you how to self-host the Heimdall dashboard using Docker.
Heimdall is a super neat dashboard for all of your applications. It provides an elegant solution for accessing your self-hosted web applications. If you like to self-host software, you will love using Heimdall as your homepage.
You can even use this dashboard to bookmark websites in general. It even has a built-in search bar you can use that makes the
One of the neatest things about Heimdall is that it can be entirely configured through its web interface. You don’t have to mess around with different configuration files like some other dashboards require.
One of the easiest ways to get the Heimdall Dashboard up and running on your system is to use Docker. Docker allows us to bring this dashboard online with just a few lines of config. If you are self-hosting software already, you likely use Docker already.
Installing and Running the Heimdall Dashboard with Docker
Over the following few sections, we will show you how to install and set up the Heimdall Dashboard using a Docker container.
One of the critical things about this dashboard, and something you will see shortly, is how easy it is to set up and configure.
Preparing your System
1. We will need to install the Docker runtime before we can set up the Heimdall Docker container.
If this is your first time installing Docker, we recommend our installation guide for Docker on Linux based systems.
https://pimylifeup.com/linux-docker-install/2. Once Docker has been installed, your next step is to create a folder to store the stack and config files for Heimdall.
In our case, we will be using the mkdir command to create a directory at “/opt/stacks/heimdall“.
sudo mkdir -p /opt/stacks/heimdall3. After creating the directory, change into it by using the cd command.
cd /opt/stacks/heimdallWriting a Docker Compose File to Manage the Heimdall Dashboard
4. With the Heimdall directoryc reated, we can move on to creating the Docker Compose file for it. This Compose file will tell Docker the Heimdall image we want to download and how to run it.
You can begin writing the “compose.yaml” file using the command below. We will use the Nano text editor as it is relatively easy for beginners to get started with. You can use whichever text editor you want to use.
sudo nano compose.yaml5. Within this file, you will want to enter the following lines. The Heimdall Dashboard is relatively easy to set up and doesn’t have many environment variables that need configuring.
While you fill out this file, there are three placeholders you will want to replace.
<TIMEZONE>: This first placeholder must be replaced with a TZ identifier for your time zone. This allows Heimdall to show the correct time for where you live.
You can find a list of these TZ identifiers on Wikipedia.
For example, based on where we live, we would use the TZ identifier “Australia/Hobart“.<HTTPPORT>: The next placeholder is where you will specify the HTTP port on which Heimdall should be exposed. You can use any port, but we recommend two different ones.80– This is the default HTTP port. Use this if it’s not already in use and you want to be able to access Heimdall without specifying a port.8080– If your port 80 is already in use by another service, this port is a great alternative. Just remember you must specify this port when accessing the dashboard.
<HTTPSPORT>: Heimdall automatically sets up a self-signed HTTPS connection. You can use this placeholder to specify the port from which the HTTPS connection should be available.443– Use this port if you want to access Heimdall directly through its URL.8443– This port is a great alternative if you are already using a service that sits on the HTTPS protocol.
services:
heimdall:
image: lscr.io/linuxserver/heimdall:latest
container_name: heimdall
environment:
- PUID=1000
- PGID=1000
- TZ=<TIMEZONE>
volumes:
- ./config:/config
ports:
- <HTTPPORT>:80
- <HTTPSPORT>:443
restart: unless-stopped6. Once you have filled out the Compose file, you can save and quit by pressing CTRL + X, Y, and then ENTER.
Starting up the Heimdall Dashboard
7. With the Docker Compose file written, all we need to do to start up the Heimdall Dashboard is to run the following command.
This command will get Docker to read the Compose file and start up all the containers in it using the specified configuration. Using the “-d” option, we will get Docker to detach from the terminal and continue running in the background.
docker compose up -dAccessing your New Dashboard
8. With the Heimdall dashboard now up and running you will want to know how to access it.
If you don’t know the IP address of your machine, try using the hostname command to retrieve it.
hostname -I9. After getting your IP address, all you need to do is go to the following address in your web browser.
Ensure that you replace “<IPADDRESS>” with the IP of your machine.
http://<IPADDRESS>However, if you are not using the standard 80 and 443 ports, you will need to specify a port when accessing your Docker powered Heimdall dashboard.
http://<IPADDRESS>:<PORT>Adding Applications to the Heimdall Dashboard
10. You should now have the Heimdall dashboard loaded up in your web browser. While it looks blank now, don’t worry; this dashboard is easy to configure.
To add your first application to Heimdall, click the “Add an application here” link.
11. You only need two elements to add a new application to your Heimdall dashboard. For this example, we will add the Pi-hole Docker installation we have running locally.
- The first thing you need to specify is a name for your application. For our example, this will be “
Pi-Hole“. - Next, you must set a URL for this bookmark to link to your application.
Once you have set these two options, click the “SAVE” button (3.). However, there are plenty of other options within this page that lets you customize how everything is displayed.
Turning on the Heimdall Search Bar
12. To make your Heimdall dashboard an even more useful homepage, you may want to add a search bar. This search bar will allow you to search directly from Heimdall.
To configure this setting, click the cogs icon in the bottom-right corner of the page.
13. On this page, you should see a section labeled “Miscellaneous“. Under this section, there are two options you will want to change.
- The first option allows you to turn the search bar on (1.).
- The second option will allow you to select the default search provider (2.).
14. To enable the homepage search functionality of Heimdall, all you must do is click the toggle (1.).
Once the option is toggled on, click the “SAVE” button (2.).
15. The other option we mentioned allows you to control the default search engine that Heimdall will use (1.). You can change this on the fly, but set the one you use the most.
Once you have set the default search provider, click the “SAVE” button (2.).
16. Below you can see that we have successfully got our Heimdall dashboard up and running using Docker. We have already taken the time to add a few of our most used applications and enabled the search bar.
Updating to the Latest Release of Heimdall
One of the best things about using Docker to self-host the Heimdall dashboard is that it simplifies the whole upgrading process. You don’t have to worry about dealing with any dependency changes, and the whole process can be completed in a few short minutes.
1. Your first step is to move to the directory where we wrote the Compose file for Heimdall. You can move to the correct folder by running the following command within the terminal.
cd /opt/stacks/heimdall2. After changing to where the Compose file sits, we can get Docker to download the latest Heimdall image by using the command below.
This command will pull the new image but won’t upgrade your running containers.
docker compose pull3. To get Docker to upgrade your Heimdall installation to the latest release, all you need to do is run the command below within the terminal.
docker compose up -dConclusion
By this point in the tutorial, you should have the Heimdall Docker container up and running.
This software is a really neat dashboard that allows you to bookmark your self-hosted applications easily. It is one of the easiest dashboards to configure, and it can all be controlled through its web interface.
Please feel free to leave a comment below if you have had any issues with getting Heimdall to run on your machine.
If you liked this guide, we highly recommend exploring some of our many other Docker tutorials. There is a huge amount of different software you can easily self-host using containers.
