Heimdall is a self-hosted application dashboard that serves as a centralized gateway for accessing your most-used services, tools, and applications. Itβs lightweight, highly customizable, and ideal for developers or system administrators who want complete control over their data. This guide will walk you through deploying Heimdall, configuring it with a reverse proxy, managing logs, setting up backups, and more.
Installing Heimdall
π¦ Docker/Docker Compose Setup
Docker is the easiest and most flexible way to deploy Heimdall. Here's how to create and run a docker-compose.yml
file:
- Create a directory for Heimdall:
mkdir -p ~/heimdall && cd ~/heimdall
- Create a
docker-compose.yml
file:
version: '3.7'
services:
heimdall:
image: lscr.io/linuxserver/heimdall:latest
container_name: heimdall
environment:
- PUID=1000
- PGID=1000
- TZ=America/New_York
ports:
- 8080:80
volumes:
- ./config:/config
restart: unless-stopped
- Start the container:
docker-compose up -d
- Verify that Heimdall is running by visiting
http://<your-server-ip>:8080
in your browser.
π Manual Installation
For a manual installation on a Linux server, follow these steps:
- Install dependencies (e.g., PHP, Composer, and a web server):
sudo apt update
sudo apt install -y nginx php-cli php-fpm composer unzip curl
- Download Heimdall and set up permissions:
cd /var/www
sudo curl -LO https://github.com/linuxserver/Heimdall/archive/refs/heads/master.zip
sudo unzip master.zip && sudo mv Heimdall-master heimdall
sudo chown -R www-data:www-data heimdall
-
Configure PHP and Nginx to serve Heimdall. Update
/etc/nginx/sites-available/heimdall
(covered in the next section). -
Restart services:
sudo systemctl restart php7.4-fpm nginx
Configuring Nginx as a Reverse Proxy
π Nginx Configuration
To access Heimdall via a domain, set up Nginx as a reverse proxy:
- Create a new Nginx configuration file:
sudo nano /etc/nginx/sites-available/heimdall
- Add the following server block:
server {
listen 80;
server_name heimdall.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;
}
}
- Enable the configuration and restart Nginx:
sudo ln -s /etc/nginx/sites-available/heimdall /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx
π SSL/TLS Setup
Secure your Heimdall instance with a Letβs Encrypt SSL certificate:
- Install Certbot:
sudo apt install -y certbot python3-certbot-nginx
- Generate and apply an SSL certificate:
sudo certbot --nginx -d heimdall.example.com
- Automate certificate renewal by verifying the Cron job:
sudo systemctl list-timers | grep certbot
Logging and Debugging Heimdall
ποΈ Enabling Debug Logs
If you need detailed logs, enable debug mode in Heimdall:
- Edit the environment variable in your
docker-compose.yml
:
environment:
- DEBUG=true
- Restart the container:
docker-compose down && docker-compose up -d
π Viewing Logs
Access Heimdall logs using Docker or directly from the file system:
- For Docker:
docker logs heimdall
- For manual installations:
tail -f /var/www/heimdall/storage/logs/laravel.log
π οΈ Troubleshooting Common Issues
-
Port conflict: Ensure no other service is using the port defined in
docker-compose.yml
. -
Permission issues: Check that the
www-data
user owns the Heimdall directory:
sudo chown -R www-data:www-data /var/www/heimdall
Backup and Restore
ποΈ File-Based Backups
Back up Heimdallβs configuration files:
- For Docker:
tar -czvf heimdall-config-backup.tar.gz ~/heimdall/config
- For manual installations:
tar -czvf heimdall-backup.tar.gz /var/www/heimdall
π Database Backups
If Heimdall uses a database, back it up with:
mysqldump -u <username> -p heimdall > heimdall-db.sql
π Automated Backup Scripts
Set up an automated backup using a cron job:
- Create a backup script:
nano ~/backup_heimdall.sh
- Add the following content:
#!/bin/bash
tar -czvf ~/heimdall-backup-$(date +%F).tar.gz ~/heimdall/config
- Make it executable and schedule it:
chmod +x ~/backup_heimdall.sh
crontab -e
Updating and Upgrading Heimdall
β¬οΈ Updating Docker Images
Update Heimdall with Docker by pulling the latest image:
- Pull the latest image:
docker-compose pull
- Restart the container:
docker-compose down && docker-compose up -d
π οΈ Manual Updates
For manual installations, update Heimdall by downloading the latest version and replacing the files in /var/www/heimdall
.
Leveraging Heimdallβs Unique Features
π§ Enabling APIs
Heimdall supports APIs for retrieving dashboard data. To use the API:
-
Enable API access in the settings page of the web interface.
-
Use a tool like
curl
to query the API:
curl -H "Authorization: Bearer <your-api-token>" http://heimdall.example.com/api/items
π Advanced Configurations
Customize Heimdall by adding application icons, creating tags, or integrating third-party tools. For example, you can attach health checks to apps by enabling the βApplication Specific Optionsβ in the UI.
Wrapping Up
This guide covered installing, configuring, and managing Heimdall, along with leveraging its core features. By following the code-driven examples, you can create a personalized dashboard tailored to your needs. Heimdallβs flexibility and simplicity make it an essential tool for anyone in the self-hosting community. Start deploying today and streamline your app management!