How to Self-Host Heimdall with Docker Compose

What Is Heimdall?

Heimdall is a self-hosted application dashboard that organizes links to all your web services in one clean interface. It replaces browser bookmark bars and scattered tabs with a single, searchable homepage. Heimdall’s standout feature is its three-tier app system: generic links, pre-styled foundation apps, and enhanced apps that pull live data from services like Sonarr, Pi-hole, and Plex via API integrations.

Official site: github.com/linuxserver/Heimdall

Prerequisites

A Linux server (Ubuntu 22.04+ recommended)
Docker and Docker Compose installed (guide)
200 MB of free disk space
128 MB of RAM (minimum)

Docker Compose Configuration

Create a docker-compose.yml file:

services:
  heimdall:
    image: lscr.io/linuxserver/heimdall:v2.7.6-ls338
    container_name: heimdall
    environment:
      - PUID=1000          # User ID for file permissions
      - PGID=1000          # Group ID for file permissions
      - TZ=America/New_York # Your timezone
      - ALLOW_INTERNAL_REQUESTS=true  # Required for Enhanced Apps on your local network
    volumes:
      - heimdall_data:/config
    ports:
      - "8090:80"     # HTTP web interface
      - "8443:443"    # HTTPS (self-signed certificate)
    restart: unless-stopped

volumes:
  heimdall_data:

Start the stack:

docker compose up -d

Initial Setup

Open http://your-server-ip:8090 in your browser
The dashboard loads immediately — no account creation needed
Click the wrench icon in the bottom-right corner to access settings
Add your first application by clicking the + button

Adding Applications

Heimdall supports three tiers of applications:

Tier	Features	Example
Generic	Custom name, URL, icon, and color	Any web service
Foundation	Pre-configured icons and styling	200+ supported apps
Enhanced	Live API data on the dashboard tile	Sonarr, Radarr, Pi-hole, Plex, Tautulli

For Enhanced Apps, you’ll need to provide the API key or URL for the target service. The tile then displays live stats (e.g., number of monitored items in Sonarr, current Pi-hole block count).

Configuration

Environment Variables

Variable	Default	Description
`PUID`	`1000`	User ID inside the container — match your host user
`PGID`	`1000`	Group ID inside the container — match your host group
`TZ`	`Etc/UTC`	Timezone in TZ database format
`ALLOW_INTERNAL_REQUESTS`	`false`	Set to `true` so Enhanced Apps can reach services on your LAN

Tags and Organization

Group your applications with tags for quick filtering. Common tag schemes:

By function: media, monitoring, networking, productivity
By server: nas, pi, vps
By priority: daily, occasional, admin

Password Protection

Heimdall doesn’t have built-in authentication. Add HTTP basic auth via the bundled nginx:

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

Then edit /config/nginx/site-confs/default.conf inside the container and uncomment the auth_basic lines.

For proper multi-user authentication, use a reverse proxy with Authelia or Authentik.

Reverse Proxy

Place Heimdall behind a reverse proxy for SSL and custom domain access. See Reverse Proxy Setup for full instructions.

Nginx Proxy Manager: Point your domain to http://heimdall:80 using the container name on your Docker network.

Backup

Back up the /config volume — it contains the SQLite database, all app configurations, custom icons, and background images:

docker compose stop
tar czf heimdall-backup-$(date +%Y%m%d).tar.gz /path/to/heimdall/config
docker compose start

See Backup Strategy for automated approaches.

Troubleshooting

Enhanced Apps Show “No Data”

Symptom: Enhanced app tiles display but show no live stats. Fix: Set ALLOW_INTERNAL_REQUESTS=true in your Docker Compose environment. Without this, Heimdall blocks API requests to private IP ranges (RFC1918). Restart the container after changing.

Permission Denied Errors on Startup

Symptom: Container logs show permission errors accessing /config. Fix: Ensure PUID and PGID match your host user’s UID/GID. Check with id on the host.

Slow Page Load with Many Apps

Symptom: Dashboard takes several seconds to load with 50+ apps. Fix: Disable Enhanced App polling for apps you don’t need live data from. Switch them to Foundation tier instead.

Custom Icons Not Displaying

Symptom: Uploaded custom icons show broken image placeholders. Fix: Icons must be placed in /config/www/icons/ inside the container. Supported formats: PNG, SVG, ICO. Clear browser cache after uploading.

Resource Requirements

Metric	Value
RAM	~50 MB idle, ~100 MB with Enhanced Apps polling
CPU	Very low — serves static pages with minimal PHP processing
Disk	~100 MB for application + user icons/backgrounds

Frequently Asked Questions

Does Heimdall have user authentication?

Not natively. Heimdall has no built-in user accounts. You can add HTTP basic auth through its bundled nginx config, or place it behind Authelia or Authentik for proper authentication.

What are Enhanced Apps in Heimdall?

Enhanced Apps are service integrations that pull live data from your self-hosted services via their APIs. For example, a Sonarr Enhanced App tile shows the number of monitored series and upcoming episodes. You provide the service URL and API key, and Heimdall polls it for stats.

Is Heimdall still actively maintained?

Heimdall receives maintenance updates through the LinuxServer.io team, but the core project’s development has slowed. For a more actively developed alternative with similar features, consider Homarr or Homepage.

How does Heimdall compare to Homarr?

Heimdall is lighter and simpler. Homarr has more features — a drag-and-drop editor, more widget types, and better Docker integration. Homarr requires more RAM (~200 MB vs ~50 MB). Choose Heimdall if you want something lightweight with basic API integrations. Choose Homarr if you want a more feature-rich dashboard experience.

Can I import/export my Heimdall configuration?

Heimdall stores its configuration in a SQLite database in the /config volume. There’s no built-in import/export feature. To migrate, back up and restore the entire /config directory.

Verdict

Heimdall is the right dashboard if you want live data from your services on a single page. The Enhanced Apps feature sets it apart — seeing Sonarr queue length, Pi-hole stats, and Plex activity at a glance saves constant tab-switching. It’s heavier than minimalist alternatives like Homer or Flame but lighter than full-featured options like Homarr or Organizr. The LinuxServer.io maintenance gives it reliable, regular updates.

If you just need clickable links with no API integrations, Homer is simpler. If you want more customization and service integrations, Homarr has surpassed Heimdall in features.