Deploying Heimdall

Introduction

Heimdall is an elegant application dashboard designed to organize all your web applications and services in one place. Named after the Norse god who guards the Bifrost bridge, Heimdall serves as the gateway to your self-hosted applications, providing quick access to any number of web services with a clean, customizable interface.

Built with Laravel and designed with simplicity in mind, Heimdall requires no database setup and stores all configuration in simple files. The dashboard supports enhanced applications that display live statistics and status information, making it easy to monitor your services at a glance.

Key highlights of Heimdall:

Application Dashboard: Centralize access to all your web applications
Enhanced Applications: View live stats from supported services (Sonarr, Radarr, etc.)
No Database Required: Simple file-based configuration
Customizable Layout: Drag-and-drop arrangement of application tiles
Custom Backgrounds: Personalize with your own background images
Search Integration: Quick search across your applications
User Management: Optional authentication with multiple users
Mobile Friendly: Responsive design works on all devices

This guide walks through deploying Heimdall on Klutch.sh using Docker, adding your applications, and customizing your dashboard.

Prerequisites

Before deploying Heimdall on Klutch.sh, ensure you have:

A Klutch.sh account
A GitHub account with a repository for your Heimdall configuration
Basic familiarity with Docker and containerization concepts
A list of web applications you want to add to your dashboard

Preparing Your Repository

Create a GitHub repository with the following structure:

heimdall-deploy/
├── Dockerfile
├── .dockerignore
└── README.md

Creating the Dockerfile

Create a Dockerfile using the LinuxServer Heimdall image:

FROM lscr.io/linuxserver/heimdall:latest

# Environment variables for configuration
ENV PUID=${PUID:-1000}
ENV PGID=${PGID:-1000}
ENV TZ=${TZ:-Etc/UTC}

# Expose HTTP and HTTPS ports
EXPOSE 80
EXPOSE 443

# Health check
HEALTHCHECK --interval=30s --timeout=10s --start-period=30s --retries=3 \
  CMD curl -f http://localhost:80/ || exit 1

Advanced Dockerfile with Optional Features

FROM lscr.io/linuxserver/heimdall:latest

ENV PUID=${PUID:-1000}
ENV PGID=${PGID:-1000}
ENV TZ=${TZ:-Etc/UTC}

# Optional: Allow internal requests for enhanced apps
ENV ALLOW_INTERNAL_REQUESTS=${ALLOW_INTERNAL_REQUESTS:-false}

EXPOSE 80
EXPOSE 443

HEALTHCHECK --interval=30s --timeout=10s --start-period=30s --retries=3 \
  CMD curl -f http://localhost:80/ || exit 1

Environment Variables Reference

Variable	Required	Default	Description
`PUID`	No	1000	User ID for file ownership
`PGID`	No	1000	Group ID for file ownership
`TZ`	No	Etc/UTC	Container timezone
`ALLOW_INTERNAL_REQUESTS`	No	false	Allow requests to internal IPs for enhanced apps

Deploying Heimdall on Klutch.sh

Push Your Repository to GitHub

git init
git add Dockerfile .dockerignore README.md
git commit -m "Initial Heimdall deployment configuration"
git remote add origin https://github.com/yourusername/heimdall-deploy.git
git push -u origin main

Create a New Project on Klutch.sh

Navigate to the Klutch.sh dashboard and create a new project named “heimdall” or “dashboard”.

Create a New App

Within your project, create a new app. Connect your GitHub account and select your Heimdall repository.

Configure HTTP Traffic

Select HTTP as the traffic type
Set the internal port to 80

Set Environment Variables

Configure the following environment variables:

Variable	Value
`PUID`	`1000`
`PGID`	`1000`
`TZ`	Your timezone (e.g., `America/New_York`)

Attach Persistent Volumes

Mount Path	Recommended Size	Purpose
`/config`	1 GB	Heimdall configuration and application data

Deploy Your Application

Click Deploy to start the build process. Klutch.sh will build the container, attach volumes, and start Heimdall with HTTPS enabled.

Access Heimdall

Once deployment completes, access your dashboard at https://your-app-name.klutch.sh.

Configuring Heimdall

Adding Applications

Click the Add button on the dashboard
Select Application
Choose from the application list or create a custom entry
Fill in the application details:
- Name
- URL
- Icon (optional, auto-detected for known apps)
- Color (customize tile color)
Save the application

Enhanced Applications

Some applications support enhanced features showing live statistics:

Supported Applications Include:

Sonarr, Radarr, Lidarr
Plex, Jellyfin, Emby
SABnzbd, NZBget
Transmission, Deluge
Portainer
Pi-hole
And many more

To configure enhanced apps:

Add the application as usual
Enable the “Enhanced” toggle
Enter API key or credentials if required
Statistics will appear on the tile

Organizing Your Dashboard

Drag and Drop:

Click and hold any application tile
Drag to rearrange position
Release to place in new location

Tags and Categories:

Click the settings icon on any application
Add tags to categorize applications
Filter by tags in the dashboard view

Customizing Appearance

Background Image:

Go to Settings > Background
Upload a custom image or enter a URL
Adjust opacity and blur settings

Tile Colors:

Edit any application
Choose a custom color or use auto-detected colors
Adjust icon color for contrast

Password Protection

Enable authentication:

Go to Settings > Users
Create a user account
Enable “Require Login”
Users must authenticate to access the dashboard

Using htpasswd for basic auth:

docker exec -it heimdall htpasswd -c /config/nginx/.htpasswd username

Troubleshooting

Applications Not Loading

Verify application URLs are correct
Check that applications are accessible from the network
For enhanced apps, verify API credentials

Enhanced Stats Not Showing

Ensure API key is correct
Set ALLOW_INTERNAL_REQUESTS=true for internal network apps
Check application logs for connection errors

Configuration Not Saving

Verify persistent volume is mounted at /config
Check file permissions
Ensure sufficient storage space

Additional Resources

Conclusion

Deploying Heimdall on Klutch.sh creates a beautiful, centralized dashboard for accessing all your web applications. The combination of simple file-based configuration, enhanced application support, and customizable appearance makes Heimdall an essential tool for organizing your self-hosted services. With persistent storage, your dashboard configuration and customizations are preserved across deployments.