In this tutorial, we'll learn how to install and configure Heimdall on AlmaLinux 10 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 AlmaLinux 10 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 AlmaLinux 10
Step 1: Update Server Packages
Regularly updating our server ensures stability and security.
sudo dnf update -y
sudo dnf upgrade -y
Step 2: Install Docker and Docker Compose
Heimdall runs best using Docker for clean, isolated deployment.
sudo dnf install -y dnf-plugins-core
sudo dnf config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo
sudo dnf install -y docker-ce docker-ce-cli containerd.io
Enable and start Docker:
sudo systemctl enable --now docker
Check Docker status:
sudo systemctl status docker
Step 3: Create Directory Structure for Heimdall
mkdir -p ~/heimdall
cd ~/heimdall
Step 4: Create Docker Compose File
nano docker-compose.yml
Add:
services:
heimdall:
image: lscr.io/linuxserver/heimdall:latest
container_name: heimdall
environment:
- PUID=1000
- PGID=1000
- TZ=Asia/Kolkata
volumes:
- ./config:/config
ports:
- 8080:80
restart: unless-stopped
Save the file.
Step 5: Start Heimdall Container
docker compose up -d
Check running containers:
docker ps
Step 6: Allow Firewall Access (If Required)
sudo firewall-cmd --permanent --add-port={80,443}/tcp
sudo firewall-cmd --reload
Configure SELinux (If enabled)
sudo setsebool -P httpd_can_network_connect 1
Step 7: Configure Nginx Reverse Proxy
Install Nginx:
sudo dnf install -y nginx
sudo systemctl enable --now nginx
Create an Nginx config file:
sudo nano /etc/nginx/conf.d/heimdall.conf
Add:
server {
listen 80;
server_name example.com;
location / {
proxy_pass http://127.0.0.1:8080;
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;
}
}
Replace example.com with your domain name.
Test and reload Nginx:
sudo nginx -t
sudo systemctl reload nginx
From now on, Heimdall opens without specifying port 8080.
Step 8: Secure Heimdall with Password Authentication (Basic Auth)
This adds a login prompt before anyone can access the dashboard.
Install the htpasswd tool:
sudo dnf install -y httpd-tools
Create the password file (replace admin with preferred username):
sudo htpasswd -c /etc/nginx/.htpasswd admin
To add more users later:
sudo htpasswd /etc/nginx/.htpasswd username
Edit the Nginx config to enable authentication:
sudo nano /etc/nginx/conf.d/heimdall.conf
Update the location block:
location / {
auth_basic "Protected Dashboard";
auth_basic_user_file /etc/nginx/.htpasswd;
proxy_pass http://127.0.0.1:8080;
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;
}
Test and reload:
sudo nginx -t
sudo systemctl reload nginx
Now the dashboard is protected by credentials.
Step 9: Enable HTTPS with SSL Certificate
Install Certbot:
sudo dnf install -y certbot python3-certbot-nginx
Run SSL auto-configuration (requires domain DNS pointed to server):
sudo certbot --nginx -d example.com
Certbot configures SSL automatically.
Navigate to browser and access:
https://dashboard.example.com
Step 10: Managing Heimdall
Stop container:
docker-compose down
Update to latest version:
docker-compose pull
docker-compose up -d
View logs:
docker logs -f heimdall
Conclusion
We successfully deployed and configured Heimdall on AlmaLinux 10 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.
