In this tutorial, we'll learn how to install and configure Heimdall on Ubuntu 24.04 server.
What is Heimdall?
Heimdall is a lightweight and user-friendly application dashboard designed to help us organize and access our self-hosted services, web tools, and frequently used links from a single, centralized interface. It acts as a visual start page where we can group applications, assign icons, and display useful app-specific information. Heimdall is popular in homelab and server environments because it requires almost no technical configuration and works smoothly with Docker, making deployment and updates easy.
Prerequisites
Before we begin, ensure we have the following:
- An Ubuntu 24.04 on dedicated server or KVM VPS.
- Basic Linux Command Line Knowledge.
- A domain name pointing A record to server IP.
How to Install and Configure Heimdall on Ubuntu 24.04
1) Update the server and install Docker Engine + Compose
Add Docker's official GPG key:
sudo apt-get update
sudo apt-get install ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc
Add the repository to Apt sources:
echo \
"deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu \
$(. /etc/os-release && echo "${UBUNTU_CODENAME:-$VERSION_CODENAME}") stable" | \
sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt-get update
Install Docker
sudo apt-get install docker-ce -y
Verify
docker --version
docker compose version
Docker + Compose is the most reliable way to run Heimdall in 2025.
2) Prepare directories and permissions
sudo mkdir -p /opt/heimdall
sudo chown -R $USER:$USER /opt/heimdall
Heimdall will store all settings in /opt/heimdall/config via a bind mount, which makes upgrades painless.
3) Create the Docker Compose file
Execute following command to create Docker compose file in /opt/heimdall directory:
cat > /opt/heimdall/docker-compose.yml <<'YAML'
services:
heimdall:
image: lscr.io/linuxserver/heimdall:latest
container_name: heimdall
environment:
- PUID=1000 # run as our user id
- PGID=1000 # run as our group id
- TZ=Asia/Kolkata # set timezone
volumes:
- /opt/heimdall/config:/config
ports:
- 8080:80
restart: unless-stopped
YAML
The LinuxServer image exposes HTTP(80)/HTTPS(443) and persists all app data under /config.
4) Start Heimdall
cd /opt/heimdall
docker compose up -d
docker compose logs -f
Heimdall’s first-run page lets us set the language, create tiles, and switch themes.
5) Open firewall for web access (UFW)
If UFW is enabled, allow web traffic:
sudo ufw allow 80,443/tcp
sudo ufw status
Nginx docs confirm these are the standard ports to expose HTTP/HTTPS traffic.
6) Production-grade HTTPS with Nginx reverse proxy
If we’ll use a domain like dashboard.example.com, run Heimdall on an internal port and proxy with Nginx + Let’s Encrypt. This avoids binding the container directly to 80/443 and lets Nginx manage TLS.
Install Nginx
sudo apt update
sudo apt install -y nginx
nginx -v
Add Basic Auth with Host Nginx. Install htpasswd tool
sudo apt install -y apache2-utils
Create the password file
sudo htpasswd -c /etc/nginx/.htpasswd admin
Enter password when asked.
To add more users later (without overwriting):
sudo htpasswd /etc/nginx/.htpasswd anotheruser
Create an Nginx server block
sudo tee /etc/nginx/sites-available/heimdall >/dev/null <<'NGINX'
server {
server_name dashboard.example.com;
location / {
proxy_pass http://127.0.0.1:8080;
proxy_http_version 1.1;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
auth_basic "Restricted Area";
auth_basic_user_file /etc/nginx/.htpasswd;
}
}
NGINX
sudo ln -s /etc/nginx/sites-available/heimdall /etc/nginx/sites-enabled/heimdall
sudo nginx -t
sudo systemctl reload nginx
Nginx proxying to a local app port is the standard pattern here.
Issue a Let’s Encrypt certificate
sudo apt install -y certbot python3-certbot-nginx
sudo certbot --nginx -d dashboard.example.com
Obtain and install a certificate
sudo certbot --nginx -d dashboard.example.com
Test auto-renewal
sudo certbot renew --dry-run
This auto-configures Nginx with HTTPS and sets up renewal timers.
Navigate to browser and access:
https://dashboard.example.com
7) Backup, update, and rollback
Backup config:
# Stop for a consistent snapshot (optional but safe)
docker compose stop
tar czf ~/heimdall-backup-$(date +%F).tar.gz -C /opt heimdall
docker compose start
Update to the latest image:
cd /opt/heimdall
docker compose pull
docker compose up -d
All settings live under /opt/heimdall/config, so upgrades are typically seamless with the LinuxServer image.
Conclusion
We successfully deployed and configured Heimdall on Ubuntu 24.04 using a stable and maintainable setup. With Docker and Nginx, we created a secure and scalable environment that helps us manage applications and services from one dashboard. This setup is reliable for self-hosted projects, home labs, and small business servers where quick access to tools improves productivity.
