How to Run Heimdall via LinuxServer.io’s Docker Image

I run a handful of software services in my own home. I have found these services useful and fun to get running, especially while stuck at home during this pandemic.

Most of these services are accessible via a browser. But since they’re all running on one machine, and thus different ports, navigating to them can be a pain. For example, remembering that Duplicacy Web is on port 3875 is no fun.

Browser bookmarks can work just fine, but Heimdall is a tool that provides a little extra layering on top. I find the visual format of the bookmarks makes navigation quick and obvious. This post is about how I set it up using LinuxServer.io’s image.

This is my fifth post documenting containers I use at home. You can also read about how I run the Unifi controller, how I run Plex, how I update DuckDNS, and how I run Duplicacy.

About LinuxServer.io

LinuxServer.io describes their organization as:

A group of like-minded enthusiasts from across the world who build and maintain the largest collection of Docker images on the web. At our core are the principles behind Free and Open Source Software. Our primary goal is to provide easy-to-use and streamlined Docker images with clear and concise documentation.

I’ve been using LinuxServer.io images for a couple of years. That’s because they’re easy to use, clear, and concisely documented, so I tend to check here first when I need a new image.

docker-compose to Portainer

Historically I’ve run my personal containers using docker-compose. But recently I migrated everything to Portainer. I did this for two reasons:

• I was getting tired of juggling half a dozen docker-compose.yml files around.
• I wanted to try Portainer.

Am I entirely happy with this migration? No, of course not. Both approaches have advantages and disadvantages.

But I do like how Portainer lets me navigate to a single dashboard, check the status of running containers, restart them, etc. It’s easier than using an SSH to my host system, finding the correct docker-compose.yml file, and typing the status or restart commands.

Would I migrate to Portainer again? I’m not sure. But I’m willing to run with it for another six months and see how my perspective changes.

Heimdall Container Configuration

Let’s configure a new Heimdall instance within Portainer.

The specific steps

All of these steps are as of Portainer version 2.1.1 in spring 2021. Some of these settings may look dissimilar in different versions, though I would be surprised if they differed significantly.

1. Create a persistent data directory for Heimdall. In my case, that command will be mkdir /mnt/service-data/heimdall.
2. Login to your Portainer instance.
3. Navigate to your containers environment. In my case, that’s in the local environment, then Containers tab.
4. Click the “Add container” button.
5. Begin filling out the below fields.
6. Name: heimdall (or whatever you want to call it. Since will have only one, this nonspecific name is fine.)
7. Registry: GitHub Container Registry
8. Image: ghcr.io linuxserver/heimdall:2.2.2-ls121

I prefer to pin my images to a specific version, but you can use whatever version or level of flexibility you prefer.

1. Click the “Publish a new network port” button.
2. Add TCP port mappings for 80:80 and 443:443.
3. Click the “Advanced container settings” tab.
4. Click the “Volumes” tab.
5. Click the “Map additional volume” button.
6. Add a bind volume mapping of /config to /mnt/service-data/heimdall.
7. Click the Env tab and add three environment variables:
   • PUID=123 (fill in the correct uid for your preferred user)
   • PGID=456 (fill in the current gid for your preferred group)
   • TZ=America/Detroit (fill in the timezone code for your preferred timezone)
8. Click the “Restart policy” tab.
9. Click the “Unless Stopped” button (or whatever your preferred policy is).
10. Click the “Deploy the container” button.

Give this a few minutes, and your container should not be booted. Then, navigate to your system on port 80, and you should be looking at Heimdall.

Heimdall Application Configuration

At this point, you can begin adding annotated bookmarks to wherever you’d like. In my case, that’s my local services.

Techno Tim has a wonderful video about setting up Heimdall itself. I’ll refer you to his video for most of the application configuration and usage.

One thing I appreciate about Heimdall is the list of preprogrammed services. Just about every service I have is known to Heimdall. At a minimum, that means I don’t need to go find an image to represent it. But a couple of them, like Plex and Portainer, show additional interesting information.

Fix Background Image File Size Limit

I ran into the background image file size limit problem that Techno Tim describes in his video.

Following Tim’s instructions :

1. Ensure Heimdall has booted at least once so that its default configuration files have been placed into its storage directory.
2. Edit /mnt/service-data/heimdall/php/php-local.ini.
3. Add one line : upload_max_filesize = 30M.
4. Save the file.
5. Bounce back over to Portainer and restart the container.

Overall I’m happy with my Portainer and Heimdall setup. As mentioned earlier, whether I am still using them six months from now is a different question. Neither is necessarily an improvement over text files and bookmarks, but there are some upsides. Testing them is the only way to decide.

Big thanks to Techno Tim for the awareness of Heimdall, the great video tutorial, and the image file fix.