Heimdall

Docker container state monitor with notifications for Discord

Get Heimdall

Status badges

Table of Contents

1. About Heimdall
2. Features
3. Usage
   • Docker container
   • Using Docker Desktop
   • Standalone application
   • Using Docker Desktop
4. Technologies
   • Language
   • Deployed to
   • CI/CD
   • Released using
   • Logo created using
5. Screenshots
   • Terminal output
   • Discord notifications
   • Container started
   • Container stopped
   • Container healthy
   • Container unhealthy
   • Container errored
   • Periodic notification
   • Running containers
   • All containers
   • Notifications with a hostname

About Heimdall

Heimdall is a monitoring application for your Docker containers. It sends you notifications through a webhook whenever the state of a container changes. It does this by using the Docker socket to listen for events. Heimdall also provides the option to receive periodic notifications about the state of your containers, where it sends you an overview of every container's status.

Features

• Easy monitoring for Docker containers
• Receive notifications through Discord webhooks
• Receive periodic notifications about the state of your containers
• Status API
• Web UI
• Bugs (hopefully)

Usage

Heimdall can be used in a couple different ways:

1. As a Docker container
2. As a standalone application

Docker container

The easiest way to use Heimdall is by running it as a Docker container. You can do this by running the following command:

docker run -d \
    -v /var/run/docker.sock:/var/run/docker.sock \
    -e HEIMDALL_WEBHOOK_URL=<your-webhook-url> \
    --name heimdall \
    drfractum/heimdall:latest

Using Docker Desktop

In some cases, Docker Desktop puts the Docker socket in a different location than the standard Docker installation. You can change the above command to the following to point to the right location:

docker run -d \
-    -v /var/run/docker.sock:/var/run/docker.sock \
+    -v ~/.docker/desktop/docker.sock:/var/run/docker.sock \
    -e HEIMDALL_WEBHOOK_URL=<your-webhook-url> \
    --name heimdall \
    drfractum/heimdall:latest

Standalone application

You can also run Heimdall as a standalone application. This is useful if you want to run it on a server or your local machine. To run Heimdall as a standalone application, you can download the latest release from the releases page.

Be sure to download the right binary for your operating system.

Platform	Binary
	heimdall_Linux_x86_64
	heimdall_Linux_armv7
	heimdall_Windows_x86_64
	heimdall_Darwin_x86_64

Other binaries are available in case you have a different architecture or operating system.

After downloading the release, you can run it by executing the following command:

./heimdall --webhook-url=<your-webhook-url>

On Windows you can run it by executing the following command:

heimdall.exe --webhook-url=<your-webhook-url>

Using Docker Desktop

In some cases if you're using Docker Desktop, you might run into an error where Heimdall can't connect to the Docker socket. By default, Docker Desktop puts the Docker socket in a different location than the standard Docker installation. If Heimdall doesn't automatically detect your environment and the right location for the Docker socket, you'll need to create a symlink to the docker.sock file. You can do this by running the following command:

sudo ln -s ~/.docker/desktop/docker.sock /var/run/docker.sock

Customisation

Heimdall can be customised by using flags or environment variables. Either works, but flags take precedence over environment variables. Short flags can be used in place of the longer flags to save some typing.

Long flag	Short flag	Environment Variable	Default	Required	Explanation
--periodic-notification	-n	HEIMDALL_PERIODIC_NOTIFICATION	false	No	Enable periodic notifications
--notification-schedule	-s	HEIMDALL_NOTIFICATION_SCHEDULE	@hourly	Only if periodic notifications are enabled and you want a schedule	The schedule for periodic notifications. Supports cron expressions (e.g. 0 9 * * 1), @interval expressions (e.g. @hourly, @montly), and @every expressions (e.g. @every 1h30m10s). Learn more
--all-containers	-a	HEIMDALL_ALL_CONTAINERS	false	Only if periodic notifications are enabled and you want periodic notifications on all containers	Enable periodic notification reporting on all containers, including stopped ones
--retry	-r	HEIMDALL_RETRY	10	No	How long Heimdall should sleep before retrying in case the Docker event stream ends unexpectedly
--provider	-p	HEIMDALL_PROVIDER	discord	No	What notification provider should be used. Possible values: discord
--webhook-url	-w	HEIMDALL_WEBHOOK_URL	-	Yes	What URL Heimdall should use to send notifications to
--hostname	-h	HEIMDALL_HOSTNAME	-	No, but recommended in case you run Heimdall on multiple devices	The name of the host Heimdall is running on. This will cause Heimdall to send status updates with the device name in them: Docker Container Status Update (Hostname)
--debug	-d	HEIMDALL_DEBUG	false	No	Enable extra debug messages
--notification-interval	-i	HEIMDALL_NOTIFICATION_INTERVAL	60	No. This parameter is DEPRECATED. use --notification-schedule instead	How often (in minutes) periodic notifications should be sent

Technologies

Heimdall was created using Go. The CI/CD pipeline is handled by GitHub Actions and the Docker image is hosted on Docker Hub.

The program is mostly based on the Docker SDK for Go

It uses the following technologies:

Language

Deployed to

CI/CD

Released using

Logo created using

Screenshots

Terminal output

Discord notifications

Container started

Container stopped

Container healthy

Container unhealthy

Container errored

Periodic notification

Running containers

All containers

Notifications with a hostname