Author	Nejat Hakan
eMail	nejat.hakan@outlook.de
PayPal Me	https://paypal.me/nejathakan

Personal Dashboard - Heimdall

Welcome to this comprehensive guide on setting up and managing Heimdall, your personal application dashboard. Heimdall is a visually appealing and highly customizable dashboard that provides easy access to all your self-hosted applications, websites, and services from a single, unified interface. This guide is designed for university students and enthusiasts eager to dive deep into self-hosting, offering detailed explanations and practical, hands-on workshops. We will cover everything from basic setup to advanced configurations, empowering you to create a truly personalized and efficient Heimdall instance.

Introduction Why Heimdall

In an increasingly digital world, many of us interact with a multitude of web applications, services, and websites daily. For those involved in self-hosting, the number of local network services (like media servers, network-attached storage, home automation tools, etc.) can quickly become overwhelming to manage and access. Bookmarking everything in a browser is a common solution, but it lacks organization, visual appeal, and often doesn't provide at-a-glance information.

What is Heimdall

Heimdall is an application dashboard designed to be a "homepage" for all your web-based applications and frequently visited sites. It presents your services as tiles on a grid, often with the ability to display live information from "Enhanced Apps" (like download speeds from a torrent client or recently added media from Plex). Its primary goal is to simplify access to your digital life by providing a clean, organized, and visually attractive portal.

Key features of Heimdall include:

Simple and Elegant Interface: Heimdall focuses on a clean, user-friendly design.
Application Organization: Arrange your applications with custom titles, icons, colors, and tags.
Enhanced Applications: Integrates with many popular self-hosted services (e.g., Sonarr, Radarr, Plex, NZBGet) to display relevant information directly on the dashboard.
Generic Links: Add any URL as a simple link.
Tagging System: Organize and filter applications using tags.
Customization: Change backgrounds, add custom CSS, and more.
Lightweight: It's not resource-intensive, making it suitable for running on low-power devices like a Raspberry Pi.
Open Source: Freely available and community-supported.

Why a Personal Dashboard

A personal dashboard like Heimdall serves several important purposes:

Centralized Access:
It acts as a single point of entry for all your important web services, whether they are hosted locally on your network or are external websites you visit frequently. This eliminates the need to remember numerous URLs or sift through disorganized bookmarks.
Improved Organization:
By categorizing and tagging applications, you can create a logical structure that makes sense for your workflow. This is especially useful if you manage many self-hosted services.
Efficiency and Time-Saving:
Quick access to your tools and sites means less time searching and more time doing. For self-hosters, quickly jumping between management interfaces for different services is a common task.
At-a-Glance Information:
With enhanced app integrations, you can get quick status updates without needing to open each application individually. For example, see if your download client is active or check recently added movies to your media server.
Reduced Cognitive Load:
Instead of trying to remember IP addresses, ports, or complex URLs, you have a visual, clickable interface.
Personalization:
You can tailor the dashboard to your specific needs and aesthetic preferences, making it a more enjoyable and personal tool.

Benefits of Self-Hosting Heimdall

Self-hosting Heimdall, as opposed to relying on a cloud-based bookmarking service or browser start page, offers distinct advantages:

Complete Control and Privacy:
Your data (the list of your applications, their URLs, any API keys used for enhanced apps) resides on your own server. You are not dependent on a third-party service that could change its terms, shut down, or suffer a data breach.
Accessibility within Your Network:
Primarily, Heimdall is invaluable for accessing services hosted on your local network, which might not be (and often shouldn't be) exposed to the public internet.
No Subscription Fees:
Heimdall is open-source and free to use.
Deep Customization:
You have full control over its appearance and functionality, including the ability to modify its code if you have the skills.
Learning Opportunity:
Setting up and managing Heimdall is an excellent way to learn about Docker, web servers, networking, and other fundamental self-hosting concepts.
Integration with Local Services:
Heimdall excels at integrating with other self-hosted applications, pulling information directly from them.

Prerequisites General

Before you embark on setting up Heimdall, it's beneficial to have a foundational understanding or setup for the following:

A Host System:
This can be a dedicated server, a virtual machine (VM), a Raspberry Pi, or even your desktop computer (though a dedicated system is better for 24/7 availability). Operating systems like Linux (e.g., Ubuntu Server, Debian) are commonly preferred for self-hosting due to their stability, efficiency, and robust command-line tools.
Basic Linux Command Line Familiarity:
Many self-hosting tasks, including Docker management, involve using the terminal. Understanding commands for navigation (cd), file listing (ls), editing files (e.g., nano, vim), and managing services will be crucial.
Networking Fundamentals:
- IP Addresses: Understand what an IP address is and how to find the IP address of your host system.
- Ports: Know that services listen on specific ports (e.g., HTTP on port 80, HTTPS on port 443) and how port conflicts can arise.
- Local Network: Basic understanding of how devices communicate on your home network.
Docker (Recommended for Heimdall):
- While not strictly mandatory (Heimdall can be installed via other methods), Docker is the most common and highly recommended way to deploy Heimdall. It simplifies installation, updates, and dependency management. We will focus heavily on Docker in this guide.
- If you plan to use Docker, you'll need Docker and preferably Docker Compose installed on your host system.

This guide will walk you through the necessary steps, but having these prerequisites in place or being prepared to learn about them will make the process smoother and more rewarding.

1. Basic Setup and Configuration

This section covers the foundational knowledge and steps required to get your Heimdall instance up and running. We'll explore Heimdall's core components, discuss installation methods with a strong focus on Docker, and guide you through the initial configuration to create your first personalized dashboard.

Understanding Heimdall's Core Concepts

Before diving into the installation, it's essential to grasp the fundamental building blocks and terminology used within Heimdall. This understanding will help you plan and organize your dashboard effectively.

Applications (or Tiles): These are the primary elements on your Heimdall dashboard. Each application tile represents a link to a web service or website.
- Generic Applications: These are simple links. You provide a name, URL, an icon (optional), and a background color. Clicking the tile opens the URL in a new tab.
- Enhanced Applications: These are special integrations for specific, popular self-hosted services like Plex, Sonarr, Radarr, Deluge, SABnzbd, etc. Besides being a link, these tiles can display live information fetched from the application's API (e.g., current download speed, number of movies, server status). This requires providing API keys and connection details for the respective service.
Tags: Tags are labels you can assign to your applications to categorize and organize them. For instance, you might have tags like "Media," "Downloads," "Network," "Utilities," or "Work." Heimdall allows you to filter the displayed applications based on these tags, making it easier to find what you're looking for if you have many items.
Pinned Items: Heimdall allows you to "pin" applications to the top of your dashboard. Pinned items are always visible, regardless of any tag filtering, making them ideal for your most frequently accessed services.
Backgrounds: You can customize the background of your Heimdall dashboard. This can be a solid color, a pre-loaded image, or a custom image URL. This helps in personalizing the look and feel of your dashboard.
Search Bar: Heimdall includes a search bar that can be configured to search using various search engines (Google, DuckDuckGo, Bing, etc.) or even to search within specific sites like YouTube or GitHub. This adds another layer of utility to your dashboard.
Settings: The settings area (usually accessed via a cog icon or similar) is where you configure Heimdall's behavior, add/edit applications, manage tags, change the background, and set up enhanced application integrations.

Understanding these concepts will allow you to envision how you want your dashboard to be structured. Think about the services you use, how you might group them, and which ones are most important to you.

Workshop Sketching Your Ideal Dashboard Layout

This workshop is a planning exercise. Before you install anything, taking a few minutes to sketch out your ideal dashboard can save time and lead to a more organized result.

Objective: To plan the initial structure of your Heimdall dashboard, including applications, potential tags, and pinned items.

Materials:

A piece of paper and a pen/pencil, or a digital drawing/note-taking tool.

Steps:

List Your Applications/Services:
- Start by listing all the web applications, services, and websites you access regularly.
- Consider Local Services: Think about your self-hosted services (e.g., Pi-hole, Home Assistant, your router's admin page, NAS interface, media servers like Jellyfin or Plex, download clients like qBittorrent or SABnzbd).
- Consider External Websites: Include frequently visited external sites (e.g., university portal, news sites, documentation pages, cloud services).
- Example List:
  - Plex (local)
  - Sonarr (local)
  - Radarr (local)
  - qBittorrent (local)
  - Router Admin (local)
  - Pi-hole (local)
  - University Email (external)
  - GitHub (external)
  - Local Weather Site (external)
Identify Potential "Enhanced Apps":
- From your list, identify which services Heimdall might support as "Enhanced Applications." Common ones include Plex, Sonarr, Radarr, Lidarr, SABnzbd, NZBGet, Deluge, qBittorrent, Transmission, Portainer, Pi-hole.
- Example (from above): Plex, Sonarr, Radarr, qBittorrent, Pi-hole.
Think About Categories (Tags):
- How would you naturally group these applications? These will become your tags.
- Example Categories/Tags:
  - Media (Plex, Sonarr, Radarr)
  - Downloads (qBittorrent)
  - Network (Router Admin, Pi-hole)
  - Education (University Email)
  - Development (GitHub)
  - Information (Local Weather Site)
Decide on Pinned Items:
- Which 2-5 applications do you use most frequently or consider most critical? These are good candidates for pinned items.
- Example Pinned Items: Plex, qBittorrent, Router Admin.

Sketch Your Dashboard:

Draw a simple grid representing your Heimdall dashboard.
Place your pinned items at the top.
Arrange other application tiles below, perhaps grouped by your intended tags.
Don't worry about exact icons or colors yet; focus on placement and organization.
You can indicate which ones might be enhanced apps.

Example Sketch (Text Representation):

-----------------------------------------------------
| [PINNED] Plex (E) | [PINNED] qBittorrent (E) | [PINNED] Router Admin |
-----------------------------------------------------
| -- TAGS: [All] [Media] [Downloads] [Network] --  |
-----------------------------------------------------
| Sonarr (E)        | Radarr (E)         | Pi-hole (E)       |
| (Tag: Media)      | (Tag: Media)       | (Tag: Network)    |
-----------------------------------------------------
| University Email  | GitHub             | Local Weather     |
| (Tag: Education)  | (Tag: Development) | (Tag: Info)       |
-----------------------------------------------------

(E) indicates an enhanced app.

Review and Refine:
- Look at your sketch. Does it feel logical? Is it too cluttered or too sparse?
- Adjust as needed. This is an iterative process.

Outcome:
You now have a visual plan for your Heimdall dashboard. This will guide you during the actual setup and configuration process, making it more efficient. Keep this sketch handy as you proceed through the next sections.

Installation Methods Overview

Heimdall can be installed in several ways, each with its own set of advantages, disadvantages, and technical requirements. Understanding these options will help you choose the method best suited to your skills, environment, and long-term goals.

Docker (Highly Recommended):
- What it is: Docker is a containerization platform that packages an application and its dependencies into a standardized unit called a container. This container can run on any system that has Docker installed, regardless of the underlying operating system or specific libraries.
- Pros:
  - Isolation: Heimdall runs in its own isolated environment, preventing conflicts with other applications or system libraries on your host.
  - Simplicity: Installation is often a one-liner command to pull and run the image.
  - Reproducibility: The same Docker image will behave identically across different systems.
  - Easy Updates: Updating Heimdall is usually as simple as pulling the new image and restarting the container.
  - Dependency Management: All dependencies are bundled within the image, so you don't need to install them manually on your host system.
  - Community Support: Most Heimdall users and guides focus on Docker, particularly images from LinuxServer.io.
- Cons:
  - Learning Curve: If you're new to Docker, there's an initial learning curve to understand concepts like images, containers, volumes, and ports.
  - Resource Overhead: While generally lightweight, Docker itself consumes some system resources.
- Common Implementations:
  - docker run command: Directly running a container using the Docker CLI.
  - Docker Compose: Using a docker-compose.yml file to define and manage the Heimdall service, which is highly recommended for easier management of configuration parameters like ports, volumes, and environment variables.
Bare Metal (Manual Installation):
- What it is: This involves installing Heimdall directly onto your host operating system, typically by cloning its source code from GitHub and manually setting up a web server (like Nginx or Apache) and PHP environment to serve the application.
- Pros:
  - No Docker Overhead: If you are resource-constrained and cannot afford Docker's overhead, this might seem appealing.
  - Direct System Integration: Potentially finer-grained control over the web server and PHP configuration if you are an expert in these areas.
- Cons:
  - Complexity: Significantly more complex to set up and configure correctly. You need to install and configure PHP, a web server, required PHP extensions, and manage file permissions manually.
  - Dependency Hell: Managing PHP versions and extensions can be problematic and may conflict with other applications on your system.
  - Difficult Updates: Updating usually involves pulling new code, running composer updates, and potentially reconfiguring your web server or PHP settings. This is much more error-prone.
  - Security Risks: Incorrect configuration of the web server or PHP can lead to security vulnerabilities.
  - Less Portable: Your setup is tied to the specific configuration of your host OS.
- When to consider: Only if you have a very specific reason not to use Docker and possess strong expertise in web server administration and PHP application deployment. For most users, especially those learning, this method introduces unnecessary complexity and potential for errors.
Other Pre-packaged Systems (e.g., DietPi, Cloudron, Unraid Community Apps):
- What it is: Some operating systems or platforms designed for self-hosting (like DietPi for Raspberry Pi, or app platforms like Cloudron or Unraid) offer Heimdall as an easy-to-install package through their own software management systems.
- Pros:
  - Simplicity: Often a one-click or simple command install managed by the platform.
  - Integration: May be pre-configured to work well within that specific platform's ecosystem.
- Cons:
  - Platform Lock-in: You are dependent on that platform's update schedule and configuration options for Heimdall.
  - Less Control: You might have less direct control over the underlying Docker image or configuration than if you managed it yourself with Docker Compose.
  - Abstraction: While easier, it might abstract away some of the learning opportunities related to Docker or manual setup.

Our Recommendation:
For this guide, and for the vast majority of users, Docker (specifically using Docker Compose) is the recommended installation method. It strikes the best balance between ease of use, control, maintainability, and community support. The rest of this guide will primarily focus on Docker-based installation.

Workshop Decision Matrix Choosing Your Heimdall Installation Path

This workshop helps you critically evaluate which installation method is most appropriate for your specific situation, skills, and goals, even though we heavily advocate for Docker.

Objective:
To make an informed decision about how you will install Heimdall by weighing the pros and cons of each method against your personal context.

Materials:

A way to create a simple table (pen and paper, spreadsheet, text document).

Steps:

Create a Decision Matrix Table:
Set up a table with the following columns:
- Installation Method
- Key Pros
- Key Cons
- My Skill Level/Comfort (Rate 1-5, 1=Very Low, 5=Very High)
- My Environment Suitability (e.g., resource constraints, OS)
- Long-term Maintainability Effort (Low, Medium, High)
- Chosen? (Yes/No/Maybe)
Populate for Docker:
- Installation Method: Docker / Docker Compose
- Key Pros: Isolation, easy updates, dependency management, reproducibility, large community.
- Key Cons: Docker learning curve (if new), slight resource overhead of Docker itself.
- My Skill Level/Comfort:
  - Assess your current Docker knowledge. If low, are you willing to learn? (This guide will help).
- My Environment Suitability:
  - Do you have Docker installed? Is your OS compatible? Are system resources (RAM, CPU) sufficient for Docker plus Heimdall (Heimdall itself is light)?
- Long-term Maintainability Effort: Low to Medium (mostly involves updating images).
- Chosen?
Populate for Bare Metal:
- Installation Method: Bare Metal (Manual)
- Key Pros: No Docker overhead, potentially fine-grained control (if expert).
- Key Cons: Complex setup, dependency hell, difficult updates, higher security risk if misconfigured, less portable.
- My Skill Level/Comfort:
  - Assess your expertise with web server (Nginx/Apache) admin, PHP configuration, and Linux system administration. This needs to be high.
- My Environment Suitability:
  - Are you comfortable managing these components directly on your OS? Do you have specific reasons to avoid Docker?
- Long-term Maintainability Effort: High (manual updates, dependency checks, security patching).
- Chosen?
Populate for Pre-packaged Systems (if applicable):
- Installation Method: (e.g., DietPi, Unraid App, Cloudron)
- Key Pros: Extreme simplicity (often), integration with the platform.
- Key Cons: Platform lock-in, less control, abstraction.
- My Skill Level/Comfort:
  - Are you already using one of these platforms? How comfortable are you with its way of managing applications?
- My Environment Suitability:
  - This is only relevant if your host system is one of these platforms.
- Long-term Maintainability Effort: Low (managed by the platform).
- Chosen?
Analyze and Decide:
- Review your completed matrix.
- For most university students looking to learn self-hosting, Docker/Docker Compose will likely emerge as the strongest candidate due to the valuable skills learned and its widespread applicability in the self-hosting world.
- If you opted for a pre-packaged system on a platform you already use, that's a valid choice for simplicity, but be aware that the rest of this guide will assume a Docker-based approach for specific commands. You'll need to adapt instructions to your platform's management interface.
- If you chose Bare Metal, be prepared for a more challenging path. You may need to consult additional resources specific to manual Heimdall installation.

Outcome:
You have now formally considered your installation options and made a reasoned choice. If you've chosen Docker, you're well-prepared for the next, more detailed sections. If not, you understand why and what alternatives you might need to explore.

Docker Installation Deep Dive

This section provides a comprehensive guide to installing Heimdall using Docker. We will primarily focus on using docker-compose as it offers a more manageable and reproducible way to define your Heimdall service. We'll cover prerequisites, obtaining the Heimdall image, configuring persistent storage, and accessing your new dashboard.

Prerequisites for Docker Installation:

Before you can install Heimdall with Docker, you need Docker and Docker Compose installed on your host system.

Docker Engine:
- What it is: Docker Engine is the core runtime that builds and runs Docker containers.
- Installation: The installation process varies by operating system.
  - Linux (Recommended Host OS): Most Linux distributions have Docker in their official repositories, but it's often recommended to install it from Docker's official repository for the latest version.
    - For Ubuntu: sudo apt update && sudo apt install docker.io (from Ubuntu repos) or follow the official Docker guide for installing from Docker's APT repository.
    - For Debian, Fedora, CentOS: Refer to the official Docker installation documentation for your specific distribution: https://docs.docker.com/engine/install/
  - Windows/macOS: Docker Desktop is the easiest way to get Docker Engine and Docker CLI tools. Download it from the Docker website. Note that Docker Desktop on Windows uses WSL2 (Windows Subsystem for Linux 2) or Hyper-V, and on macOS uses a lightweight Linux VM.
- Post-installation (Linux):
  - Add your user to the docker group to run Docker commands without sudo:
```
sudo usermod -aG docker ${USER}
```
    You'll need to log out and log back in (or run newgrp docker in your current shell) for this change to take effect.
  - Enable Docker to start on boot:
```
sudo systemctl enable docker
sudo systemctl start docker
```
- Verify Installation:
```
docker --version
```
  This should output the installed Docker version.
Docker Compose:
- What it is: Docker Compose is a tool for defining and running multi-container Docker applications. It uses a YAML file (docker-compose.yml) to configure application services, networks, and volumes. Even for a single-service application like Heimdall, Compose simplifies configuration management.
- Installation:
  - If you installed Docker Desktop (Windows/macOS): Docker Compose is typically included.
  - Linux: Docker Compose is often a separate installation. The recommended method is to download the latest stable release binary from the Docker Compose GitHub repository.
```
# Check the latest release version on: https://github.com/docker/compose/releases
LATEST_COMPOSE_VERSION="v2.24.6" # Example, replace with actual latest
sudo curl -L "https://github.com/docker/compose/releases/download/${LATEST_COMPOSE_VERSION}/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
sudo chmod +x /usr/local/bin/docker-compose
```
    Alternatively, on some Linux systems, it might be available as a plugin with Docker: sudo apt install docker-compose-plugin. If so, you'd use docker compose (with a space) instead of docker-compose (with a hyphen). This guide will primarily use docker-compose (hyphenated), but be aware docker compose (space) is the newer V2 syntax.
- Verify Installation:
```
docker-compose --version
# or for V2 plugin:
# docker compose version
```
  This should output the installed Docker Compose version.

Obtaining the Heimdall Docker Image:

Heimdall images are available on Docker Hub. The most popular and well-maintained image is provided by the LinuxServer.io team.

Image Name: linuxserver/heimdall
Pulling the image (optional, docker-compose up will do this automatically if needed): You can manually pull the image to ensure you have the latest version before running it:
```
docker pull linuxserver/heimdall:latest
```
- docker pull: The command to download an image from a registry.
- linuxserver/heimdall: The name of the repository for the image. linuxserver is the organization/user, and heimdall is the image name.
- :latest: This is a tag, usually pointing to the most recent stable version of the image. You can also specify version tags (e.g., :2.5.6) if you need a particular version.

Understanding Key Configuration Parameters for linuxserver/heimdall:

The LinuxServer.io images use a standard set of environment variables for configuration:

-e PUID=<UID>: Process User ID. This sets the user ID under which the Heimdall process runs inside the container. It's crucial for managing file permissions correctly, especially when using bind mounts for persistent storage. To find your current user's UID on Linux, type id -u.
-e PGID=<GID>: Process Group ID. Similar to PUID, this sets the group ID. To find your current user's GID on Linux, type id -g.
- Why PUID/PGID are important: When Heimdall (running inside the container) writes configuration files to a volume mounted from your host system, it needs to have the correct permissions. By setting PUID/PGID to match your host user, you ensure that you can easily access and manage these files on the host if needed, and the container process has the necessary write permissions.
-e TZ=<Timezone>: Timezone. Sets the timezone for the container, e.g., Europe/London, America/New_York. A list of valid timezones can usually be found by looking for "tz database time zones". This ensures that any time-sensitive operations or logs within the container use the correct local time.
-p <host_port>:<container_port>: Port Mapping. This maps a port on your host machine to a port inside the container where the Heimdall application is listening.
- Heimdall listens on port 80 (HTTP) and 443 (HTTPS) inside the container.
- You'll map a port on your host (e.g., 8080) to port 80 in the container for HTTP access: -p 8080:80.
- And/or map a port on your host (e.g., 8443) to port 443 in the container for HTTPS access: -p 8443:443.
-v <path_on_host_or_volume_name>:/config: Volume Mapping for Persistent Storage. This is the most critical part for ensuring your Heimdall configuration (added applications, settings, etc.) persists across container restarts or recreations.
- /config: This is the directory inside the Heimdall container where all its configuration data, SQLite database, custom CSS, and uploaded backgrounds are stored.
- Bind Mount: -v /path/on/your/host/heimdall/config:/config
  - You create a directory on your host system (e.g., /srv/heimdall/config or ~/docker/heimdall/config).
  - Docker maps this host directory to /config inside the container.
  - Files are directly accessible and editable on your host.
  - Ensure the host directory exists and has correct permissions for the PUID/PGID you'll use.
- Named Volume: -v heimdall_config:/config
  - Docker manages the volume. The actual data is stored in a Docker-controlled location on your host (usually under /var/lib/docker/volumes/).
  - Easier to manage with Docker commands (docker volume ls, docker volume inspect).
  - Generally preferred for portability and letting Docker handle storage.
--restart unless-stopped (or always): Restart Policy. Defines what Docker should do if the container stops.
- unless-stopped: Restarts the container unless it was manually stopped.
- always: Always restarts the container if it stops, even if manually stopped (unless the Docker daemon itself is stopped/restarted).
- This is good for ensuring Heimdall comes back online after a server reboot or unexpected crash.

Using docker-compose.yml (Recommended):

A docker-compose.yml file allows you to define all these parameters in a structured YAML format, making it much easier to manage, version control, and share your configuration.

Create a Project Directory:
It's good practice to create a dedicated directory for your Heimdall configuration.
```
mkdir -p ~/docker/heimdall
cd ~/docker/heimdall
```
The -p flag for mkdir creates parent directories if they don't exist.

Create docker-compose.yml:
Inside the ~/docker/heimdall directory, create a file named docker-compose.yml using a text editor like nano or vim:

nano docker-compose.yml

Paste the following content into the file. Read the comments and adjust values as needed.

---
version: "3.8" # Specifies the Docker Compose file format version

services:
  heimdall:
    image: linuxserver/heimdall:latest # Specifies the Docker image to use
    container_name: heimdall # A friendly name for your container
    environment:
      - PUID=1000 # Replace with your user's UID (find with `id -u`)
      - PGID=1000 # Replace with your user's GID (find with `id -g`)
      - TZ=Etc/UTC # Replace with your timezone, e.g., America/New_York or Europe/London
    volumes:
      # Option 1: Named Volume (Recommended for most users)
      - heimdall_config:/config
      # Option 2: Bind Mount (Uncomment and adjust path if you prefer)
      # - /path/on/your/host/heimdall/config:/config # e.g., ./config:/config or /srv/heimdall/config:/config
    ports:
      - "8080:80"  # Map host port 8080 to container port 80 (HTTP)
      - "8443:443" # Map host port 8443 to container port 443 (HTTPS)
    restart: unless-stopped # Restart policy

volumes:
  heimdall_config: # Defines the named volume 'heimdall_config'
    # If you chose Option 1 for volumes above, this section is necessary.
    # If you chose Option 2 (bind mount), you can remove this 'volumes:' block at the end.
    name: heimdall_appdata # You can optionally give the Docker volume a specific name on the host

Explanation of the docker-compose.yml:
- version: "3.8": Defines the version of the Compose file format. Version 3.x is common.
- services:: This block defines the different application services that make up your application stack. In this case, we only have one service: heimdall.
- heimdall:: This is the name you give to your Heimdall service within Docker Compose.
  - image: linuxserver/heimdall:latest: Tells Docker Compose to use the latest linuxserver/heimdall image from Docker Hub.
  - container_name: heimdall: Assigns a specific, predictable name to the container created by this service. This makes it easier to identify and manage with docker ps or docker logs heimdall.
  - environment:: A list of environment variables to pass to the container.
    - PUID, PGID: Set these to your host user's ID and group ID. Find them by running id -u and id -g in your terminal. If your UID/GID is 1000, the defaults are fine.
    - TZ: Set to your correct timezone from the tz database (e.g., America/Los_Angeles, Europe/Berlin).
  - volumes: (under services:heimdall:): Defines how data persistence is handled.
    - - heimdall_config:/config: This maps a Docker named volume called heimdall_config to the /config directory inside the container. This is where Heimdall stores all its data. The named volume is managed by Docker.
    - # - /path/on/your/host/heimdall/config:/config: This is the alternative bind mount syntax, commented out. If you use this, replace /path/on/your/host/heimdall/config with an actual path on your host system, for example ~/docker/heimdall/config:/config (if you want the config folder to be in the same directory as your docker-compose.yml, you can use ./config:/config). If you use a bind mount, ensure the directory exists on your host and has appropriate permissions for the PUID/PGID.
  - ports:: Maps ports from the host machine to ports inside the container.
    - "8080:80": Maps port 8080 on your host to port 80 (HTTP) inside the Heimdall container. You will access Heimdall via http://<your-host-ip>:8080.
    - "8443:443": Maps port 8443 on your host to port 443 (HTTPS) inside the Heimdall container.
    - You can change the host ports (the numbers before the colon) if 8080 or 8443 are already in use on your system. For example, "8081:80".
  - restart: unless-stopped: Ensures the container restarts automatically if it crashes or if the Docker daemon restarts (e.g., after a server reboot), unless you've explicitly stopped it.
- volumes: (at the root level of the YAML, indented same as services:): This block is used to define named volumes.
  - heimdall_config:: Declares the named volume heimdall_config that was referenced in the service definition.
  - name: heimdall_appdata: This is an optional Docker Swarm extension that also works with docker-compose. It allows you to give the underlying Docker volume a specific name that you might see with docker volume ls. If omitted, Docker Compose will typically prefix the volume name with the project directory name (e.g., heimdall_heimdall_config).
Save and Close the File:
- If using nano, press Ctrl+X, then Y to confirm, then Enter to save.
Start Heimdall:
Navigate to the directory containing your docker-compose.yml file (~/docker/heimdall in our example) and run:
```
docker-compose up -d
```
- docker-compose up: This command reads the docker-compose.yml file, creates/updates the services, networks, and volumes defined, and starts the containers.
- -d: (detached mode) Runs the containers in the background and prints the new container names. Without -d, logs would be streamed to your terminal, and closing the terminal would stop the containers.
Verify Container is Running:
You can check the status of your container:
```
docker ps
```
You should see an entry for heimdall, indicating it's up and running, along with its port mappings. To view logs (useful for troubleshooting):
```
docker logs heimdall
# Or, if you want to follow the logs in real-time:
# docker logs -f heimdall
```

Accessing Heimdall:

Once the container is running, you can access Heimdall through your web browser:

Open your browser and navigate to: http://<your-host-ip>:<host_port_for_http>
- Replace <your-host-ip> with the IP address of the machine where Docker is running (e.g., 192.168.1.100). You can find this on Linux with ip a or hostname -I.
- Replace <host_port_for_http> with the host port you mapped to container port 80 (e.g., 8080 from our docker-compose.yml).
- So, the URL would typically be: http://192.168.1.100:8080 (adjust IP and port as per your setup).

You should be greeted by the Heimdall default interface.

Managing Heimdall with Docker Compose:

To stop Heimdall: In the directory with docker-compose.yml:
```
docker-compose down
```
This stops and removes the containers defined in the Compose file. Your data in the named volume (heimdall_config) or bind mount will persist.
To restart Heimdall:
```
docker-compose restart heimdall
```
To update Heimdall:
1. Pull the latest image:
```
docker-compose pull heimdall
# Or, more generically:
# docker-compose pull
```
2. Recreate the container with the new image:
```
docker-compose up -d --remove-orphans
```
  Docker Compose will detect the new image and recreate the heimdall container. Your /config volume will be reattached, preserving your settings. --remove-orphans cleans up any containers for services that might have been removed from the docker-compose.yml file.

Workshop Your First Heimdall Container

This workshop will guide you step-by-step through creating the docker-compose.yml file, launching your Heimdall container, and verifying its operation.

Objective:
To successfully deploy Heimdall using Docker Compose and access its web interface.

Prerequisites:

Docker and Docker Compose installed and operational (as per the "Prerequisites for Docker Installation" subsection).
Access to a terminal on your host machine.
Knowledge of your host machine's IP address.
Your user's UID and GID (use id -u and id -g to find these).

Steps:

Determine Your UID and GID:
Open a terminal on your host machine and run:
```
id -u
id -g
```
Note down these numbers. For many default users on Linux systems (like the first user created on Ubuntu), these will both be 1000.
Determine Your Host IP Address:
In the terminal, run one of the following commands to find your host's local IP address:
```
hostname -I  # Often shows the primary IP first
# or
ip a         # Look for your main network interface (e.g., eth0, enpXsY) and its inet address
```
Note down this IP address (e.g., 192.168.1.55).
Determine Your Timezone:
You need your timezone in the "tz database" format (e.g., America/New_York, Europe/Paris, Asia/Tokyo). If unsure, you can often find it by:
```
cat /etc/timezone
# or
timedatectl | grep "Time zone"
```
Or search online for "tz database time zones list".
Create the Project Directory:
If you haven't already, create a directory to store your Heimdall Docker Compose configuration:
```
mkdir -p ~/docker/heimdall
cd ~/docker/heimdall
```
- mkdir -p ...: Creates the directory heimdall inside a directory docker in your home directory. If docker doesn't exist, -p creates it too.
- cd ...: Changes your current directory to ~/docker/heimdall.

Create the docker-compose.yml File:
Use a text editor (e.g., nano) to create the docker-compose.yml file:

nano docker-compose.yml

Copy and paste the following template into the editor. Then, carefully replace the placeholder values (<YOUR_UID>, <YOUR_GID>, <YOUR_TIMEZONE>, <YOUR_HTTP_PORT>, <YOUR_HTTPS_PORT>) with your actual values determined in steps 1-3 and your desired ports.

---
version: "3.8"

services:
  heimdall:
    image: linuxserver/heimdall:latest
    container_name: heimdall
    environment:
      - PUID=<YOUR_UID>      # Example: 1000
      - PGID=<YOUR_GID>      # Example: 1000
      - TZ=<YOUR_TIMEZONE>   # Example: Europe/Berlin or America/Chicago
    volumes:
      - heimdall_config:/config
    ports:
      - "<YOUR_HTTP_PORT>:80"   # Example: "8080:80"
      - "<YOUR_HTTPS_PORT>:443" # Example: "8443:443"
    restart: unless-stopped

volumes:
  heimdall_config:
    name: heimdall_data # Optional: gives a specific name to the Docker volume

Example filled values:
- PUID=1000
- PGID=1000
- TZ=America/New_York
- ports:
  - "8080:80" (You'll access Heimdall on port 8080 of your host)
  - "8443:443" (You'll access Heimdall HTTPS on port 8443 of your host)

Save the file and exit the editor (for nano: Ctrl+X, then Y, then Enter).

Launch the Heimdall Container:
Ensure you are still in the ~/docker/heimdall directory (where your docker-compose.yml file is located). Run the command:
```
docker-compose up -d
```
- You will see Docker pull the linuxserver/heimdall image (if it's not already local), then create and start the container.
- Expected output (will vary slightly):
```
[+] Pulling heimdall          Pulled
[+] Creating network "heimdall_default" Created
[+] Creating volume "heimdall_data"   Created
[+] Running heimdall          Started
```
  If you used a different volume name or didn't specify one, the volume name in the output might be heimdall_heimdall_config or similar.

Verify the Container is Running:
Check the status of your running Docker containers:

docker ps

Expected output (column content and order may vary):

CONTAINER ID   IMAGE                           COMMAND                  CREATED          STATUS          PORTS                                                              NAMES
xxxxxxxxxxxx   linuxserver/heimdall:latest   "/init"                  About a minute ago   Up About a minute   0.0.0.0:<YOUR_HTTPS_PORT>->443/tcp, 0.0.0.0:<YOUR_HTTP_PORT>->80/tcp   heimdall

Confirm that the STATUS is "Up" and the PORTS column shows your chosen host ports mapped correctly.

Access Heimdall in Your Browser:
Open a web browser on a device connected to the same network as your host machine. Navigate to http://<YOUR_HOST_IP>:<YOUR_HTTP_PORT>.
- For example, if your host IP is 192.168.1.55 and you used port 8080, go to http://192.168.1.55:8080.
You should see the default Heimdall dashboard page, likely empty or with a few placeholder/sample items.
Troubleshooting (If it doesn't work):
- "Cannot connect" or "Site can't be reached":
  - Double-check the IP address and port number.
  - Ensure your host firewall is not blocking the port you chose (e.g., sudo ufw status on Ubuntu; you might need sudo ufw allow <YOUR_HTTP_PORT>/tcp).
  - Check Heimdall logs: docker logs heimdall. Look for any error messages.
- Container not starting (check docker ps, it might be restarting or exited):
  - Check logs: docker logs heimdall. Common issues are incorrect PUID/PGID (if using bind mounts and permissions are wrong), or port conflicts if the host port is already in use by another service.
  - If you made a typo in docker-compose.yml, docker-compose up -d might show an error. Correct the YAML file (indentation is very important in YAML).

Outcome:
Congratulations! You have successfully deployed Heimdall using Docker Compose. Your personal dashboard is now running and accessible on your network. In the next section, we'll start configuring it.

Initial Configuration

With Heimdall running, it's time to perform the initial configuration to make it your own. This involves accessing the web interface, adding your first application links, understanding the difference between generic and enhanced applications, organizing with tags, and personalizing the appearance.

Accessing the Heimdall Settings:

Navigate to your Heimdall instance in your web browser (e.g., http://<your-host-ip>:<your-port>).
On the default Heimdall page, you should see a list of "Pinned Items" (which might be empty or have examples initially) and "Application List" (often empty).
Locate the Settings / Add an app area. This is typically:
- A prominent "Add an app" button or link.
- A cogwheel icon (⚙️) or a plus icon (+), usually in one of the corners or on a sidebar, which opens up the main settings and application management interface.
- On more recent Heimdall versions, it's often a large "+" button in the bottom right corner, or a "Settings" link in the top menu.
Clicking this will usually take you to a page or modal where you can add new applications and configure general Heimdall settings.

Adding Your First Application Link (Generic Application):

Let's start by adding a simple link to a website, like your university's main page or a search engine.

In the Heimdall settings/application management area, look for an option like "Add" or "Create Application".
You will typically be presented with a choice of application types. For a simple link, choose "Generic" or "Application" (the exact naming might vary slightly between Heimdall versions).
You'll see a form with several fields:
- Application Name: Enter a descriptive name for the link (e.g., "My University Portal," "DuckDuckGo"). This is what will appear on the tile.
- URL: Enter the full URL of the website, including http:// or https:// (e.g., https://www.myuni.edu, https://duckduckgo.com).
- Icon: Heimdall often tries to fetch a favicon automatically. You can also:
  - Upload a custom icon image.
  - Use Font Awesome icons (e.g., fas fa-university, fab fa-searchengin). You might need to look up Font Awesome class names. Many Heimdall versions have a built-in Font Awesome picker.
- Colour: Choose a background color for the tile.
- Application Type: This should already be "Generic" or similar if you selected it earlier.
- Tags: (We'll cover this next). For now, you can leave it blank or create a simple tag like "General."
- Display: You might see options for how it opens (new tab, same tab). "New Tab" is usually default and recommended.
- Pinned: Check this box if you want this application to appear in the "Pinned Items" section at the top of your dashboard.
Click "Save" or "Add".
Go back to your main Heimdall dashboard page (you might need to refresh or click a "Dashboard" link). You should now see your newly added application tile. Click it to test if it opens the correct URL.

Understanding Application Types: Generic vs. Enhanced:

Generic Applications:
- As created above, these are straightforward bookmarks. They link to a URL.
- They are highly versatile and can be used for any website or web service that doesn't have specific Heimdall integration.
- Configuration is minimal: Name, URL, Icon, Color.
Enhanced Applications:
- These are special integrations built into Heimdall for popular self-hosted services (e.g., Plex, Sonarr, Radarr, qBittorrent, Pi-hole, Portainer).
- In addition to being a link, these tiles can display live information fetched from the application's API.
  - Example: A Sonarr tile might show the number of missing episodes. A qBittorrent tile might show current download/upload speeds. A Pi-hole tile might show the number of queries blocked.
- Configuration Requirements: To enable the "enhanced" features, you typically need to provide:
  - The application's URL (e.g., http://192.168.1.56:8989 for Sonarr).
  - An API Key for that application. You'll need to go into the settings of the specific application (Sonarr, Radarr, etc.) to find or generate its API key.
  - Sometimes, other specific details like username/password (less common for API-based integrations but possible for some apps).
- When adding an application in Heimdall, if you type a name like "Sonarr" or "Plex," Heimdall often automatically suggests the "Enhanced" version and shows the extra fields required for API integration.

Adding Tags:

Tags help you organize and filter your applications. This is especially useful as your dashboard grows.

Creating Tags:
- During App Addition/Editing: When you add or edit an application, there's usually a "Tags" field. You can type a new tag name (e.g., "Media," "Utilities," "Work") and often hit Enter or a comma to create it. If the tag already exists, it will likely autocomplete. An application can have multiple tags.
- Dedicated Tag Management: Some Heimdall versions might have a separate section in Settings to manage tags (create, rename, delete).
Using Tags:
- Once applications are tagged, you'll see your tags listed on the main dashboard, usually above the application list.
- Clicking on a tag name will filter the dashboard to show only applications that have that tag.
- There's usually an "All" or "Show All" option to clear the filter.

Customizing the Background:

Personalizing the background can make your dashboard more visually appealing.

Go to the main Settings area of Heimdall.
Look for a section related to "Appearance," "Background," or "Customization."
You typically have several options:
- Default Backgrounds: Heimdall might come with a selection of pre-loaded images or color schemes.
- Solid Color: Choose a specific hex color code or use a color picker.
- Custom Image URL: Provide a URL to an image hosted online. This image will be fetched and set as the background.
- Upload Image: Some versions allow you to upload an image directly from your computer. This image is then stored in Heimdall's /config volume.
Select your desired background option and save the changes.
View your dashboard to see the new background.

Other Initial Settings to Explore:

Search Provider: In Settings, you can often configure the default search engine used by the search bar on the dashboard (e.g., Google, DuckDuckGo, Bing). You can also set custom search URLs.
Dashboard Title: Some versions might allow you to set a custom title for your dashboard that appears in the browser tab or on the page itself.

Take some time to explore all the options available in Heimdall's settings menu. The interface is generally intuitive.

Workshop Building Your Initial Application Grid

This workshop will guide you through adding a mix of generic and (if you have them) enhanced applications to your Heimdall dashboard, organizing them with tags, and pinning your most important ones, based on the sketch you made earlier.

Objective: To populate your Heimdall dashboard with at least 3-5 applications, including one pinned item and one item with a tag, and to set a custom background.

Prerequisites:

Heimdall installed and accessible via your web browser.
Your "Sketching Your Ideal Dashboard Layout" plan from the previous workshop.
If you plan to add an "Enhanced Application," you'll need:
- The URL of that application (e.g., http://<sonarr-ip>:<sonarr-port>).
- The API key for that application (e.g., from Sonarr's Settings -> General -> Security section).

Steps:

Access Heimdall and Open Settings:
- Navigate to your Heimdall URL.
- Click the "Add an app" button or the settings icon (e.g., "+", "⚙️") to enter the application management area.
Add a Generic Application (e.g., a Search Engine):
- Click "Add" or "Create Application."
- Select "Generic" or "Application" type.
- Application Name: DuckDuckGo (or your preferred search engine)
- URL: https://duckduckgo.com
- Icon: Type fab fa-duckduckgo (if Font Awesome is supported and that's the icon for DuckDuckGo) or let it fetch the favicon. If you can't find a specific icon easily, you can use a generic one like fas fa-search.
- Colour: Pick a color you like.
- Tags: Type Search and press Enter (or click "Add Tag").
- Pinned: Leave this unchecked for now (unless it's truly a top item for you).
- Click Save.
Add a Pinned Generic Application (e.g., Your Router):
- Click "Add" again.
- Select "Generic" type.
- Application Name: Router Admin
- URL: http://<your-router-ip> (e.g., http://192.168.1.1)
- Icon: Try fas fa-network-wired or fas fa-cogs.
- Colour: Choose a distinct color.
- Tags: Type Network and add it.
- Pinned: Check this box.
- Click Save.
Add an Enhanced Application (Example: Sonarr - adapt if using another):
- (If you don't have Sonarr or a similar API-enabled app, you can add another generic app instead and skip the API key part, or plan to come back to this when you do.)
- Click "Add" again.
- In the "Application Type" dropdown or selection list, look for Sonarr. If you type "Sonarr" as the name, it might auto-select.
- If Sonarr is an option, selecting it should reveal extra fields for API configuration.
- Application Name: Sonarr
- URL (for Sonarr): http://<your-sonarr-ip>:<sonarr-port> (e.g., http://192.168.1.10:8989)
- API Key: Paste the API key you obtained from Sonarr's settings (Settings > General > Security > API Key).
- Icon: It will likely use a Sonarr-specific icon by default.
- Colour: Choose a color.
- Tags: Type Media and add it. Also, add Downloads.
- Pinned: Uncheck (unless you want Sonarr pinned).
- Click Save.
  - Verification: After saving, Heimdall might try to connect to Sonarr using the API key. If successful, the tile on your dashboard might show information like "X series, Y missing." If it fails, double-check the URL and API key in Heimdall's settings for this app. Ensure Heimdall (running in its Docker container) can reach the Sonarr URL.
Review Your Dashboard:
- Go back to your main Heimdall dashboard view.
- You should see your "Router Admin" app in the "Pinned Items" section.
- You should see "DuckDuckGo" and "Sonarr" (or your alternatives) in the "Application List."
- You should see tags like "Search," "Network," "Media," "Downloads" available for filtering. Click them to test.
Customize the Background:
- Go back into Heimdall's main Settings (not just app adding).
- Find the Appearance or Background section.
- Option 1: Simple Color: Choose a background color from a palette or enter a hex code (e.g., #2c3e50).
- Option 2: Image URL: Find a nice, large background image online (e.g., from Unsplash, Pexels, or a wallpaper site). Copy its direct image URL (usually ending in .jpg or .png). Paste this URL into the "Background image URL" field.
- Click Save or Apply.
- View your dashboard to see the new background. Adjust if needed.
Add More Applications (Optional):
- Continue adding more applications from your "Sketch" plan, assigning appropriate tags and pinning status. Aim for at least 2-3 more to get a feel for it.

Outcome:
You now have a personalized Heimdall dashboard with several applications, including a pinned item, tagged items for organization, and a custom background. You've experienced adding both generic and (potentially) enhanced applications. Your dashboard is starting to become a useful hub!

2. Intermediate Customization and Management

Now that you have a basic Heimdall setup, this section will delve into more advanced ways to customize its functionality and appearance, secure your instance, and manage its data. These intermediate steps will help you tailor Heimdall more precisely to your needs and ensure its long-term stability and security.

Advanced Application Configuration

Beyond simple links, Heimdall offers several ways to enhance how applications are displayed and interact. This includes leveraging enhanced application features more deeply, using custom icons, and even embedding content using iFrames for certain applications.

Deep Dive into Enhanced Applications:

We touched upon enhanced applications earlier. Their key benefit is displaying live data from the service directly on the Heimdall tile.

Common Enhanced Apps and Their Data:
- Download Clients (SABnzbd, NZBGet, qBittorrent, Deluge, Transmission): Current download/upload speed, queue size, remaining download amount.
- Media Management (Sonarr, Radarr, Lidarr, Bazarr): Number of series/movies/artists, missing items, wanted items, upcoming releases.
- Media Servers (Plex, Jellyfin, Emby): Recently added media, active streams.
- System Monitoring/Utilities (Pi-hole, Portainer, AdGuard Home, Glances): Ads blocked, DNS queries, container counts, system load.
- Indexers/Trackers (Prowlarr, NZBHydra2, Jackett): Status, number of configured indexers.
Finding API Keys: This is the most common stumbling block.
- General Strategy: Log into the application you want to integrate (e.g., Sonarr). Navigate to its Settings or Configuration section. Look for tabs or sub-sections named API, Security, General, or Advanced. The API key is usually a long string of random characters.
- Example for Sonarr: Settings -> General -> Security -> API Key.
- Example for Radarr: Settings -> General -> Security -> API Key.
- Example for qBittorrent: Web UI -> Tools -> Options -> Web UI -> Enable "Bypass authentication for clients on localhost" (if Heimdall and qBittorrent are on the same Docker network and qBittorrent is accessed via its container name by Heimdall) OR use username/password if Heimdall supports it for qBittorrent. For API access, qBittorrent often doesn't use a key but relies on session authentication or IP whitelisting for its WebAPI. Heimdall's qBittorrent module might require specific setup.
- Example for Pi-hole: Settings -> API / Web interface -> Show API token (you might need to click a button to reveal it).
URL Configuration:
- Ensure you use the correct full URL, including http:// or https:// and any port number and sub-path if applicable.
- Internal vs. External URLs: If Heimdall and the target application are running in Docker on the same host, you might be able to use Docker's internal DNS and container names (e.g., http://sonarr:8989) if they are on the same custom Docker network. This is often more reliable than using the host's IP address. However, for initial setup, using the host's IP address is usually simpler to troubleshoot.
Troubleshooting Enhanced Apps:
- No Data Displayed / Error on Tile:
  1. Verify API Key: Double-check it's copied correctly, without extra spaces.
  2. Verify URL: Ensure it's accessible from where Heimdall is running. You can test this by trying to curl the URL from within the Heimdall container:
```
docker exec -it heimdall curl -v <URL_of_enhanced_app>
```
    Look for a successful HTTP response (e.g., 200 OK). If you get "Connection refused" or "No route to host," there's a network connectivity issue between Heimdall and the app.
  3. Check Heimdall Logs: docker logs heimdall might show error messages related to API communication.
  4. Application-Specific Settings: Some apps might need "API access" explicitly enabled in their own settings.
  5. HTTPS/SSL Issues: If the target app uses HTTPS with a self-signed certificate, Heimdall (or the underlying PHP cURL library) might refuse to connect. You might need to configure Heimdall to ignore SSL errors for that specific app if such an option exists, or preferably, set up proper SSL for your internal services.

Custom Icons and Colors:

Personalizing the visual appearance of each tile can greatly improve the dashboard's usability and aesthetics.

Icons:
- Built-in Font Awesome: Heimdall often includes support for Font Awesome icons. When adding/editing an app, there's usually an icon field where you can type Font Awesome class names (e.g., fas fa-server, fab fa-docker, fas fa-film). You might need to look up available icons and their classes on the Font Awesome website. Some Heimdall versions have a picker.
- Uploading Custom Icons: Most Heimdall versions allow you to upload your own image file (PNG, JPG, SVG) to be used as an icon. This is great for applications that don't have a good Font Awesome representation or for using official logos.
  - Best Practices for Custom Icons: Use square images, ideally with transparent backgrounds (PNGs are good for this). Keep file sizes small to ensure fast loading. Recommended dimensions might be around 128x128 pixels or 256x256 pixels.
- Favicon Fetching: For generic links, Heimdall often attempts to automatically fetch the website's favicon to use as the icon. This can be hit-or-miss.
Colors:
- Each application tile can have a custom background color. This helps in visually grouping applications or making important ones stand out.
- Use a hex color picker or enter hex color codes (e.g., #3498db for a nice blue).

Using iFrames (Use with Caution):

Some Heimdall versions or community modifications allow you to embed content from another URL directly into a tile using an iFrame.

What is an iFrame? An iFrame (Inline Frame) is an HTML element that loads another HTML page within the document.
Potential Use Cases in Heimdall:
- Displaying a simple status page from another service.
- Embedding a Grafana graph.
- Showing a very simple web interface that doesn't require much interaction.
How to Configure (if supported):
- When adding/editing an application, there might be an "iFrame URL" field or an "Application Type" option like "iFrame."
- You provide the URL you want to embed.
Caveats and Limitations:
- X-Frame-Options Header: Many websites and applications prevent themselves from being embedded in iFrames for security reasons (to prevent clickjacking). They do this by sending an X-Frame-Options: DENY or X-Frame-Options: SAMEORIGIN HTTP header. If the target site sends this header, it will not load in the iFrame. You usually cannot override this from Heimdall's side; the server hosting the content dictates this.
- Content Security Policy (CSP): Modern websites also use Content-Security-Policy: frame-ancestors to control embedding, which is more flexible and supersedes X-Frame-Options.
- Usability: Content in an iFrame on a small Heimdall tile might be difficult to interact with.
- Security: Be cautious about embedding content from untrusted sources.
When it might work:
- Services you control where you can modify HTTP headers to allow framing.
- Services specifically designed to be embeddable.
- Simple, static HTML pages.

Generally, rely on Enhanced Applications for displaying data. Use iFrames sparingly and only when you know the source content allows embedding and is suitable for it.

Workshop Integrating a Media Server with Enhanced Features

This workshop will guide you through adding your media server (e.g., Plex, Jellyfin, or Emby) as an enhanced application to Heimdall, configuring it to display information like recently added media.

Objective: To add Plex (or an alternative like Jellyfin/Emby) to Heimdall as an enhanced application, displaying live information on its tile.

Prerequisites:

Heimdall installed and accessible.
A running instance of Plex Media Server, Jellyfin, or Emby.
For Plex:
- Your Plex URL (e.g., http://<plex-ip>:32400).
- Your Plex Token. To get this:
  1. Sign in to your Plex account in a web browser.
  2. Visit any library item's XML info page by:
    - Navigating to an item (movie, show).
    - Clicking the three-dot menu (...) -> Get Info.
    - In the Get Info dialog, click "View XML".
  3. In the XML page URL, look for X-Plex-Token=YOUR_TOKEN_HERE. Copy this token.
  4. Alternatively, follow Plex's official guide: Finding an Authentication Token / X-Plex-Token
For Jellyfin/Emby:
- Your Jellyfin/Emby URL (e.g., http://<jellyfin-ip>:8096).
- An API Key from Jellyfin/Emby:
  - Jellyfin: Dashboard -> API Keys -> Click '+' to generate a new key. Give it a name (e.g., "Heimdall").
  - Emby: Dashboard -> API Keys -> Generate API Key.

Steps:

Access Heimdall and Open Application Settings:
- Navigate to your Heimdall URL.
- Click the "+" or "Add an app" button to manage applications.
Add the Media Server Application:
- Click "Add" or "Create Application."
- Application Type: Start typing "Plex", "Jellyfin", or "Emby" in the name field or look for it in the application type dropdown. Heimdall should recognize it and offer the enhanced version. Select it.
- This will typically reveal additional fields specific to that media server.
Configure Plex (skip if using Jellyfin/Emby):
- Application Name: Plex
- URL: Your Plex server's URL (e.g., http://192.168.1.15:32400).
- API Key / Token (Plex Token): Paste the X-Plex-Token you obtained.
- Enable enhanced: Ensure any checkbox like "Enable enhanced features" or similar is checked (usually default for these app types).
- Other Plex options: Heimdall might offer options like "Number of items to show," "Show recently added movies/shows/music." Configure these as desired.
- Icon/Colour: Choose or let Heimdall default.
- Tags: Add a tag like Media.
- Click Save.
Configure Jellyfin (skip if using Plex/Emby):
- Application Name: Jellyfin
- URL: Your Jellyfin server's URL (e.g., http://192.168.1.16:8096).
- API Key: Paste the API key you generated in Jellyfin.
- Enable enhanced: Ensure active.
- Other Jellyfin options: Configure any specific display options available.
- Icon/Colour/Tags: Set as desired (e.g., Tag: Media).
- Click Save.
Configure Emby (skip if using Plex/Jellyfin):
- Application Name: Emby
- URL: Your Emby server's URL (e.g., http://192.168.1.17:8096).
- API Key: Paste the API key you generated in Emby.
- Enable enhanced: Ensure active.
- Other Emby options: Configure as needed.
- Icon/Colour/Tags: Set as desired (e.g., Tag: Media).
- Click Save.
Verify on Dashboard:
- Go back to your main Heimdall dashboard.
- Locate the new tile for your media server.
- It might take a few seconds to fetch data. You should see information like "Recently Added" media items, or a count of movies/shows, directly on the tile.
- Clicking the tile should take you to your media server's web interface.
Troubleshooting:
- Tile shows an error or no data:
  - Double-check URL: Is it correct? Is it reachable from the Heimdall container? (Use docker exec -it heimdall curl -v <your_media_server_url> to test connectivity from within the Heimdall container).
  - Double-check API Key/Token: Is it copied correctly? Is it still valid? Some tokens/keys can expire or be revoked.
  - SSL/HTTPS Issues: If your media server uses HTTPS with a self-signed certificate, Heimdall might have trouble connecting.
    - If your media server is on the same host or local network, try accessing it via http:// first for testing if https:// is problematic.
    - Ideally, set up proper SSL for your services (e.g., using a reverse proxy with Let's Encrypt), which we'll cover later.
  - Plex Specific:
    - Ensure your Plex server is claimed and accessible.
    - If you use Plex with a custom domain/reverse proxy, ensure the URL in Heimdall matches how Plex expects to be reached.
  - Check Heimdall Logs: docker logs heimdall might provide clues about connection failures or API errors.
  - Firewall: Ensure no firewall (on the host running Heimdall, or the host running the media server, or network firewall) is blocking communication between Heimdall and the media server on the required port.

Outcome: You have successfully integrated your media server with Heimdall, leveraging its enhanced application features. Your dashboard now provides a more dynamic and informative overview of your media library. You can apply similar steps to add other supported enhanced applications.

Securing Your Heimdall Instance

While Heimdall itself doesn't store highly sensitive personal data (beyond application URLs and potentially API keys for other services), it's good practice to secure access to it, especially if it's exposed to your local network or, in rare cases, the internet. Heimdall, by default, does not have built-in user authentication for accessing the dashboard itself; anyone who can reach its URL can see it.

There are several layers to consider for security:

Network Segmentation (Basic Protection):
- Ensure Heimdall is only accessible from trusted networks. If it's just for your home use, it should only be available on your local LAN.
- Avoid exposing Heimdall directly to the internet unless absolutely necessary and properly secured (see Reverse Proxy below).
Heimdall's Built-in Protection (Limited):
- Settings Page Protection: Some newer versions of Heimdall allow you to set a password to protect access to the settings page only. This prevents unauthorized users from adding/deleting apps or changing configurations, but the main dashboard view might still be public.
  - How to enable (if available): Look in Heimdall's general settings for an option like "Enable Password Protection for Settings," "Admin Password," or similar. Set a strong password.
- This is a minimal protection layer.
Reverse Proxy with Authentication and HTTPS (Recommended): This is the most robust way to secure Heimdall and any other web services you self-host. A reverse proxy sits in front of Heimdall (and other applications) and handles incoming web requests.
- Benefits:
  - HTTPS/SSL Encryption: Encrypts traffic between the user's browser and the reverse proxy, protecting API keys or other data in transit. This is crucial if you ever access Heimdall from outside your immediate secure network (e.g., over Wi-Fi). You can use Let's Encrypt for free SSL certificates.
  - Access Control / Authentication: The reverse proxy can enforce authentication (e.g., HTTP Basic Auth, or integration with OAuth/OIDC providers like Authelia, Authentik) before a user can even reach Heimdall. This means the entire Heimdall dashboard is protected.
  - Single Point of Access: Manage access and SSL for multiple services from one place.
  - Cleaner URLs: Access Heimdall via a domain name (e.g., heimdall.yourdomain.com) instead of an IP address and port.
- Popular Reverse Proxy Options:
  - Nginx Proxy Manager (NPM): User-friendly web interface for managing Nginx as a reverse proxy. Great for beginners. It simplifies SSL certificate generation (via Let's Encrypt) and setting up proxy hosts and access lists.
  - Traefik: A modern, cloud-native reverse proxy that's particularly well-suited for Docker environments due to its automatic service discovery. Steeper learning curve than NPM but very powerful.
  - Caddy: Known for its automatic HTTPS by default and simple configuration files.
  - Nginx (manual configuration): Very powerful and flexible, but requires manual configuration file editing.
- General Workflow (using Nginx Proxy Manager as an example):
  1. Set up Nginx Proxy Manager (NPM) – often as another Docker container.
  2. In NPM, add a new proxy host:
    - Domain Name: heimdall.yourlan.local (if using a local-only domain with local DNS like Pi-hole) or heimdall.yourpublicdomain.com (if exposing publicly, ensure you own the domain and can point DNS records to your public IP).
    - Scheme: http
    - Forward Hostname / IP: The IP address of the machine running Heimdall (e.g., 192.168.1.100).
    - Forward Port: The host port you mapped for Heimdall's HTTP access (e.g., 8080).
  3. SSL Tab (in NPM): Request a new SSL certificate (Let's Encrypt). For public domains, this requires your server to be reachable from the internet on ports 80/443 for validation. For local-only domains, you might use self-signed certificates or set up your own internal CA (more advanced).
  4. Access List Tab (in NPM): Create an access list with a username and password. Apply this access list to your Heimdall proxy host. This enforces HTTP Basic Authentication.
  5. Now, when you access https://heimdall.yourdomain.com, NPM will first prompt for the username/password, and then, if correct, proxy you to Heimdall over HTTPS.
Firewall:
- Use a host-based firewall (like ufw on Ubuntu, firewalld on CentOS/Fedora, or Windows Firewall) to restrict access to the Heimdall port only from specific IP addresses or subnets if needed.
- If you use a reverse proxy, you might configure your firewall to only allow access to the reverse proxy's ports (80/443) and block direct access to Heimdall's original port (e.g., 8080) from outside the host itself.
Regular Updates:
- Keep Heimdall updated to the latest version (as shown in the Docker installation section: docker-compose pull, docker-compose up -d). Updates often include security patches.
- Keep your Docker host system and Docker itself updated.

Focus on API Key Security: If you're using Enhanced Applications, the API keys stored in Heimdall's configuration are sensitive. If someone gains access to your Heimdall settings or its configuration files, they could potentially retrieve these keys. This is another strong reason to implement robust access control via a reverse proxy.

Workshop Securing Heimdall with Nginx Proxy Manager and Let's Encrypt

This workshop guides you through setting up Nginx Proxy Manager (NPM) as a reverse proxy for Heimdall, enabling HTTPS with a Let's Encrypt certificate, and adding basic authentication.

Disclaimer: This workshop assumes you have a publicly accessible server and a registered domain name for which you can manage DNS records if you want to use Let's Encrypt for a publicly valid SSL certificate. If you only want to secure Heimdall for local network access without a public domain, the Let's Encrypt part will be more complex (requiring DNS challenge or a private CA) or you might opt for a self-signed certificate generated by NPM (which browsers will warn about). For simplicity, this workshop will aim for a public domain setup.

Prerequisites:

Heimdall running and accessible (e.g., at http://<heimdall-host-ip>:<heimdall-port>).
Docker and Docker Compose installed on your server.
A server that is reachable from the internet on ports 80 (for HTTP validation) and 443 (for HTTPS).
A registered domain name (e.g., yourdomain.com).
Ability to add DNS records (specifically an A record) for your domain, pointing a subdomain (e.g., heimdall.yourdomain.com) to your server's public IP address.

Part 1: Setting up Nginx Proxy Manager (NPM)

Create a Directory for NPM:
```
mkdir -p ~/docker/npm
cd ~/docker/npm
```
Create docker-compose.yml for NPM: Create a docker-compose.yml file in ~/docker/npm:
```
nano docker-compose.yml
```
Paste the following:
```
version: '3.8'
services:
  app:
    image: 'jc21/nginx-proxy-manager:latest'
    container_name: npm
    restart: unless-stopped
    ports:
      # These ports are publicly exposed. Make sure your firewall allows them.
      - '80:80'    # Public HTTP Port
      - '443:443'  # Public HTTPS Port
      - '81:81'    # Admin Web UI Port (Access NPM admin interface here)
    volumes:
      - ./data:/data # Persists NPM data, including SSL certs and configs
      - ./letsencrypt:/etc/letsencrypt # Persists Let's Encrypt certificates
```
- Explanation:
  - 80:80 and 443:443: Map host ports 80 and 443 to the container for handling web traffic. Ensure these ports are not already in use on your host by another application. If they are, you'll need to stop that other application or use different host ports (which makes Let's Encrypt HTTP challenge more complex).
  - 81:81: Maps port 81 for accessing the NPM admin interface. You can change the host port (left side) if 81 is in use.
  - ./data:/data and ./letsencrypt:/etc/letsencrypt: Bind mounts for persistent storage of NPM's configuration and SSL certificates. These will be created as data and letsencrypt subdirectories in your ~/docker/npm directory.
Start Nginx Proxy Manager:
```
docker-compose up -d
```
Access NPM Admin Interface: Open your browser and go to http://<your-server-ip>:81.
- The default login credentials are:
  - Email: admin@example.com
  - Password: changeme
- You will be prompted to change these immediately. Do so with a strong, unique password.

Part 2: Configuring DNS

Go to your domain registrar or DNS provider's control panel.
Create an A record for the subdomain you want to use for Heimdall.
- Type: A
- Name/Host: heimdall (or whatever subdomain you choose, e.g., dash)
- Value/Points to: Your server's public IP address.
- TTL: Default is fine.
- Example: If your domain is yourdomain.com, this creates heimdall.yourdomain.com.
Wait for DNS propagation (can take a few minutes to a few hours, but often faster). You can use a tool like nslookup heimdall.yourdomain.com or an online DNS checker to see if it resolves to your IP.

Part 3: Configuring Heimdall Proxy Host in NPM

Log into NPM: http://<your-server-ip>:81.
Navigate to Hosts > Proxy Hosts.
Click "Add Proxy Host".
Details Tab:
- Domain Names: Enter your fully qualified subdomain (e.g., heimdall.yourdomain.com). You can add multiple if needed.
- Scheme: http (because Heimdall itself is running on HTTP internally).
- Forward Hostname / IP: Enter the local IP address of the server where your Heimdall Docker container is running (e.g., 192.168.1.100 or if NPM and Heimdall are on the same Docker host, you can often use the host's Docker bridge IP, e.g., 172.17.0.1, or the container name if they are on the same custom Docker network).
- Forward Port: Enter the host port you mapped for Heimdall's HTTP (e.g., 8080 from your Heimdall docker-compose.yml).
- Cache Assets: Optional, can be enabled.
- Block Common Exploits: Recommended to enable.
- Websockets Support: Enable if any app on Heimdall (or Heimdall itself) might use websockets (generally good to have on).
SSL Tab:
- SSL Certificate: Select "Request a new SSL Certificate".
- Force SSL: Enable this to automatically redirect HTTP requests to HTTPS.
- HTTP/2 Support: Enable for better performance.
- HSTS Enabled: Recommended for security once you confirm everything works.
- Email Address for Let's Encrypt: Enter your valid email address.
- "I Agree to the Let's Encrypt Terms of Service": Check the box.
- Click Save. NPM will attempt to obtain the SSL certificate from Let's Encrypt. This requires your DNS to be propagated and your server to be reachable on port 80 from the internet.
- If successful, the status will show "Online" with a green indicator. If it fails, check the logs (click the three dots next to the host entry > Edit > SSL > look for error messages or try "Renew Certificate"). Common issues are firewall blocking port 80, incorrect DNS, or Let's Encrypt rate limits.
Access Heimdall Securely (Test):
- Open your browser and navigate to https://heimdall.yourdomain.com.
- You should see Heimdall loading over HTTPS, with a valid lock icon in the address bar.

Part 4: Adding Basic Authentication

In NPM, navigate to Access Lists.
Click "Add Access List".
Details Tab:
- Name: Give it a descriptive name (e.g., Heimdall Auth).
Authorization Tab:
- Username: Enter your desired username.
- Password: Enter a strong password.
- Click Add. You can add multiple users if needed.
Click Save.
Go back to Hosts > Proxy Hosts.
Click the three dots next to your heimdall.yourdomain.com entry and choose "Edit".
Go to the "Access List" tab.
From the Access List dropdown, select the list you just created (e.g., Heimdall Auth).
Satisfy any: This option is for advanced setups with multiple authentication methods. For simple username/password, the default is fine.
Click Save.
Test Authentication:
- Open a new private/incognito browser window (to avoid cached sessions).
- Navigate to https://heimdall.yourdomain.com.
- You should now be prompted with a basic authentication dialog from your browser. Enter the username and password you configured in the Access List.
- If successful, you will be granted access to your Heimdall dashboard.

Outcome: You have now successfully secured your Heimdall instance using Nginx Proxy Manager. It's accessible via a custom subdomain over HTTPS (with a valid Let's Encrypt certificate), and access is protected by basic authentication. This is a significant improvement in security and professionalism for your self-hosted dashboard. You can use NPM to similarly protect other self-hosted services.

Backup and Restore Strategies

Your Heimdall configuration—all the applications you've added, their settings, API keys, tags, and custom appearance—is valuable. Losing this data due to disk failure, accidental deletion, or container issues would mean setting everything up again from scratch. Implementing a backup strategy is crucial for peace of mind and quick recovery.

Identifying Heimdall's Configuration Data:

As configured in our Docker setup, all of Heimdall's persistent data is stored in the volume mapped to /config inside the container.

If you used a named volume (e.g., heimdall_config:/config in docker-compose.yml with volumes: { heimdall_config: {} } at the root), the data resides in a Docker-managed directory, typically under /var/lib/docker/volumes/your_volume_name/_data/.
If you used a bind mount (e.g., /path/on/your/host/heimdall/config:/config), the data is directly in the host directory you specified (e.g., /srv/heimdall/config or ~/docker/heimdall/config).

The key files and folders within this /config directory usually include:

db/ or database/: Contains the SQLite database file (e.g., heimdall.sqlite or similar) which stores most of your application links, tags, and settings.
www/ or public/ (specifically subfolders like uploads or backgrounds): May store uploaded custom icons or background images.
php/ (and nginx/ if present in the volume): Contains runtime configuration files.
custom-css.css (or similar): If you've added custom CSS.

Essentially, the entire content of the directory mapped to /config needs to be backed up.

Manual Backup Methods:

This is the simplest approach, suitable for occasional backups or before making significant changes.

If using a Bind Mount:

Simply copy the entire host directory to a safe location (another drive, network share, cloud storage).

Example: If your config is in ~/docker/heimdall/config:

# Create a timestamped backup directory
BACKUP_DIR=~/heimdall_backups/$(date +%Y-%m-%d_%H-%M-%S)
mkdir -p "$BACKUP_DIR"
# Copy the config directory
cp -r ~/docker/heimdall/config "$BACKUP_DIR/"
echo "Heimdall backup completed to $BACKUP_DIR"

Or, create a compressed archive:

tar -czvf ~/heimdall_backups/heimdall_config_$(date +%Y-%m-%d_%H-%M-%S).tar.gz -C ~/docker/heimdall/ config
# -C changes directory to ~/docker/heimdall/ before archiving the 'config' folder,
# so the 'config' folder itself is at the root of the archive.

If using a Named Volume: You can't directly cp a named volume as easily. Here are a few ways:

Option A: Temporarily stop Heimdall and use a utility container to access the volume:

# Stop Heimdall container to ensure data consistency
cd ~/docker/heimdall # Or wherever your Heimdall docker-compose.yml is
docker-compose down

# Create a timestamped backup file name
BACKUP_FILE=~/heimdall_backups/heimdall_volume_$(date +%Y-%m-%d_%H-%M-%S).tar.gz
mkdir -p ~/heimdall_backups

# Run a temporary container mounting the Heimdall volume and a local backup directory
# Replace 'heimdall_heimdall_config' with your actual volume name (check with `docker volume ls`)
# Or if you used 'heimdall_data' as the volume name in docker-compose:
# Replace 'heimdall_data' with the actual volume name if it's different.
# The volume name might be <projectname>_heimdall_config if you used 'heimdall_config'
# in services and volumes sections. Check `docker volume ls`.
# Assuming your compose project directory was 'heimdall' and volume was 'heimdall_config':
HEIMDALL_VOLUME_NAME="heimdall_heimdall_config" # Adjust if your project name or volume name in compose was different
# If you named your volume explicitly like 'heimdall_data' in the root 'volumes:' block:
# HEIMDALL_VOLUME_NAME="heimdall_data"

docker run --rm \
    -v ${HEIMDALL_VOLUME_NAME}:/volume_data \
    -v ~/heimdall_backups:/backup_target \
    alpine \
    tar -czf /backup_target/$(basename "$BACKUP_FILE") -C /volume_data .
    # The '.' at the end means "everything in the current directory (/volume_data)"

echo "Heimdall volume backup completed to $BACKUP_FILE"

# Restart Heimdall
docker-compose up -d

Option B: Find the volume path on the host (less portable, Docker version dependent): You can inspect the volume to find its mountpoint on the host:
```
HEIMDALL_VOLUME_NAME="heimdall_heimdall_config" # Adjust as above
docker volume inspect ${HEIMDALL_VOLUME_NAME}
```
Look for the "Mountpoint" value (e.g., /var/lib/docker/volumes/heimdall_heimdall_config/_data). Then you can sudo cp -r or sudo tar that directory. This requires sudo and is more direct but less "Docker-idiomatic."

Automated Backup Scripts (e.g., using cron):

For regular, unattended backups, you can automate the manual methods using a cron job.

Create a Backup Script: Create a shell script, for example, ~/scripts/backup_heimdall.sh:

#!/bin/bash

# --- Configuration ---
# For Bind Mount:
# HEIMDALL_CONFIG_DIR="~/docker/heimdall/config" # Your Heimdall config bind mount path
# For Named Volume:
HEIMDALL_VOLUME_NAME="heimdall_heimdall_config" # Your Heimdall named volume (check `docker volume ls`)
                                            # Or "heimdall_data" if you named it explicitly in docker-compose

BACKUP_BASE_DIR="~/heimdall_backups" # Where to store backups
DAYS_TO_KEEP=7 # How many days of backups to retain
TIMESTAMP=$(date +%Y-%m-%d_%H-%M-%S)
# --- End Configuration ---

# Ensure backup base directory exists
mkdir -p "$BACKUP_BASE_DIR"

# Construct backup file name
BACKUP_FILE="$BACKUP_BASE_DIR/heimdall_backup_$TIMESTAMP.tar.gz"

echo "Starting Heimdall backup: $(date)"

# Choose backup method based on whether HEIMDALL_CONFIG_DIR is set (for bind mount)
if [ -n "${HEIMDALL_CONFIG_DIR}" ]; then
    echo "Using bind mount method for directory: ${HEIMDALL_CONFIG_DIR}"
    # Ensure PUID/PGID used by Heimdall can read this. If not, may need sudo for tar.
    # The -C option changes directory, so 'config' (or its contents) is at the root of the tarball.
    # Example: tar -czvf "$BACKUP_FILE" -C "$(dirname "${HEIMDALL_CONFIG_DIR}")" "$(basename "${HEIMDALL_CONFIG_DIR}")"
    # If HEIMDALL_CONFIG_DIR is ~/docker/heimdall/config, then:
    # tar -czvf "$BACKUP_FILE" -C ~/docker/heimdall config
    # This makes restoration easier as you just extract into ~/docker/heimdall
    tar -czvf "$BACKUP_FILE" -C "$(eval echo $(dirname "${HEIMDALL_CONFIG_DIR}"))" "$(basename "$(eval echo ${HEIMDALL_CONFIG_DIR})")"
    # Using eval to expand tilde
elif [ -n "${HEIMDALL_VOLUME_NAME}" ]; then
    echo "Using named volume method for volume: ${HEIMDALL_VOLUME_NAME}"
    # Temporarily stop Heimdall (optional but recommended for consistency)
    # This assumes docker-compose.yml is in ~/docker/heimdall
    # (cd ~/docker/heimdall && docker-compose stop heimdall)

    docker run --rm \
        -v "${HEIMDALL_VOLUME_NAME}:/volume_data:ro" \
        -v "${BACKUP_BASE_DIR}:/backup_target" \
        alpine \
        tar -czf "/backup_target/$(basename "$BACKUP_FILE")" -C /volume_data .

    # (cd ~/docker/heimdall && docker-compose start heimdall)
else
    echo "Error: Neither HEIMDALL_CONFIG_DIR nor HEIMDALL_VOLUME_NAME is set in the script."
    exit 1
fi

if [ $? -eq 0 ]; then
    echo "Backup successful: $BACKUP_FILE"
else
    echo "Backup FAILED."
    exit 1
fi

# Prune old backups
echo "Pruning backups older than $DAYS_TO_KEEP days..."
find "$BACKUP_BASE_DIR" -name "heimdall_backup_*.tar.gz" -mtime +"$DAYS_TO_KEEP" -exec echo "Deleting old backup: {}" \; -exec rm {} \;

echo "Backup process finished: $(date)"
echo "------------------------------------"

Important:
- Adjust HEIMDALL_CONFIG_DIR (for bind mount) or HEIMDALL_VOLUME_NAME (for named volume) at the top of the script. Comment out or remove the one you are not using.
- HEIMDALL_VOLUME_NAME: Use docker volume ls to find the exact name of your Heimdall data volume. It's often <project_directory_name>_heimdall_config (e.g., if your compose file is in ~/docker/heimdall and you used heimdall_config as the volume key, it might be heimdall_heimdall_config) or the name you explicitly set (e.g., heimdall_data).
- eval echo is used to correctly expand ~ in paths.
- The ro (read-only) flag when mounting /volume_data is a good safety measure for the named volume backup.
- The lines for stopping/starting Heimdall are commented out. For critical data consistency, stopping the app is best, but for Heimdall (which mostly reads its DB unless you're actively changing settings), backing up live might be acceptable for many.
Make the script executable: chmod +x ~/scripts/backup_heimdall.sh.

Test the Script: Run it manually: ~/scripts/backup_heimdall.sh. Check if a .tar.gz file is created in ~/heimdall_backups.
Schedule with Cron: Open your crontab for editing: crontab -e. Add a line to run the script, for example, daily at 2:00 AM:
```
0 2 * * * /bin/bash /home/your_user/scripts/backup_heimdall.sh >> /home/your_user/logs/heimdall_backup.log 2>&1
```
- Replace your_user with your actual username.
- >> /home/your_user/logs/heimdall_backup.log 2>&1: Appends standard output and standard error to a log file. Create the ~/logs directory if it doesn't exist.
- Save and exit the crontab editor.

Restoring from a Backup:

The restore process depends on how you backed up and whether you're restoring to the same or a new system.

Ensure Heimdall Container is Stopped/Removed:
If Heimdall is running, stop and remove it to prevent conflicts:

cd ~/docker/heimdall # Or wherever your Heimdall docker-compose.yml is
docker-compose down

If using a named volume, you might also want to remove the old (potentially corrupted) volume before restoring, BUT BE CAREFUL:

# !! DANGER: This deletes the current volume data. Only do if you're sure you want to restore !!
# docker volume rm <your_heimdall_volume_name>

Locate Your Backup File:
Identify the .tar.gz backup file you want to restore.
Restore Process:
- If you used a Bind Mount (HEIMDALL_CONFIG_DIR):
  1. Ensure the target bind mount directory is empty or remove its contents (e.g., rm -rf ~/docker/heimdall/config/*).
  2. Extract the backup into the parent directory of your config folder. If your backup heimdall_config_XXXX.tar.gz contains the config folder at its root:
```
# Assuming your bind mount is ~/docker/heimdall/config
# and your compose file is in ~/docker/heimdall
tar -xzvf /path/to/your/heimdall_backup_XXXX.tar.gz -C ~/docker/heimdall/
```
    This should recreate ~/docker/heimdall/config with the backed-up content.
  3. Verify permissions on the restored config directory and its contents. Ensure they are accessible by the PUID/PGID Heimdall will run as. sudo chown -R your_user:your_group ~/docker/heimdall/config might be needed, replacing your_user:your_group with the user/group corresponding to your PUID/PGID.
- If you used a Named Volume (HEIMDALL_VOLUME_NAME):
  1. Ensure the named volume exists (Docker Compose will create it if it doesn't on up). If you explicitly removed it, it will be recreated empty.
  2. Use a temporary container to extract the backup into the volume:
```
# Ensure Heimdall is down
# HEIMDALL_VOLUME_NAME should be set to your actual volume name
HEIMDALL_VOLUME_NAME="heimdall_heimdall_config" # Adjust if needed
BACKUP_FILE_TO_RESTORE="/path/to/your/heimdall_backup_XXXX.tar.gz"

docker run --rm \
    -v "${HEIMDALL_VOLUME_NAME}:/volume_data" \
    -v "$(dirname "$BACKUP_FILE_TO_RESTORE"):/backup_source" \
    alpine \
    tar -xzf "/backup_source/$(basename "$BACKUP_FILE_TO_RESTORE")" -C /volume_data
```
    This mounts the named volume to /volume_data and the directory containing your backup to /backup_source, then extracts the tarball into /volume_data.

Restart Heimdall:

cd ~/docker/heimdall
docker-compose up -d

Verify:
Access Heimdall in your browser and check if your applications, tags, and settings are restored.

Important Considerations:

Backup Storage: Store backups on a separate physical drive or remote location (e.g., cloud storage, another server via scp or rsync in your script). A backup on the same disk as the original data protects against application errors but not disk failure.
Testing Restores: Periodically test your restore process to ensure your backups are valid and you know how to recover.
Database Consistency: For applications with active databases, stopping the application before backup is the safest way to ensure database consistency. For Heimdall, this is less critical unless you are actively making many changes during the backup window.

Workshop Automating Heimdall Backups with Cron

This workshop will guide you through setting up the automated backup script and scheduling it with a cron job for your Heimdall configuration. This example will assume you are using a named volume for Heimdall, as it's generally preferred.

Objective: To create a bash script that backs up Heimdall's named volume, prunes old backups, and schedule this script to run daily using cron.

Prerequisites:

Heimdall running via Docker Compose, using a named volume for its /config data.
Access to the terminal on the Docker host.
Knowledge of your Heimdall Docker volume name (use docker volume ls and identify it, e.g., heimdall_heimdall_config or heimdall_data).

Steps:

Identify Your Heimdall Volume Name:
Open your terminal and list your Docker volumes:
```
docker volume ls
```
Look for the volume associated with your Heimdall container. If your docker-compose.yml is in a directory named heimdall and your volume definition in the services section is heimdall_config:/config, and in the root volumes section is heimdall_config: ..., the volume name will likely be heimdall_heimdall_config. If you explicitly named it (e.g., heimdall_data: with name: heimdall_appdata), use that name. For this workshop, let's assume the volume name is heimdall_heimdall_config. Adjust this in the script if yours is different.

Create Directories for Script and Backups:

mkdir -p ~/scripts
mkdir -p ~/heimdall_backups
mkdir -p ~/logs # For cron job logs

Create the Backup Script:
Create the script file ~/scripts/backup_heimdall_named_volume.sh:

nano ~/scripts/backup_heimdall_named_volume.sh

Paste the following script content. Remember to replace YOUR_HEIMDALL_VOLUME_NAME_HERE with your actual volume name.

#!/bin/bash

# --- Configuration ---
HEIMDALL_VOLUME_NAME="YOUR_HEIMDALL_VOLUME_NAME_HERE" # IMPORTANT: Set this! e.g., heimdall_heimdall_config
HEIMDALL_COMPOSE_DIR="~/docker/heimdall" # Path to your Heimdall docker-compose.yml directory

BACKUP_BASE_DIR="~/heimdall_backups"
DAYS_TO_KEEP=7 # How many days of backups to retain
TIMESTAMP=$(date +%Y-%m-%d_%H-%M-%S)
LOG_FILE="~/logs/heimdall_backup.log" # Log file for cron output
# --- End Configuration ---

# Expand tilde paths
HEIMDALL_COMPOSE_DIR=$(eval echo ${HEIMDALL_COMPOSE_DIR})
BACKUP_BASE_DIR=$(eval echo ${BACKUP_BASE_DIR})
LOG_FILE=$(eval echo ${LOG_FILE})

# Function to log messages
log_message() {
    echo "$(date +'%Y-%m-%d %H:%M:%S') - $1" >> "$LOG_FILE"
}

log_message "Starting Heimdall backup script..."

# Ensure backup base directory exists
mkdir -p "$BACKUP_BASE_DIR"
if [ ! -d "$BACKUP_BASE_DIR" ]; then
    log_message "Error: Backup base directory $BACKUP_BASE_DIR could not be created."
    exit 1
fi

# Construct backup file name
BACKUP_FILE="$BACKUP_BASE_DIR/heimdall_backup_volume_$TIMESTAMP.tar.gz"

log_message "Selected Heimdall volume: ${HEIMDALL_VOLUME_NAME}"
log_message "Backup file will be: $BACKUP_FILE"

# Optional: Stop Heimdall container for data consistency
# log_message "Stopping Heimdall container..."
# (cd "$HEIMDALL_COMPOSE_DIR" && docker-compose stop heimdall)
# if [ $? -ne 0 ]; then
#     log_message "Error stopping Heimdall. Proceeding with backup, but data might be inconsistent."
# fi

log_message "Creating backup using Docker run..."
docker run --rm \
    -v "${HEIMDALL_VOLUME_NAME}:/volume_data:ro" \
    -v "${BACKUP_BASE_DIR}:/backup_target" \
    alpine/git:latest \
    sh -c "tar -czf \"/backup_target/$(basename "$BACKUP_FILE")\" -C /volume_data ."
    # Using alpine/git as it's small and has tar. Could use just 'alpine'.

if [ $? -eq 0 ]; then
    log_message "Backup successful: $BACKUP_FILE"
else
    log_message "Backup FAILED. Check Docker run command and volume names."
    # Optional: Restart Heimdall even if backup failed, if it was stopped
    # (cd "$HEIMDALL_COMPOSE_DIR" && docker-compose start heimdall)
    exit 1
fi

# Optional: Restart Heimdall container if it was stopped
# log_message "Starting Heimdall container..."
# (cd "$HEIMDALL_COMPOSE_DIR" && docker-compose start heimdall)
# if [ $? -ne 0 ]; then
#    log_message "Error starting Heimdall. Please check manually."
# fi

# Prune old backups
log_message "Pruning backups older than $DAYS_TO_KEEP days from $BACKUP_BASE_DIR..."
find "$BACKUP_BASE_DIR" -name "heimdall_backup_volume_*.tar.gz" -mtime +"$DAYS_TO_KEEP" -print0 | while IFS= read -r -d $'\0' old_backup; do
    log_message "Deleting old backup: $old_backup"
    rm "$old_backup"
done

log_message "Heimdall backup script finished."
log_message "------------------------------------"

Before saving, make sure you replace YOUR_HEIMDALL_VOLUME_NAME_HERE with the actual name of your Heimdall data volume (e.g., heimdall_heimdall_config). Save and close (Ctrl+X, Y, Enter in nano).

Make the Script Executable:

chmod +x ~/scripts/backup_heimdall_named_volume.sh

Test the Script Manually:
Run the script from your terminal:
```
~/scripts/backup_heimdall_named_volume.sh
```
- Check the output in your terminal (it will also log to ~/logs/heimdall_backup.log).
- Verify that a new .tar.gz file is created in your ~/heimdall_backups directory.
- Run it a second time to ensure it doesn't error on existing files and that pruning (if you had files older than DAYS_TO_KEEP) works. (You might need to touch some dummy old backup files to test pruning properly or temporarily reduce DAYS_TO_KEEP to 0).
Schedule the Script with Cron:
Open your user's crontab:
```
crontab -e
```
If prompted, choose an editor (nano is usually easiest). Add the following line to the end of the file to schedule the script daily at 3:00 AM (adjust time as you like):
```
0 3 * * * /bin/bash /home/your_username/scripts/backup_heimdall_named_volume.sh
```
- Replace your_username with your actual Linux username.
- The script itself handles logging to ~/logs/heimdall_backup.log, so direct cron output redirection isn't strictly needed here but can be added as >> /path/to/cron_specific.log 2>&1 for cron daemon specific messages. Save and exit the crontab editor.
Verify Cron Setup (Optional):
You can list your cron jobs to ensure it was added:
```
crontab -l
```
After the scheduled time passes (e.g., the next day after 3:00 AM), check the ~/logs/heimdall_backup.log file and the ~/heimdall_backups directory to confirm the backup ran successfully.

Outcome:
You have now created and scheduled an automated backup solution for your Heimdall named volume. Your Heimdall configuration will be backed up daily, and old backups will be pruned, providing a safety net against data loss. Remember to occasionally test the restore process from these backups.

Customizing Appearance with CSS

While Heimdall offers some built-in appearance customization (like background images and tile colors), you can achieve a much deeper level of personalization by applying custom Cascading Style Sheets (CSS). This allows you to change fonts, spacing, tile appearance, hide elements, and much more.

Understanding Heimdall's HTML Structure (Briefly):

To effectively write custom CSS for Heimdall, you need a basic understanding of how its page elements are structured in HTML. You don't need to be an HTML expert, but knowing how to use your browser's Developer Tools is key.

Browser Developer Tools:
- In most browsers (Chrome, Firefox, Edge), right-click on an element on your Heimdall page (e.g., a tile, the header, a tag) and select "Inspect" or "Inspect Element."
- This opens the Developer Tools, typically showing:
  - Elements/Inspector Panel: The HTML structure of the page. As you hover over HTML tags here, the corresponding element on the page will be highlighted.
  - Styles Panel: The CSS rules currently applied to the selected HTML element, including rules from Heimdall's default stylesheets and any custom CSS you add.
Identifying Selectors:
- When you select an element in the Elements panel, look at its HTML tag (e.g., <div>, <a>, <li>), its class attributes (e.g., class="item app", class="title"), and its id attributes (e.g., id="search-form"). These are what you'll use as CSS selectors to target specific elements.
- Examples:
  - An application tile might be a div with class app.
  - The title within that tile might be an h3 with class title.
  - The main container for all apps might be a div with id apps-container.

Using the Custom CSS Field in Heimdall Settings:

Heimdall provides a dedicated field in its settings where you can paste your custom CSS code.

Navigate to your Heimdall instance.
Go to Settings (usually a cogwheel icon or a "Settings" link).
Look for a section named "Customization," "Appearance," "Styling," or similar.
Within this section, you should find a text area labeled "Custom CSS" or "Additional CSS."
Paste your CSS rules directly into this text area.
Save the settings. Heimdall will apply these styles, typically by injecting them into a <style> tag in the page's <head>.
Refresh your Heimdall dashboard page to see the changes. You might need to do a hard refresh (Ctrl+Shift+R or Cmd+Shift+R) to bypass browser cache.

Basic CSS Examples for Common Tweaks:

Here are some examples to get you started. You'll need to use your browser's Inspector to find the correct selectors for your specific version of Heimdall, as class names can change. The examples below are illustrative.

Change the Font for Application Titles:
Let's say application titles are h3 elements with a class title inside a div with class app.

.app .title {
    font-family: 'Arial', sans-serif; /* Change to your desired font */
    font-size: 1.1em; /* Make it slightly larger */
    color: #ffffff; /* Change text color */
}

Add a Border Radius to Application Tiles:
If application tiles are div elements with class item or app:

.item, .app { /* Or whatever your tile class is */
    border-radius: 10px; /* Rounded corners */
    box-shadow: 3px 3px 5px rgba(0,0,0,0.2); /* Add a subtle shadow */
}

Change the Background Color of the Pinned Items Area:
If the pinned items area has an ID like pinned-apps:

#pinned-apps {
    background-color: rgba(0, 0, 0, 0.1); /* Slightly darker transparent background */
    padding: 10px;
    border-radius: 8px;
}

Hide the Search Bar:
If the search bar is in a form with ID search-form:

#search-form {
    display: none !important; /* Use !important sparingly, only if needed to override existing styles */
}

Increase Spacing Between Tiles:
If tiles are list items li within an unordered list ul:

ul.apps-list > li { /* Adjust selector as needed */
    margin: 10px; /* Add more margin around each tile */
}

Style Tags Differently:
If tags are <a> elements with class tag-link:

.tag-link {
    background-color: #5dade2;
    color: white;
    padding: 5px 10px;
    border-radius: 15px;
    font-size: 0.9em;
    margin-right: 5px;
}
.tag-link:hover {
    background-color: #3498db;
}

Workflow for Applying Custom CSS:

Identify What You Want to Change: Pinpoint the visual aspect you want to modify.
Inspect the Element: Use browser developer tools to find the HTML element and its selectors (classes, ID).
Test CSS in Developer Tools: Many browsers allow you to edit CSS rules live in the Styles panel or add new rules to an element to see their effect immediately. This is a great way to experiment without constantly saving in Heimdall.
Write Your CSS Rule: Construct your CSS rule using the selectors you found.
Add to Heimdall's Custom CSS Field: Copy your tested CSS rule into the Custom CSS field in Heimdall's settings.
Save and Refresh: Save settings in Heimdall and refresh the dashboard page.
Iterate: If it doesn't work or needs adjustment, go back to step 2 or 3. CSS can sometimes be tricky due to specificity (how browsers decide which rule applies if multiple rules target the same element).

Important CSS Concepts:

Selectors: element (e.g., body, h1, div), .class (e.g., .my-class), #id (e.g., #my-id). You can combine them: div.my-class (a div with class my-class), ul > li (an li that is a direct child of a ul).
Properties & Values: property: value; (e.g., color: blue;, font-size: 16px;).
Specificity: More specific selectors override less specific ones. IDs are more specific than classes, which are more specific than element types. Inline styles (not recommended here) are most specific.
!important: Appending !important to a CSS value (e.g., color: red !important;) makes it override almost any other declaration. Use it as a last resort, as it can make CSS harder to maintain.

Custom CSS is a powerful way to make your Heimdall instance truly unique and aligned with your personal aesthetic.

Workshop Creating a Themed Dashboard with Custom CSS

This workshop will guide you through applying several custom CSS rules to create a simple "dark theme" for your Heimdall dashboard, modifying tile appearance and fonts.

Objective:
To apply custom CSS to change the overall theme of Heimdall, including background, text colors, tile styles, and fonts.

Prerequisites:

Heimdall installed and accessible.
Familiarity with using your browser's Developer Tools (Inspect Element).
Heimdall's Custom CSS setting accessible.

Note:
The exact CSS selectors might vary slightly depending on your Heimdall version. This workshop provides common selectors; you may need to adjust them using your browser's Inspector.

Theme Goal: A Simple Dark Theme

Dark page background.
Lighter text.
Slightly rounded, shadowed tiles.
A different font for application titles.

Steps:

Open Heimdall and Browser Developer Tools:
- Navigate to your Heimdall dashboard.
- Right-click anywhere on the page and select "Inspect" or "Inspect Element."
Identify Key Selectors (and take notes):
- Page Body: Inspect the main background of the page. Find the <body> tag. Note its classes or ID if any, though body itself is often sufficient.
- Application Tiles: Inspect one of your application tiles. It's likely a <div> or <li> with a class like app, item, or tile.
- Tile Titles: Inspect the name/title text within an application tile. It might be an <h3>, <h4>, or <span> with a class like title, app-title, or name.
- Tile URLs/Info (if present): Inspect any secondary text on the tile (like the URL or enhanced app info).
- Tags Area: Inspect the area where tags are displayed.
- Pinned Items Area: Inspect the container for pinned items.
Example (these are guesses, verify with your Inspector!):
- Page Body: body
- Tiles: div.app (or li.item)
- Tile Titles: h3.title
- Tile Info: p.url or span.info
- Pinned Area: div#pinned-items (or similar ID/class)
- Tags: a.tag (or span.tag-item)

Prepare Your Custom CSS Snippets (in a text editor first):

Overall Page Background and Text Color:

body {
    background-color: #2c3e50 !important; /* Dark blue-grey background */
    color: #ecf0f1 !important; /* Light grey text for general text */
}

(Using !important here to ensure it overrides default body styles, common for themes).

Application Tile Styling: (Assuming tiles are div.app and titles h3.title, info p.app-url)

/* General tile styling */
.app, .item { /* Use the correct selector for your tiles */
    background-color: #34495e; /* Slightly lighter dark blue-grey for tiles */
    border-radius: 8px;
    box-shadow: 2px 2px 8px rgba(0,0,0,0.3);
    border: 1px solid #4a6fa5; /* Subtle border */
    /* Remove default Heimdall tile background color if it interferes */
    /* background-image: none !important; */
}

/* Tile Title */
.app .title, .item .title { /* Adjust selector */
    font-family: 'Roboto', 'Segoe UI', sans-serif; /* Cleaner font */
    color: #ffffff !important; /* White title text */
    font-weight: bold;
}

/* Tile URL or other info text */
.app .url, .item .info, .app-url { /* Adjust selectors */
    color: #bdc3c7 !important; /* Lighter grey for secondary text */
}

Pinned Items Area (Optional Styling): (Assuming div#pinned or section.pinned-items)

#pinned, .pinned-items { /* Adjust selector */
    background-color: rgba(0,0,0,0.1); /* Even darker transparent background */
    padding: 15px;
    border-radius: 10px;
    margin-bottom: 20px;
}

Tags Styling: (Assuming tags are a.tag)

.tag { /* Adjust selector */
    background-color: #1abc9c !important; /* Teal background for tags */
    color: white !important;
    border-radius: 15px;
    padding: 4px 10px;
}
.tag:hover {
    background-color: #16a085 !important; /* Darker teal on hover */
}

Combine and Apply CSS in Heimdall:
- Go to Heimdall's Settings > Customization (or Appearance) > Custom CSS field.
- Copy all your CSS snippets from your text editor and paste them into this field.
- Click Save.
Refresh and Observe:
- Refresh your Heimdall dashboard (Ctrl+Shift+R or Cmd+Shift+R for a hard refresh).
- Observe the changes. Does it look like a dark theme? Are the tiles rounded? Is the font different?
Iterate and Refine (Using Developer Tools):
- If something doesn't look right or a style isn't applying:
  - Right-click the element and "Inspect."
  - In the Styles panel, see which rules are being applied. Your custom CSS should appear (often from an "inline style sheet" or a <style> tag if Heimdall injects it that way).
  - Check for typos in your selectors or properties.
  - Verify your selectors match the actual HTML structure.
  - You might need to increase selector specificity (e.g., body div.app .title instead of just .title) or, as a last resort, use !important if a default style is too strong.
  - Experiment with CSS changes directly in the Styles panel until you get the desired effect, then copy those changes back to Heimdall's Custom CSS field.
- Example: If tile backgrounds are still the default colors, you might need to override the specific style Heimdall uses for individual tile colors, or make your general tile background more specific or !important.
```
.app, .item {
    background-color: #34495e !important; /* Adding !important here if needed */
    /* ... other styles ... */
}
```

Outcome:
You have now applied a custom dark theme to your Heimdall dashboard using CSS. You've practiced inspecting elements, identifying selectors, writing CSS rules, and applying them through Heimdall's settings. This gives you powerful control over the look and feel of your personal dashboard. Feel free to experiment further with other CSS properties to fine-tune your theme!

3. Advanced Integration and Automation

This section explores more advanced topics, moving beyond basic configuration and appearance. We'll look at how Heimdall can be further integrated into your self-hosted ecosystem, how to monitor its health, understand its place among alternatives, and even how you might contribute to its development.

Extending Heimdall Functionality

While Heimdall's core purpose is to be a launcher, you can think about extending its utility or integrating it more deeply with your workflows through various means. This often involves scripting, interacting with its configuration, or using external tools.

API Usage (Primarily for Enhanced Apps, Limited for Dashboard Management):

Heimdall's Own API: Heimdall itself does not have a comprehensive, documented public API for managing the dashboard (like adding/deleting apps programmatically via HTTP requests). Its "API" interactions are primarily outbound: Heimdall acts as an API client to fetch data from services like Sonarr, Radarr, etc., for its Enhanced Applications.
Interacting with Configuration Files (Use with Extreme Caution):
- Heimdall stores its configuration primarily in an SQLite database located within its /config volume (e.g., /config/db/heimdall.sqlite or similar).
- Directly manipulating this SQLite database is highly discouraged for typical users. It requires understanding the database schema, risks data corruption if not done correctly, and changes might be overwritten by Heimdall or cause unexpected behavior.
- However, for advanced users or specific automated tasks, one could theoretically write scripts (e.g., Python with sqlite3 library) to read from or write to this database. This would require stopping Heimdall, performing the database operations, and then restarting it.
- A safer approach for automation might involve manipulating exported/imported configuration if Heimdall supports a human-readable format for this (e.g., JSON), though this feature is not consistently available or robust across all versions.

Scripting for Dynamic Link Management (Conceptual / Advanced):

Imagine you have a system that dynamically provisions new services, and you want them to automatically appear on your Heimdall dashboard. Since Heimdall lacks a direct management API, this is challenging but conceptually possible through advanced means:

Template-Based Configuration Generation:
- If you manage your Heimdall applications via a structured list (e.g., a YAML or JSON file you maintain yourself), you could write a script that reads this list and programmatically generates the necessary SQL INSERT statements to add these applications to Heimdall's SQLite database.
- This script would need to:
  1. Stop the Heimdall container.
  2. Connect to the SQLite database.
  3. Execute the generated SQL statements.
  4. Close the database connection.
  5. Start the Heimdall container.
- This is complex and error-prone.
Browser Automation Tools (e.g., Selenium, Puppeteer):
- You could write a script using a browser automation tool to interact with Heimdall's web UI programmatically. The script would navigate to Heimdall, log in (if settings are password-protected), click the "Add App" button, fill in the form fields, and save.
- This is more robust against changes in database schema but can be slow and brittle if the UI changes significantly between Heimdall versions.
Leveraging Heimdall's (Undocumented) Internal Mechanisms:
- Advanced users might reverse-engineer the HTTP requests Heimdall's frontend makes to its backend when an app is added via the UI. They could then try to replicate these requests in a script. This is highly dependent on the Heimdall version and can break easily with updates.

For most users, manually adding applications via the UI is sufficient. These advanced methods are for very specific automation needs and require significant technical expertise.

Browser Extensions for Quick Adding (Community/Third-Party):

While not an official feature, it's conceivable that community-developed browser extensions could exist or be created to facilitate adding the current webpage to Heimdall.
Such an extension would typically require:
1. Configuration with your Heimdall URL.
2. Potentially an API key or credentials if Heimdall's settings page is protected and the extension interacts with it programmatically (which, as discussed, is difficult without a proper API).
3. A simpler extension might just pre-fill a form that submits to a specific URL on your Heimdall instance, or open the "Add App" page with URL and Title parameters.
A quick search for "Heimdall browser extension" can reveal if any such tools are available.

Using Heimdall as a Centralized Hub for Other Tools:

Links to Other Dashboards: If you use other specialized dashboards (e.g., Grafana for metrics, Uptime Kuma for status pages, a network monitoring tool), Heimdall is the perfect place to link to them.
Documentation Links: Keep links to important documentation for your self-hosted services or your own notes directly on Heimdall for quick access.

The key is to think of Heimdall as your primary navigation point. If it makes sense to access something from a "central hub," consider adding it to Heimdall.

Workshop Scripting a Simple Check for Enhanced App URLs

Since directly manipulating Heimdall's app list programmatically is complex and risky, this workshop will focus on a related, safer scripting task: creating a simple script to check if the URLs configured for your Heimdall Enhanced Apps are still reachable. This can help you identify services that might be down.

This script will not interact with Heimdall's database directly but will require you to manually list the URLs you want to check (which you'd get from your Heimdall configuration).

Objective: To write a bash script that takes a list of URLs (representing your Heimdall enhanced apps) and checks if they return a successful HTTP status code.

Prerequisites:

A Linux environment (or WSL on Windows) with curl installed.
A text editor.
A list of URLs for services you have on your Heimdall dashboard (especially enhanced apps).

Steps:

Gather Your Application URLs:
- Go through your Heimdall dashboard. For each important (especially enhanced) application, note down its full URL (e.g., http://192.168.1.10:8989 for Sonarr, http://192.168.1.11:7878 for Radarr).
Create a URL List File: Create a new text file, for example, ~/heimdall_app_urls.txt. In this file, list each URL on a new line:
```
http://192.168.1.10:8989
http://192.168.1.11:7878
https://plex.yourdomain.com
http://your-pihole-ip/admin
```
Save this file.

Create the Bash Script: Create a new script file, for example, ~/scripts/check_heimdall_urls.sh:

nano ~/scripts/check_heimdall_urls.sh

Paste the following script:

#!/bin/bash

URL_FILE="~/heimdall_app_urls.txt" # Path to your list of URLs
TIMEOUT_SECONDS=5 # How long to wait for a response from each URL

# Expand tilde
URL_FILE=$(eval echo ${URL_FILE})

if [ ! -f "$URL_FILE" ]; then
    echo "Error: URL file not found at $URL_FILE"
    exit 1
fi

echo "Checking URLs from $URL_FILE..."
echo "-------------------------------------"

SUCCESS_COUNT=0
FAIL_COUNT=0

while IFS= read -r url || [[ -n "$url" ]]; do
    if [ -z "$url" ]; then # Skip empty lines
        continue
    fi

    echo -n "Checking $url ... "

    # Use curl to get HTTP status code.
    # -s: silent mode
    # -o /dev/null: discard output body
    # -w "%{http_code}": output only the HTTP status code
    # --connect-timeout: max time for connection
    # -L: follow redirects (optional, but often useful)
    # --max-time: max total time for operation
    status_code=$(curl -s -o /dev/null -w "%{http_code}" --connect-timeout $TIMEOUT_SECONDS --max-time $((TIMEOUT_SECONDS + 2)) -L "$url")

    if [[ "$status_code" -ge 200 && "$status_code" -lt 400 ]]; then
        echo "OK (Status: $status_code)"
        SUCCESS_COUNT=$((SUCCESS_COUNT + 1))
    elif [[ "$status_code" == "000" ]]; then
        echo "FAIL (Status: $status_code - Timeout or Connection Refused)"
        FAIL_COUNT=$((FAIL_COUNT + 1))
    else
        echo "FAIL (Status: $status_code)"
        FAIL_COUNT=$((FAIL_COUNT + 1))
    fi
done < "$URL_FILE"

echo "-------------------------------------"
echo "Check complete."
echo "Successful: $SUCCESS_COUNT"
echo "Failed:     $FAIL_COUNT"

if [ "$FAIL_COUNT" -gt 0 ]; then
    exit 1 # Exit with error code if any checks failed
else
    exit 0
fi

Save and close the file.

Make the Script Executable:

chmod +x ~/scripts/check_heimdall_urls.sh

Run the Script:

~/scripts/check_heimdall_urls.sh

Expected Output:

Checking URLs from /home/your_user/heimdall_app_urls.txt...
-------------------------------------
Checking http://192.168.1.10:8989 ... OK (Status: 200)
Checking http://192.168.1.11:7878 ... OK (Status: 200)
Checking https://plex.yourdomain.com ... OK (Status: 200)
Checking http://your-pihole-ip/admin ... OK (Status: 200)
Checking http://nonexistent-service.local ... FAIL (Status: 000 - Timeout or Connection Refused)
-------------------------------------
Check complete.
Successful: 4
Failed:     1

(If a service is down or the URL is incorrect, you'll see a "FAIL" status. 000 often means connection refused or timeout.)

Potential Enhancements (Optional):
- Add notifications (e.g., send an email or a Pushbullet notification if any check fails). This would require installing and configuring mail utilities or notification clients.
- Schedule this script with cron to run periodically and alert you to downed services.
- Read URLs directly from Heimdall's SQLite database (very advanced, requires stopping Heimdall, Python/sqlite knowledge, and understanding the DB schema).

Outcome:
You have created a useful bash script that can help you monitor the availability of the services linked on your Heimdall dashboard. While it doesn't directly "extend" Heimdall's features by modifying Heimdall itself, it complements Heimdall by helping ensure the links on your dashboard are functional. This is a practical example of how scripting can augment your self-hosted environment.

Monitoring and Maintenance

Ensuring your Heimdall instance (and the server it runs on) remains healthy and performant is key to a reliable dashboard experience. This involves monitoring system resources, checking container logs, and performing routine maintenance.

Monitoring Heimdall's Docker Container:

Container Logs: The first place to look for issues or information about Heimdall's operation is its Docker logs.
```
docker logs heimdall
```
To follow logs in real-time (e.g., when troubleshooting an enhanced app):
```
docker logs -f heimdall
```
Look for:
- Error messages (PHP errors, API connection failures, database issues).
- Startup information.
- Access logs (if Heimdall's web server is configured to log them to stdout/stderr, which LinuxServer.io images usually do).
Container Status and Resource Usage:
- docker ps: Shows if the heimdall container is running (Up), its uptime, and port mappings.
- docker stats heimdall: Provides a live stream of resource usage for the heimdall container, including:
  - CPU percentage.
  - Memory usage (amount and percentage).
  - Network I/O.
  - Block I/O (disk). Heimdall is generally very lightweight, so high resource usage might indicate a problem (e.g., a runaway script within Heimdall, or an issue with an enhanced app integration causing excessive polling).
Inspecting the Container: docker inspect heimdall: Gives a wealth of information about the container's configuration, including volume mounts, network settings, environment variables, etc. Useful for verifying your setup.

Monitoring the Host System:

Heimdall's performance is also dependent on the health of the host system it runs on.

Standard Linux Monitoring Tools:
- top or htop: Interactive process viewers showing CPU usage, memory usage, load average, running processes. htop is more user-friendly.
- df -h: Disk free space. Ensure the partition where Docker stores its volumes (and where your Heimdall config volume resides if it's a bind mount or where Docker itself lives) has enough free space. Running out of disk space is a common cause of service failure.
- free -h: Memory usage (total, used, free, cache/buffers).
- vmstat: Reports virtual memory statistics.
- iostat: Reports CPU statistics and input/output statistics for devices and partitions.
Log Files: Check system logs like /var/log/syslog or use journalctl (on systemd systems) for any Docker daemon errors or general system issues.
```
sudo journalctl -u docker.service # View logs for the Docker service
```

Setting Up External Monitoring for Heimdall:

You can use dedicated uptime monitoring tools to check if your Heimdall instance is accessible and responding correctly. This is especially useful if you expose Heimdall (securely) via a reverse proxy.

Uptime Kuma (Self-Hosted):
- An excellent, easy-to-use, self-hosted monitoring tool.
- You can set up Uptime Kuma (often as another Docker container) to periodically ping your Heimdall URL (e.g., https://heimdall.yourdomain.com).
- It can check for:
  - HTTP(S) status codes (e.g., expect a 200 OK).
  - Keyword presence on the page (e.g., expect the word "Heimdall" or "Applications" to ensure the page loads correctly).
  - Response time.
- Uptime Kuma can send notifications (Email, Telegram, Discord, etc.) if Heimdall becomes unreachable.
External Monitoring Services (e.g., UptimeRobot - free tier available):
- Cloud-based services that can monitor your publicly accessible Heimdall URL.

Routine Maintenance Tasks:

Update Heimdall Regularly: As covered in the Docker installation section:

cd ~/docker/heimdall # Or your Heimdall compose directory
docker-compose pull heimdall # Pulls the latest image for the 'heimdall' service
docker-compose up -d --remove-orphans # Recreates the container with the new image

Check the Heimdall GitHub page or LinuxServer.io announcements for release notes to be aware of significant changes.

Update Docker and Host System: Keep your Docker engine and Docker Compose updated to their latest stable versions. Regularly update your host operating system:
```
# For Ubuntu/Debian
sudo apt update
sudo apt upgrade -y
sudo apt autoremove -y # Removes unused packages
```
Reboot the host system if required by kernel updates.

Prune Unused Docker Resources: Docker can accumulate unused images, containers, volumes, and networks over time, consuming disk space.

docker system prune -a # Prompts for confirmation, removes all unused containers, networks, images (dangling and unreferenced), and optionally build cache.
docker volume prune # Removes all unused (not associated with any container) local volumes. Be careful with this if you have detached volumes you still need.

Schedule this or run it periodically.

Check Heimdall Configuration Backups:
- Verify your automated backups are running successfully (check logs, see if new backup files are created).
- Periodically test restoring a backup to a test environment or (very carefully) to your main instance during a maintenance window to ensure the backups are valid.
Review Heimdall Settings: Occasionally, review your Heimdall setup:
- Are all enhanced apps still working? Any API keys expired?
- Are there broken links?
- Is the organization (tags) still logical for your use?

By implementing these monitoring and maintenance practices, you can ensure your Heimdall dashboard remains a stable, reliable, and performant tool in your self-hosting arsenal.

Workshop Monitoring Heimdall with Docker Stats and Uptime Kuma

This workshop will guide you through two levels of monitoring:

Using docker stats for real-time resource monitoring of the Heimdall container.
Setting up Uptime Kuma (as a separate Docker container) to continuously monitor the accessibility of your Heimdall dashboard.

Prerequisites:

Heimdall running in Docker.
Docker and Docker Compose installed.
If you secured Heimdall with Nginx Proxy Manager and a public domain (from a previous workshop), you'll use that URL for Uptime Kuma. If Heimdall is only local, you'll use its local IP and port.

Part 1: Real-time Monitoring with docker stats

Open Your Terminal:
Connect to the server where your Heimdall Docker container is running.
Run docker stats:
If your Heimdall container is named heimdall (as per our docker-compose.yml examples):
```
docker stats heimdall
```
If you have many containers and only want to see Heimdall, this is perfect. To see all running containers:
```
docker stats
```
Observe the Output:
You'll see a live-updating table similar to this:
```
CONTAINER ID   NAME      CPU %     MEM USAGE / LIMIT   MEM %     NET I/O           BLOCK I/O         PIDS
xxxxxxxxxxxx   heimdall  0.05%     50.5MiB / 1.94GiB   2.50%     1.2MB / 800kB     20MB / 0B         10
```
- CPU %: Percentage of host CPU cores the container is using. Heimdall should be very low when idle (<< 1%).
- MEM USAGE / LIMIT: Memory currently used by the container and the total memory limit available to it (often the host's total memory unless specific limits are set).
- MEM %: Percentage of the memory limit the container is using. Heimdall is typically low (e.g., 50-150MiB).
- NET I/O: Network data sent and received by the container.
- BLOCK I/O: Data read from and written to disk by the container (primarily its config volume).
- PIDS: Number of processes running inside the container.
Interact with Heimdall:
While docker stats is running, open your Heimdall dashboard in a browser and click around, refresh pages, or interact with enhanced apps. Observe if there are any noticeable spikes in CPU or memory usage in the docker stats output. This can help you understand its typical resource footprint.
Exit docker stats:
Press Ctrl+C in the terminal to stop docker stats.

Part 2: Setting up Uptime Kuma for Continuous Monitoring

Create a Directory for Uptime Kuma:

mkdir -p ~/docker/uptimekuma
cd ~/docker/uptimekuma

Create docker-compose.yml for Uptime Kuma:

nano docker-compose.yml

Paste the following:

version: '3.8'

services:
  uptimekuma:
    image: louislam/uptime-kuma:1
    container_name: uptimekuma
    volumes:
      - ./kuma_data:/app/data # Persists Uptime Kuma data
    ports:
      - "3001:3001" # Map host port 3001 to container port 3001 for Uptime Kuma UI
    restart: unless-stopped

This uses a bind mount ./kuma_data to store Uptime Kuma's data within your ~/docker/uptimekuma directory.
It exposes Uptime Kuma on port 3001 of your host. Change the host port (left side of 3001:3001) if 3001 is already in use.

Start Uptime Kuma:
```
docker-compose up -d
```
Access Uptime Kuma Setup:
Open your web browser and navigate to http://<your-server-ip>:3001.
- You'll be guided through a quick setup process to create an admin user account for Uptime Kuma. Follow the on-screen instructions.
Add Heimdall as a Monitor in Uptime Kuma:
- Once logged into Uptime Kuma, click the "+ Add New Monitor" button.
- Monitor Type: Select HTTP(s).
- Friendly Name: Enter a descriptive name, e.g., Heimdall Dashboard.
- URL: Enter the URL for your Heimdall instance:
  - If you set up Heimdall with Nginx Proxy Manager and a public domain: https://heimdall.yourdomain.com
  - If Heimdall is local only: http://<heimdall-host-ip>:<heimdall-port> (e.g., http://192.168.1.100:8080)
- Heartbeat Interval: How often Uptime Kuma checks (e.g., default 60 seconds).
- Advanced Options (Optional but Recommended):
  - Accepted Status Codes: By default, it's 200-299. This is usually fine.
  - Keyword: You can add a keyword that Uptime Kuma should find on the Heimdall page to confirm it's loading correctly. For example, inspect your Heimdall page and find a unique word like "Applications" or "Settings" that indicates a successful load.
    - Keyword Type: Plain Text or Regex.
    - Keyword: Enter the word (e.g., Applications).
  - Ignore TLS/SSL error for HTTPS websites (Local only): If your Heimdall is local and uses HTTPS with a self-signed certificate (not recommended, but if you do), you might need to enable this. For publicly trusted Let's Encrypt certs, leave this OFF.
- Setup Notification (Optional): If you want alerts, click "Setup Notification," select your preferred method (e.g., Email, Telegram), and configure it. This might require setting up SMTP for email, etc. You can do this later too.
- Click Save.
Observe Monitoring in Uptime Kuma:
- You'll be taken back to the Uptime Kuma dashboard. Your new "Heimdall Dashboard" monitor will appear.
- Initially, it might show "Pending" or "Unknown." After a short while (up to your heartbeat interval), it should turn Green ("Up") if Heimdall is accessible.
- You can click on the monitor name to see more details, including response time history, uptime percentage, and event logs.
Test a "Down" Scenario (Optional):
- Temporarily stop your Heimdall container:
```
cd ~/docker/heimdall # Or your Heimdall compose directory
docker-compose stop heimdall
```
- Wait for Uptime Kuma's next check (or force a check if the option is there). The monitor in Uptime Kuma should turn Red ("Down"). If you configured notifications, you should receive one.
- Restart Heimdall:
```
docker-compose start heimdall
```
- The monitor in Uptime Kuma should eventually return to Green.

Outcome:

You've learned how to use docker stats to get a quick, real-time overview of your Heimdall container's resource consumption.
You've successfully deployed Uptime Kuma and configured it to continuously monitor your Heimdall dashboard's availability, providing a more robust way to ensure it's up and running. This setup can be expanded to monitor all your other self-hosted services.

Exploring Heimdall Alternatives and Complements

While Heimdall is an excellent application dashboard, the world of self-hosted dashboards is diverse. Understanding alternatives and how they compare can help you ensure Heimdall is the right fit for your needs, or inspire you to use complementary tools.

Popular Heimdall Alternatives:

Each of these has a slightly different focus, feature set, and aesthetic.

Homer Dashboard:
- Focus: Simplicity, YAML configuration, lightweight.
- Description: Homer is configured entirely via a single YAML file (config.yml). This makes it very easy to manage with version control (like Git) and to deploy. It offers basic service discovery with some services (like Docker) and can display status indicators. It's generally very fast and has a clean, modern look.
- Pros: Extremely simple configuration, very lightweight, good for text-based config lovers, supports basic status pings and some service integrations.
- Cons: Less feature-rich in terms of "enhanced apps" with detailed info compared to Heimdall. UI customization is primarily through themes and custom CSS in the YAML. No built-in UI for editing dashboard items.
- When to choose over Heimdall: If you prefer config-as-code (YAML), want something extremely lightweight, and don't need as many deep integrations for live data on tiles.
Dashy:
- Focus: Extreme customization, widgets, status checking, themes.
- Description: Dashy is a highly configurable dashboard with a focus on widgets that can display a wide variety of information. It supports numerous integrations, status checking, theming (with a UI theme editor), and multiple page layouts. Configuration is primarily via a YAML file, but it has a UI for some configurations too.
- Pros: Very powerful customization options, many widgets, built-in status checking, theming capabilities, supports multiple pages.
- Cons: Can be more resource-intensive than Heimdall or Homer. The sheer number of options can be overwhelming for some.
- When to choose over Heimdall: If you want a dashboard with many interactive widgets, live status updates for most services, and a high degree of visual customization through its UI and config.
Organizr:
- Focus: Full-fledged homepage/portal with tabs, iFrames, and user management.
- Description: Organizr aims to be more than just a launcher; it's a complete "homepage" for your server. It uses tabs to embed entire web pages (your services) within its interface using iFrames. It supports user accounts, theming, and many integrations.
- Pros: True "single pane of glass" by embedding services, user management, extensive customization, active development.
- Cons: Can be heavier due to iFrames. Some services don't work well in iFrames (due to X-Frame-Options or CSP). Can feel more complex to set up than simpler dashboards.
- When to choose over Heimdall: If you want to embed your services directly into your dashboard interface and need user management for accessing the dashboard itself.
Flame:
- Focus: Simplicity, beautiful UI, Docker integration, bookmarking.
- Description: Flame is a newer dashboard with a very polished and aesthetically pleasing UI. It's designed to be simple to set up and use. It can integrate with Docker to automatically discover and add applications. It also has a strong focus on bookmark management.
- Pros: Beautiful modern UI, easy setup, Docker integration for auto-discovery, good bookmarking features.
- Cons: May have fewer "enhanced app" type integrations than Heimdall or Dashy as its focus is more on launching and bookmarking.
- When to choose over Heimdall: If your priority is a visually stunning, simple launcher with good Docker integration and bookmarking, and you don't need as many live data tiles.

When to Choose Heimdall:

Heimdall strikes a good balance:

Ease of Use: Its web UI for adding and managing apps is generally intuitive.
Enhanced Apps: It has a good selection of integrations that display useful information directly on the tiles (e.g., for media download clients, Plex, Pi-hole).
Customization: Offers decent customization (backgrounds, custom CSS, tile colors) without being overwhelming.
Lightweight Enough: While not as minimal as Homer, it's generally not very resource-intensive.

Choose Heimdall if you appreciate a GUI-driven setup, want those specific enhanced app integrations, and prefer a tile-based visual layout.

Using Multiple Dashboards for Different Purposes:

You don't have to choose just one! It's perfectly valid to use multiple dashboards if they serve different needs:

Heimdall or Homer: For your primary, quick-access application links.
Dashy: Perhaps for a more detailed status overview page with many widgets.
Organizr: If you want an embedded experience for certain users or services.
Specialized Dashboards:
- Grafana: For detailed metrics and performance monitoring of your servers and applications.
- Uptime Kuma: For uptime monitoring and status pages. You can then link to these specialized dashboards from your primary launcher like Heimdall.

Complements to Heimdall:

Instead of replacing Heimdall, consider tools that complement it:

Reverse Proxy (Nginx Proxy Manager, Traefik): Essential for securing Heimdall with HTTPS and authentication, and providing clean URLs.
Uptime Kuma: For monitoring Heimdall and the services it links to.
A Password Manager (e.g., Bitwarden/Vaultwarden): To securely store credentials for the services Heimdall links to, and for Heimdall itself if you password-protect its settings or use a reverse proxy with auth.
Backup Solution: For backing up Heimdall's configuration and your entire server.

The goal is to build a self-hosted ecosystem that is functional, secure, and easy for you to manage. Heimdall can be a central piece of this, but it doesn't have to be the only piece.

Workshop Setting up a Simple Homer Dashboard for Comparison

This workshop will guide you through setting up a basic Homer dashboard. This will allow you to directly compare its configuration style and feel with Heimdall, helping you understand the different philosophies.

Objective:
To deploy a simple Homer dashboard using Docker and configure a few application links via its YAML configuration.

Prerequisites:

Docker and Docker Compose installed.
A text editor.

Steps:

Create a Directory for Homer:

mkdir -p ~/docker/homer
cd ~/docker/homer

Create Initial Homer Configuration Directory and File:
Homer reads its configuration from a config.yml file located in a directory that will be mounted into the container. Let's create this directory and an initial basic file.

mkdir -p assets/ # Homer looks for config.yml inside an 'assets' subdirectory by default
nano assets/config.yml

Paste the following minimal configuration into assets/config.yml:

# Homer configuration file
# See https://github.com/bastienwirtz/homer/blob/main/docs/configuration.md for reference

title: "My Homer Dashboard"
subtitle: "Quick Access Links"
#logo: "assets/logo.png" # You can add a logo file in the assets folder

# Optional: Different columns for different screen sizes
# columns:
#   lg: 4 # Large screens (desktop)
#   md: 3 # Medium screens (tablet)
#   sm: 2 # Small screens (mobile)

# Header
header: true # Show header

# Connectivity Check
connectivityCheck: true # Enables a check to see if services are reachable (adds a small dot)

# Services (application links)
# Each service group is an object in the services array
services:
  - name: "Productivity" # Name of the group
    icon: "fas fa-briefcase" # Font Awesome icon for the group
    items:
      - name: "My University"
        logo: "assets/icons/university.png" # Path to an icon in assets/icons/
        subtitle: "University Portal"
        tag: "education"
        url: "https://www.example-uni.com"
        target: "_blank" # Open in new tab

      - name: "Search Engine"
        icon: "fab fa-searchengin" # Using Font Awesome icon directly
        subtitle: "DuckDuckGo"
        url: "https://duckduckgo.com"
        target: "_blank"

  - name: "Self-Hosted"
    icon: "fas fa-server"
    items:
      - name: "Heimdall" # Let's link back to our Heimdall!
        # You'd put an icon file here or use a Font Awesome icon
        # logo: "assets/icons/heimdall.png"
        icon: "fas fa-th-large"
        subtitle: "Main Dashboard"
        url: "http://<your-heimdall-ip-or-domain>:<port>" # CHANGE THIS
        target: "_blank"

      - name: "Pi-hole"
        # logo: "assets/icons/pihole.png"
        icon: "fas fa-shield-alt"
        subtitle: "Network Ad Blocker"
        url: "http://<your-pihole-ip>/admin/" # CHANGE THIS
        target: "_blank"
        # type: "PiHole" # For Pi-hole status integration (requires API token in config)
        # For Pi-hole integration, you'd also need to add under 'connectivityCheck':
        # pihole: { url: "http://<your-pihole-ip>", apiKey: "YOUR_PIHOLE_API_KEY" } in the main config.yml
        # This is more advanced, so we're keeping it simple for now.

Important:
- Replace http://<your-heimdall-ip-or-domain>:<port> with the actual URL of your Heimdall instance.
- Replace http://<your-pihole-ip>/admin/ with your Pi-hole URL if you have one, or change the item to another service.
- For custom logos (logo: "assets/icons/university.png"), you would need to create an assets/icons directory and place university.png inside it. For simplicity, you can remove the logo: lines and just use icon: with Font Awesome classes.

Save and close assets/config.yml.

Create docker-compose.yml for Homer:
In the ~/docker/homer directory (not assets), create docker-compose.yml:
Paste the following:
```
ser                
```
href="#__codelineno-87-1">nano docker-compose.yml href="#__codelineno-88-1">version: "3.8" vices: homer: image: b4bz/homer:latest container_name: homer # We map the 'assets' directory on the host to '/www/assets' in the container # Homer expects its config.yml and custom assets (icons, logo) to be in this 'assets' folder. volumes: - ./assets/:/www/assets/ ports: - "8088:8080" # Map host port 8088 to container port 8080. Change 8088 if it's in use. restart: unless-stopped # Optional: Set PUID/PGID if you have permission issues with the assets volume # environment: # - PUID=1000 # - PGID=1000 # - TZ=Etc/UTC
- The key part is volumes: - ./assets/:/www/assets/. This makes your local assets directory (containing config.yml and any custom icons/logos) available inside the Homer container where it expects them.
- We're mapping Homer to host port 8088.
Start Homer:
```
docker-compose up -d
```
Access Homer Dashboard:
Open your browser and navigate to http://<your-server-ip>:8088.
- You should see your Homer dashboard with the title, subtitle, and the service groups and items you defined in config.yml.
Make a Change and See it Update:
- Open ~/docker/homer/assets/config.yml in your text editor again.
- Add a new item or change a name. For example, add a new item under the "Productivity" group:
```
# ... inside services: - name: "Productivity" ... items:
  - name: "Code Repository"
    icon: "fab fa-github"
    subtitle: "GitHub"
    url: "https://github.com"
    target: "_blank"
```
- Save the config.yml file.
- Refresh the Homer dashboard page in your browser. You should see the changes immediately (Homer usually hot-reloads the config). If not, you might need to restart the Homer container: docker-compose restart homer.
Compare with Heimdall:
- Configuration: Notice how Homer is configured entirely by editing the config.yml text file, versus Heimdall's web UI for adding/editing apps.
- Appearance: Observe Homer's default look and feel.
- Features: Homer's "enhanced" features (like the Pi-hole integration, if you were to enable it) are also configured in the YAML.

Outcome:
You have now set up a basic Homer dashboard and experienced its YAML-based configuration. This provides a clear contrast to Heimdall's UI-driven approach. You can now better appreciate the different philosophies and decide which style (or a combination) suits you best. You can stop/remove the Homer container if you don't intend to keep it: cd ~/docker/homer && docker-compose down.

Contributing to the Heimdall Project

Heimdall is an open-source project, and like most such projects, it thrives on community contributions. If you find Heimdall useful and have ideas for improvement, or if you encounter bugs, contributing back can be a rewarding experience. Contributions can range from simple bug reports to suggesting new features, improving documentation, or even writing code.

Understanding the Heimdall Codebase (Brief Overview):

Primary Language: Heimdall is primarily a PHP application. It uses the Laravel framework (a popular PHP framework) for its backend logic, routing, and structure.
Frontend: The frontend uses HTML, CSS (often with a CSS framework like Bootstrap or Tailwind CSS, depending on the version/theme), and JavaScript (potentially with a framework like Vue.js or jQuery for interactivity).
Database: SQLite is typically used by default for storing application data, tags, and settings.
Source Code Repository: The official Heimdall source code is usually hosted on GitHub. The most active fork/version is often maintained by LinuxServer.io or associated developers.
- LinuxServer.io fork: https://github.com/linuxserver/Heimdall (This is a common one, but always check for the most current official or community-preferred repository).

Ways to Contribute:

Reporting Bugs:
- Reproduce the Bug: Before reporting, try to reliably reproduce the issue. Note down the steps.
- Check for Existing Reports: Search the project's GitHub "Issues" section to see if the bug has already been reported. If it has, you can add a "thumbs up" reaction or provide additional information if your scenario is different.
- Create a New Issue: If it's a new bug:
  - Go to the GitHub repository's "Issues" tab and click "New Issue."
  - Use a clear and descriptive title.
  - Provide a detailed description of the bug:
    - What you expected to happen.
    - What actually happened.
    - Steps to reproduce the bug.
    - Your Heimdall version (often found in settings or from the Docker image tag).
    - Your browser version and operating system.
    - Any relevant logs from Heimdall (docker logs heimdall) or browser console errors.
  - Be polite and provide as much information as possible.
Suggesting Features (Enhancement Requests):
- Check for Existing Requests: Similar to bugs, search existing issues to see if your idea has already been suggested.
- Create a New Issue:
  - Clearly describe the feature you're proposing.
  - Explain the problem it solves or the benefit it provides (the "why").
  - If possible, suggest how it might be implemented or how it would look/work from a user's perspective.
  - Label it as an "enhancement" or "feature request" if the repository uses labels.
Improving Documentation:
- If you find parts of the documentation (e.g., README, setup guides, Wiki) unclear, outdated, or missing, you can suggest improvements.
- You can do this by creating an issue, or if you're comfortable with Markdown and Git, you can fork the repository, make the changes to the documentation files, and submit a "Pull Request."
Providing Support to Other Users:
- If you see questions on forums (like Reddit r/selfhosted, r/Heimdall), Discord servers, or GitHub issues that you know the answer to, helping other users is a valuable contribution.
Developing New Enhanced Applications:
- If Heimdall doesn't support an enhanced integration for a service you use, and you have PHP/Laravel development skills, you could try to develop a new enhanced app module. This typically involves:
  - Understanding how existing enhanced apps are structured in Heimdall.
  - Learning the API of the target service.
  - Writing PHP code to fetch data from the API and format it for display on the Heimdall tile.
  - This is a more advanced contribution.
Submitting Code (Pull Requests):
- This is for developers who want to fix bugs or implement features by writing code.
- Process:
  1. Fork the Repository: Create your own copy of the Heimdall repository on GitHub.
  2. Clone Your Fork: Download your forked repository to your local machine (git clone ...).
  3. Create a New Branch: Create a dedicated branch for your changes (git checkout -b my-new-feature).
  4. Make Your Code Changes: Implement the fix or feature. Test thoroughly.
  5. Commit Your Changes: git commit -am "Add some feature" (use a clear commit message).
  6. Push to Your Fork: git push origin my-new-feature.
  7. Create a Pull Request (PR): Go to your forked repository on GitHub. You'll see a prompt to create a PR from your new branch to the original Heimdall repository's main or develop branch.
  8. Fill out the PR template, explaining your changes clearly.
- Coding Standards: Follow any coding style guidelines or contribution guidelines provided by the project.
- Discussion: Be prepared for feedback and discussion on your PR from the project maintainers. They might request changes before merging.

Getting Started with Development (If you're a developer):

Set up a local development environment for Heimdall (often involving cloning the repo, installing PHP, Composer, Node.js/npm for frontend assets, and setting up a web server). The project's README or a CONTRIBUTING.md file might have instructions.
Start with small, well-defined issues (often labeled "good first issue" or "help wanted" on GitHub).

Contributing to open source is a great way to learn, improve your skills, and give back to projects you value. Even non-code contributions are highly appreciated.

Workshop Identifying a UI Suggestion and Reporting it Effectively

This workshop focuses on a non-code contribution: identifying a potential User Interface (UI) or User Experience (UX) improvement in Heimdall and drafting a well-structured feature suggestion for GitHub.

Objective: To practice the process of observing software critically, formulating a constructive suggestion, and preparing it for submission as a GitHub issue.

Prerequisites:

A running Heimdall instance to explore.
A GitHub account (free to create at https://github.com/).
Access to the Heimdall GitHub repository (e.g., https://github.com/linuxserver/Heimdall - check for the most current official/active one).

Steps:

Explore Your Heimdall Instance Critically:
- Use your Heimdall dashboard as you normally would, but pay close attention to the UI and your interactions.
- Think about:
  - Are there any tasks that feel awkward or take too many clicks?
  - Is any information hard to find or unclear?
  - Could any visual element be improved for clarity or aesthetics?
  - Is there a small feature missing that would significantly improve usability for a common task?
- Example Scenario: Let's imagine while adding tags to applications, you find it slightly tedious that you can't easily see a list of all existing tags directly in the "Add/Edit App" form, or perhaps you wish you could reorder pinned items via drag-and-drop.
Choose One Specific Suggestion:
- From your observations, pick one specific, actionable UI/UX suggestion. It's better to have a focused suggestion than a vague or overly broad one.
- Our Example Suggestion: "Allow reordering of pinned application tiles via drag-and-drop on the main dashboard."
Check if the Suggestion Already Exists:
- Go to the Heimdall GitHub repository's "Issues" tab.
- Use the search bar within the issues (e.g., search for "drag and drop pinned," "reorder pinned," "sort pinned items").
- Filter by "label:enhancement" or "label:feature-request" if these labels are used.
- If you find a similar existing issue:
  - Read it. If it matches your idea, you can add a 👍 reaction to show support.
  - If your idea is slightly different or adds a new perspective, you could comment on the existing issue (constructively!).
- If you don't find an existing issue, proceed to the next step.
Draft Your Feature Suggestion (in a text editor first): Structure your suggestion clearly. A good feature request often includes:
- Title: Clear, concise, and descriptive.
  - Example Title: [Feature Suggestion] Enable Drag-and-Drop Reordering for Pinned Applications
- Is your feature request related to a problem? Please describe. A clear and concise description of what the problem is.
  - Example: "Currently, pinned applications are displayed in the order they were pinned (or perhaps alphabetically/by ID). If a user wants to change the display order of their pinned items for better workflow or visual preference, they have to unpin and re-pin items in the desired sequence, which is cumbersome, especially with many pinned items."
- Describe the solution you'd like. A clear and concise description of what you want to happen.
  - Example: "I would like to be able to reorder my pinned application tiles directly on the dashboard using a drag-and-drop interface. The user should be able to click and hold on a pinned tile, drag it to a new position among the other pinned tiles, and release it to save the new order. This new order should persist."
- Describe alternatives you've considered (optional but good). A clear and concise description of any alternative solutions or features you've considered.
  - Example: "An alternative could be adding 'move up'/'move down' buttons in the edit screen for each pinned application, but drag-and-drop is more intuitive for direct visual reordering on the dashboard itself. Another alternative is manual sort-order numbers in settings, but that's less user-friendly."
- Additional context (optional). Add any other context or screenshots (mockups are great if you can make them) about the feature request here.
  - Example: "This feature would improve the personalization and usability of the pinned items section, making it easier for users to organize their most important links exactly how they prefer. Many other dashboard applications offer similar drag-and-drop functionality for item reordering."
  - (If you were actually submitting, you could create a simple mockup image showing arrows or a "dragging" state).
Review Your Draft:
- Is it clear and easy to understand?
- Is it polite and constructive?
- Have you provided enough detail?
- Have you explained the "why" (the benefit)?
(Simulated) Submitting the Issue on GitHub:
- Go to the Heimdall GitHub repository's "Issues" tab.
- Click "New Issue."
- If there are issue templates (e.g., "Bug report," "Feature request"), choose the "Feature request" template.
- Copy and paste your drafted title and description into the appropriate fields on GitHub.
- Add relevant labels if you can (e.g., "enhancement," "ui," "ux").
- Click "Submit new issue."
(For this workshop, you don't have to actually submit it unless you have a real, well-thought-out suggestion for the current Heimdall project and have checked it doesn't exist. The goal here is to practice the formulation process.)

Outcome:
You have now walked through the process of identifying a potential UI improvement and structuring it into a clear, well-reasoned feature suggestion suitable for submission to an open-source project like Heimdall. This practice helps in contributing effectively even without writing code, as good feedback and well-articulated suggestions are invaluable to developers.

Troubleshooting Common Issues

Even with careful setup, you might encounter issues with your Heimdall instance. This section covers some common problems and how to diagnose and resolve them. The primary tool for troubleshooting Dockerized applications like Heimdall is checking container logs.

1. Container Not Starting or Continuously Restarting:

Symptom:
- docker ps shows the Heimdall container is not listed, or it's listed with a status like Restarting (x seconds ago) or Exited (x) x seconds ago.
- You cannot access the Heimdall web UI.
Diagnosis & Solution:
- Check Docker Logs: This is the most important step.
```
docker logs heimdall
```
  Look for error messages at the end of the log output. Common causes:
  - Port Conflicts: If the host port Heimdall is trying to use (e.g., 8080 or 8443 from your docker-compose.yml) is already in use by another application on your host.
    - Log Message Example: Error starting userland proxy: listen tcp4 0.0.0.0:8080: bind: address already in use.
    - Solution: Stop the other application using that port, or change the host port mapping in your Heimdall docker-compose.yml (e.g., change "8080:80" to "8081:80") and run docker-compose up -d again.
  - Volume/Bind Mount Path Issues:
    - If using a bind mount, the host path specified in docker-compose.yml might not exist or Docker might not have permission to access it.
    - Log Message Example: Errors related to "permission denied" when trying to access /config, or PHP errors indicating it cannot write to a file/directory.
    - Solution: Ensure the host path for your bind mount exists. Check permissions of the host directory; it should be writable by the PUID/PGID you configured for the Heimdall container. For named volumes, this is less common unless there's a Docker daemon issue.
  - Incorrect PUID/PGID: Especially with bind mounts, if the PUID/PGID set in docker-compose.yml doesn't have write permissions to the host directory mapped to /config, Heimdall might fail to start or operate correctly.
    - Solution: Verify PUID and PGID (id -u, id -g for your user). Ensure the host directory is owned by this user/group or has appropriate permissions.
  - Corrupted Configuration / Database: In rare cases, Heimdall's SQLite database or other config files might become corrupted, preventing startup.
    - Log Message Example: SQLite errors, PHP errors related to database connection or queries.
    - Solution: Try restoring from a backup. If no backup, you might have to remove/rename the config volume/directory (losing all settings) and let Heimdall recreate it fresh.
  - Base Image Issues / Invalid Entrypoint: If the Docker image itself is faulty or there's an issue with its startup scripts. This is rare with official LinuxServer.io images but possible.
    - Solution: Try pulling the image again (docker pull linuxserver/heimdall:latest) or try an older specific version tag.
- Check docker-compose.yml for Typos: Ensure your YAML syntax is correct. Indentation is critical. A misplaced space can break it. Run docker-compose config to validate your compose file.
```
cd ~/docker/heimdall # Or your Heimdall compose directory
docker-compose config
```
  This will report syntax errors.
- Insufficient System Resources: If your host is very low on RAM or disk space, Docker might struggle to start containers. Check df -h and free -m.

2. Unable to Access Web UI (Container is Running):

Symptom:
- docker ps shows Heimdall is Up and running.
- When you try to access http://<your-ip>:<port> in your browser, you get "Connection refused," "Site can't be reached," or a timeout.
Diagnosis & Solution:
- Verify IP Address and Port: Double-check you're using the correct IP address of the Docker host and the correct host port that you mapped in docker-compose.yml (e.g., 8080 if you have ports: - "8080:80").
- Host Firewall: The firewall on your Docker host might be blocking incoming connections on the port Heimdall is using.
  - Linux (ufw): sudo ufw status. If active, you might need to allow the port: sudo ufw allow 8080/tcp (replace 8080 with your port).
  - Linux (firewalld): sudo firewall-cmd --list-all. If active, add port: sudo firewall-cmd --permanent --add-port=8080/tcp && sudo firewall-cmd --reload.
  - Windows Firewall: Check its rules.
- Network Configuration:
  - Ensure your client device (where you're opening the browser) is on the same network as the Docker host, or that there's proper routing between them.
  - If using a reverse proxy (like Nginx Proxy Manager), ensure the proxy is configured correctly to forward to Heimdall's internal IP and port, and that the proxy itself is accessible. Troubleshoot the proxy first.
- Check Heimdall Logs (docker logs heimdall): Even if the container is "Up," the application inside might have encountered an error that prevents it from serving web pages. Look for PHP errors or web server (Nginx/Apache often used within the container) errors.
- Try curl from the Host: Test connectivity locally on the Docker host itself.
```
curl http://localhost:<your_heimdall_host_port>
# Example: curl http://localhost:8080
```
  If this works but access from another machine doesn't, it's almost certainly a firewall or network issue between the host and the client. If localhost doesn't work, the issue is likely with Heimdall itself or its port mapping in Docker.

3. Application Links Not Working / Enhanced Apps Not Showing Data:

Symptom:
- Clicking a tile on Heimdall leads to an error page, or an enhanced app tile shows an error/no data.
Diagnosis & Solution:
- For Generic Links:
  - Verify URL in Heimdall Settings: Edit the application in Heimdall. Is the URL correct? Typos are common.
  - Test URL Directly: Copy the URL from Heimdall and paste it directly into your browser's address bar. Does it work there? If not, the service itself is down or the URL is wrong.
- For Enhanced Applications:
  - Verify URL in Heimdall Settings: Ensure it's the correct base URL for the service (e.g., http://sonarr-ip:8989).
  - Verify API Key: Double-check the API key is correct and hasn't expired or been revoked in the target application's settings.
  - Network Connectivity from Heimdall Container to Service: The Heimdall container needs to be able to reach the service's URL.
    - If both Heimdall and the service are Docker containers on the same host:
      - Are they on the same custom Docker network? If so, you can often use the service's container name as the hostname in the URL (e.g., http://sonarr:8989).
      - If not, use the host's IP and the service's mapped port.
    - Test connectivity from within the Heimdall container:
      docker exec -it heimdall /bin/bash # Or /bin/sh if bash isn't there # Once inside the container shell: apk add curl # If curl is not installed (for Alpine-based images) curl -v http://<service_ip_or_hostname>:<service_port> exit
      A Connection refused or No route to host here means the Heimdall container cannot reach the service. This could be due to Docker networking misconfiguration or a firewall blocking the container.
  - Check Heimdall Logs (docker logs heimdall): Look for specific error messages related to the enhanced app (e.g., "Failed to connect to Sonarr API," "Invalid API key for Radarr").
  - SSL/TLS Issues: If the target service uses HTTPS with a self-signed certificate, Heimdall's underlying cURL/PHP might refuse to connect due to certificate validation errors.
    - Heimdall might have an option per-app to "ignore SSL errors" (use with caution).
    - The best solution is to use properly signed certificates for all your services, often via a reverse proxy with Let's Encrypt.
  - API Rate Limiting: Some services might rate-limit API requests. If Heimdall polls too frequently, it could be temporarily blocked.

4. Permissions Issues with Config Volume (Bind Mounts):

Symptom:
- Heimdall starts, but settings are not saved, or it complains about not being able to write to its configuration.
- Uploaded images/icons don't appear or cause errors.
- Logs might show "Permission denied" errors related to /config.
Diagnosis & Solution:
- This usually occurs when using bind mounts and the PUID/PGID of the Heimdall container process do not match the ownership/permissions of the host directory mapped to /config.
- Verify PUID/PGID:
  - In your docker-compose.yml, check the PUID and PGID environment variables.
  - On your host, find out which user and group these IDs correspond to.
- Check Host Directory Permissions:
```
ls -ld /path/to/your/host/heimdall/config # The directory itself
ls -l /path/to/your/host/heimdall/config # Contents of the directory
```
  The owner and group should match the PUID/PGID, or the directory needs to be writable by that PUID/PGID (e.g., group write permissions if the PGID matches the directory's group).
- Fix Permissions:
```
# Change ownership (replace 1000:1000 with your PUID:PGID)
sudo chown -R 1000:1000 /path/to/your/host/heimdall/config
# Or, ensure appropriate chmod permissions (less ideal than correct ownership)
# sudo chmod -R u+rwX,g+rwX /path/to/your/host/heimdall/config
```
- Restart the Heimdall container after adjusting permissions: docker-compose restart heimdall.

5. Custom CSS Not Applying or Behaving Unexpectedly:

Symptom:
- CSS rules added in Heimdall's "Custom CSS" setting don't take effect or don't look as expected.
Diagnosis & Solution:
- Browser Cache: Do a hard refresh (Ctrl+Shift+R or Cmd+Shift+R) in your browser to ensure you're not seeing a cached version.
- CSS Specificity: Your custom CSS rules might be overridden by more specific default Heimdall styles.
  - Use your browser's Developer Tools ("Inspect Element") to select the element you're trying to style. Look at the "Styles" panel to see which rules are being applied and if yours is crossed out or not present.
  - Make your selectors more specific (e.g., instead of .title, try body .app .title).
  - As a last resort, use !important on your CSS property (e.g., color: red !important;), but try to avoid this if possible as it makes CSS harder to maintain.
- Selector Typos/Errors: Double-check your CSS selectors for typos or incorrect class/ID names. Verify against the actual HTML structure using the Inspector.
- Syntax Errors in CSS: A missing semicolon or curly brace can break your custom CSS.
- Heimdall Version Changes: CSS class names and HTML structure can change between Heimdall versions, breaking your custom CSS. You may need to re-inspect and update your selectors after an update.

By systematically checking logs, configurations, and using browser developer tools, most common Heimdall issues can be resolved.

Workshop Debugging a Non-Functional Application Link

This workshop will simulate a common scenario: an application link on your Heimdall dashboard is not working as expected. We'll go through the steps to diagnose and fix it.

Scenario: You've added a new "AwesomeApp" to Heimdall. The tile appears, but when you click it, you get a "This site can’t be reached" error, or it goes to the wrong page.

Objective: To practice the diagnostic steps to identify why a Heimdall application link is failing and how to correct it.

Prerequisites:

Your Heimdall instance running.
For this workshop, we'll intentionally create a broken link.

Steps:

Create an Intentionally Broken Link in Heimdall:
- Go to your Heimdall dashboard and open the settings to add/edit applications.
- Click "Add" to create a new application.
- Application Name: Broken Test App
- Application Type: Generic
- URL: Enter a deliberately incorrect or non-existent URL. Examples:
  - http://thissitedoesnotexist12345.com (likely non-existent)
  - http://192.168.1.254:12345 (an IP and port unlikely to be listening on your network)
  - htttps://google.com (typo in protocol: htttps instead of https - some browsers might auto-correct, try to make it less obvious)
- Icon/Colour: Choose anything.
- Click Save.
Attempt to Use the Broken Link:
- Go back to your Heimdall dashboard.
- Find the "Broken Test App" tile and click it.
- Observe the error: Your browser will likely show an error page (e.g., "This site can’t be reached," "DNS_PROBE_FINISHED_NXDOMAIN," "Connection refused"). Note the error message.
Begin Diagnosis - Step 1: Verify URL in Heimdall Settings:
- In Heimdall, go back to edit the "Broken Test App."
- Carefully examine the URL field.
  - Is there a typo in the domain name (e.g., gogle.com instead of google.com)?
  - Is there a typo in the protocol (e.g., htp:// instead of http://)? (Our example htttps:// if not auto-corrected by browser).
  - Is the port number correct (if applicable)?
  - Is there any extraneous whitespace?
- Correction (if an obvious typo is found): If you spot a typo (like our htttps://), correct it (e.g., to https://google.com). Save, and try the link again from the dashboard. If it now works, your problem was a simple typo in the Heimdall configuration.
- For our workshop, let's assume our broken URL was http://192.168.1.254:12345 and we see no obvious typo.
Diagnosis - Step 2: Test URL Directly in Browser:
- Copy the exact URL from the Heimdall settings for "Broken Test App" (http://192.168.1.254:12345).
- Paste this URL directly into a new browser tab's address bar and press Enter.
- Observation: You should get the same error as when clicking the Heimdall tile.
- Interpretation:
  - If it fails here too (as expected for our workshop scenario), the problem is not with Heimdall itself redirecting you, but with the URL being unreachable or the service at that URL being down/misconfigured.
  - If it worked here but failed when clicking the Heimdall tile, that would be very unusual and might point to a strange Heimdall bug, a browser extension interfering, or a subtle difference in the URL being processed by Heimdall (less likely for generic links).
Diagnosis - Step 3: Check Network Connectivity (if URL is local):
- Our example URL http://192.168.1.254:12345 points to a local IP address.
- Ping the Host (IP Address part): Open a terminal or command prompt on your computer (the one you're using to browse Heimdall).
```
ping 192.168.1.254
```
  - Observation:
    - If you get replies: The host machine at 192.168.1.254 is online and reachable on the network. The problem is likely that no service is listening on port 12345 on that host, or a firewall on that host is blocking the port.
    - If you get "Request timed out," "Destination host unreachable," or similar: The host itself is offline, not reachable from your machine, or a network firewall between you and it is blocking pings (and likely other traffic).
- Check if Service is Listening on the Port (on the target host): If you have access to the machine at 192.168.1.254, you would log into it and use a command like ss -tulnp | grep 12345 (Linux) or netstat -ano | findstr "12345" (Windows) to see if any process is actually listening on that port.
  - For our workshop, we assume nothing is listening.
Diagnosis - Step 4: Firewall Check (Client and Server):
- Client Firewall: Is there a firewall on your local computer blocking outbound connections to port 12345? (Unlikely for common browser traffic but possible in strict environments).
- Server Firewall: If the host 192.168.1.254 was reachable via ping and you believe a service should be on port 12345, a firewall on that server might be blocking incoming connections to that port.
Conclusion for "Broken Test App":
- For http://192.168.1.254:12345, the likely issue is that no service is running on host 192.168.1.254 at port 12345, or the host itself is unreachable.
- For http://thissitedoesnotexist12345.com, the domain doesn't resolve to an IP (DNS error).
- For htttps://google.com, the typo in the protocol.
Fix the Link (for real this time):
- Go back to Heimdall settings and edit "Broken Test App."
- Change the URL to a known working URL, for example, https://www.wikipedia.org.
- Save the changes.
- Go to your dashboard and click the "Broken Test App" tile (which should now be a "Wikipedia" link effectively). It should now work.

Outcome:
You have practiced a systematic approach to troubleshooting a non-functional link in Heimdall. Key takeaways:

Always verify the URL in Heimdall settings first (typos are common).
Test the URL directly in your browser to isolate whether the problem is Heimdall or the target service/URL.
For local services, use network diagnostic tools like ping and check if the service/port is active on the target host.
Consider firewalls on both client and server sides.

This methodical process can be applied to diagnose issues with any link, whether it's a generic application or the base URL for an enhanced app.

Conclusion

Throughout this comprehensive guide, we've journeyed from the fundamental concepts of Heimdall to its advanced configurations, security considerations, and troubleshooting techniques. You've learned not just the "how" but also the "why" behind setting up your personalized application dashboard, equipping you with the knowledge to create an efficient and organized hub for your digital services.

Recap of Key Learnings:

Understanding Heimdall: We started by defining what Heimdall is, why personal dashboards are beneficial, and the advantages of self-hosting, particularly with Docker.
Basic Setup: You mastered installing Heimdall using Docker Compose, focusing on persistent storage and initial configuration, including adding generic and enhanced applications, using tags, and customizing the background.
Intermediate Customization: We delved into advanced application configurations, leveraging enhanced app features, securing your Heimdall instance with a reverse proxy like Nginx Proxy Manager for HTTPS and authentication, and implementing robust backup and restore strategies. You also explored the power of custom CSS to theme your dashboard.
Advanced Integration and Beyond: You explored ways to potentially extend Heimdall's functionality, the importance of monitoring its health and performance, its place among alternative dashboard solutions, and how you can contribute to this open-source project.
Practical Workshops: Each sub-section was complemented by a hands-on workshop, allowing you to apply the theoretical knowledge in practical, real-world scenarios, from sketching your dashboard layout to automating backups and debugging issues.

The Future of Your Self-Hosted Dashboard:

Your Heimdall instance is now more than just a collection of links; it's a testament to your growing skills in self-hosting. As your collection of self-hosted services expands, Heimdall will continue to be an invaluable tool for organization and quick access. Consider these next steps in your journey:

Expand Your Services: Continue to explore and self-host new applications that interest you, adding them to your Heimdall dashboard.
Refine Your Theme: Experiment further with custom CSS to create a truly unique look that reflects your personal style.
Integrate More Enhanced Apps: As you deploy services like Sonarr, Radarr, Plex, or Pi-hole, integrate them as enhanced apps in Heimdall to benefit from live data on your tiles.
Strengthen Security: Regularly review and update your security practices, especially for your reverse proxy and firewall configurations.
Automate More: Look for opportunities to automate maintenance tasks, such as system updates or log rotation, for your Docker host and Heimdall.

Encouragement for Further Exploration:

The world of self-hosting is vast and constantly evolving. The skills you've developed while working with Heimdall—Docker management, basic networking, troubleshooting, and even light scripting or CSS—are foundational and transferable to many other self-hosting projects. Don't be afraid to experiment, break things (in a safe, learning environment!), and rebuild. Each challenge you overcome deepens your understanding and confidence. Explore other dashboard alternatives to see different approaches, or dive into complementary tools like Grafana for monitoring or Authelia/Authentik for advanced SSO. The self-hosting community is vibrant and full of resources; engage with it, ask questions, and share your own experiences.

Thank you for following this guide. We hope it has empowered you to take control of your digital application access with a powerful, personalized Heimdall dashboard and has sparked a lasting interest in the rewarding field of self-hosting. Happy hosting!