|
1 | | -## Using Docker Desktop |
2 | | -Run this command to create a symlink to the docker.sock file: |
| 1 | +<div align="center"> |
| 2 | + <a href="https://hermes.fractum.nl"> |
| 3 | + <img src="public/logo.png" alt="Logo" width="80" height="80"> |
| 4 | + </a> |
| 5 | + <h1>Heimdall</h1> |
| 6 | + <p><i>Docker container state monitor with notifications for Discord</i></p> |
| 7 | +</div> |
| 8 | + |
| 9 | +<!-- TOC --> |
| 10 | +<details> |
| 11 | + <summary>Table of Contents</summary> |
| 12 | + <ol> |
| 13 | + <li> |
| 14 | + <a href="#about-heimdall">About Heimdall</a> |
| 15 | + </li> |
| 16 | + <li> |
| 17 | + <a href="#features">Features</a> |
| 18 | + </li> |
| 19 | + <li> |
| 20 | + <a href="#usage">Usage</a> |
| 21 | + <ul> |
| 22 | + <li><a href="#docker-container">Docker container</a></li> |
| 23 | + <ul> |
| 24 | + <li><a href="#using-docker-desktop-1">Using Docker Desktop</a></li> |
| 25 | + </ul> |
| 26 | + <li><a href="#standalone-application">Standalone application</a></li> |
| 27 | + <ul> |
| 28 | + <li><a href="#using-docker-desktop-2">Using Docker Desktop</a></li> |
| 29 | + </ul> |
| 30 | + </ul> |
| 31 | + </li> |
| 32 | + <li> |
| 33 | + <a href="#technologies">Technologies</a> |
| 34 | + <ul> |
| 35 | + <li><a href="#language">Language</a></li> |
| 36 | + <li><a href="#deployed-to">Deployed to</a></li> |
| 37 | + <li><a href="#ci--cd">CI/CD</a></li> |
| 38 | + <li><a href="#released-using">Released using</a></li> |
| 39 | + <li><a href="#logo-created-using">Logo created using</a></li> |
| 40 | + </ul> |
| 41 | + </li> |
| 42 | + <li> |
| 43 | + <a href="#screenshots">Screenshots</a> |
| 44 | + </li> |
| 45 | + </ol> |
| 46 | +</details> |
| 47 | +<!-- TOC --> |
| 48 | + |
| 49 | +## About Heimdall |
| 50 | +Heimdall is a monitoring application for your Docker containers. It sends you notifications through a webhook whenever the state of a container changes. |
| 51 | +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. |
| 52 | + |
| 53 | +## Features |
| 54 | +- [x] Easy monitoring for Docker containers |
| 55 | +- [x] Receive notifications through Discord webhooks |
| 56 | +- [x] Receive periodic notifications about the state of your containers |
| 57 | +- [ ] Status API |
| 58 | +- [ ] Web UI |
| 59 | +- [ ] Bugs (hopefully) |
| 60 | + |
| 61 | +## Usage |
| 62 | +Heimdall can be used in a couple different ways: |
| 63 | +1. As a Docker container |
| 64 | +2. As a standalone application |
| 65 | + |
| 66 | +### Docker container |
| 67 | +The easiest way to use Heimdall is by running it as a Docker container. You can do this by running the following command: |
| 68 | +```bash |
| 69 | +docker run -d \ |
| 70 | + -v /var/run/docker.sock:/var/run/docker.sock \ |
| 71 | + -e HEIMDALL_WEBHOOK_URL=<your-webhook-url> \ |
| 72 | + --name heimdall \ |
| 73 | + drfractum/heimdall:latest |
| 74 | +``` |
| 75 | + |
| 76 | +#### Using Docker Desktop |
| 77 | +In some cases, Docker Desktop puts the Docker socket in a different location than the standard Docker installation. |
| 78 | +You can change the above command to the following to point to the right location: |
| 79 | +```diff |
| 80 | +docker run -d \ |
| 81 | +- -v /var/run/docker.sock:/var/run/docker.sock \ |
| 82 | ++ -v ~/.docker/desktop/docker.sock:/var/run/docker.sock \ |
| 83 | + -e HEIMDALL_WEBHOOK_URL=<your-webhook-url> \ |
| 84 | + --name heimdall \ |
| 85 | + drfractum/heimdall:latest |
| 86 | +``` |
| 87 | + |
| 88 | +### Standalone application |
| 89 | +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. |
| 90 | +To run Heimdall as a standalone application, you can download the latest release from the [releases page](https://github.com/RobinHeidenis/heimdall/releases). |
| 91 | + |
| 92 | +Be sure to download the right binary for your operating system. |
| 93 | + |
| 94 | +| Platform | Binary | |
| 95 | +|----------------------------------------------------------------------------------------------------------|-------------------------| |
| 96 | +|  | heimdall_Linux_x86_64 | |
| 97 | +|  | heimdall_Linux_armv7 | |
| 98 | +|  | heimdall_Windows_x86_64 | |
| 99 | +|  | heimdall_Darwin_x86_64 | |
| 100 | + |
| 101 | +Other binaries are available in case you have a different architecture or operating system. |
| 102 | +Other binaries are available in case you have a different architecture or operating system. |
| 103 | + |
| 104 | + |
| 105 | +After downloading the release, you can run it by executing the following command: |
| 106 | +```bash |
| 107 | +./heimdall --webhook-url=<your-webhook-url> |
| 108 | +``` |
| 109 | + |
| 110 | +On Windows you can run it by executing the following command: |
| 111 | +```bash |
| 112 | +heimdall.exe --webhook-url=<your-webhook-url> |
| 113 | +``` |
| 114 | + |
| 115 | +#### Using Docker Desktop |
| 116 | +In some cases if you're using Docker Desktop, you might run into an error where Heimdall can't connect to the Docker socket. |
| 117 | +By default, Docker Desktop puts the Docker socket in a different location than the standard Docker installation. |
| 118 | +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: |
3 | 119 | ```bash |
4 | 120 | sudo ln -s ~/.docker/desktop/docker.sock /var/run/docker.sock |
5 | | -`` |
| 121 | +``` |
| 122 | + |
| 123 | +## Customisation |
| 124 | +Heimdall can be customised by using the following environment variables: |
| 125 | + |
| 126 | +| Long flag | Short flag | Environment Variable | Default | Required | Explanation | |
| 127 | +|---------------------------|------------|----------------------------------|-----------|--------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------| |
| 128 | +| `--periodic-notification` | `-n` | `HEIMDALL_PERIODIC_NOTIFICATION` | `false` | No | Enable periodic notifications | |
| 129 | +| `--notification-interval` | `-i` | `HEIMDALL_NOTIFICATION_INTERVAL` | `60` | Only if periodic notifications are enabled and you want a different value than default | How often (in minutes) periodic notifications should be sent | |
| 130 | +| `--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 | |
| 131 | +| `--retry` | `-r` | `HEIMDALL_RETRY` | `10` | No | How long Heimdall should sleep before retrying in case the Docker event stream ends unexpectedly | |
| 132 | +| `--provider` | `-p` | `HEIMDALL_PROVIDER` | `discord` | No | What notification provider should be used. Possible values: `discord` | |
| 133 | +| `--webhook-url` | `-w` | `HEIMDALL_WEBHOOK_URL` | - | Yes | What URL Heimdall should use to send notifications to | |
| 134 | +| `--debug` | `-d` | `HEIMDALL_DEBUG` | `false` | No | Enable extra debug messages | |
| 135 | + |
| 136 | + |
| 137 | +## Technologies |
| 138 | +Heimdall was created using Go. The CI/CD pipeline is handled by GitHub Actions and the Docker image is hosted on Docker Hub. |
| 139 | + |
| 140 | +The program is mostly based on the [Docker SDK for Go](https://pkg.go.dev/github.com/docker/docker/client#section-readme) |
| 141 | + |
| 142 | +It uses the following technologies: |
| 143 | +### Language |
| 144 | +[](https://go.dev) |
| 145 | + |
| 146 | +### Deployed to |
| 147 | +[](https://hub.docker.com/r/drfractum/heimdall) |
| 148 | + |
| 149 | +### CI/CD |
| 150 | +[](https://github.com/RobinHeidenis/heimdall/actions) |
| 151 | + |
| 152 | +### Released using |
| 153 | +[](https://goreleaser.com) |
| 154 | + |
| 155 | +### Logo created using |
| 156 | +[](https://www.bing.com/images/create) |
| 157 | + |
| 158 | + |
| 159 | +## Screenshots |
| 160 | +### Terminal output |
| 161 | + |
| 162 | + |
| 163 | +### Discord notifications |
| 164 | +#### Container started |
| 165 | + |
| 166 | + |
| 167 | +#### Container stopped |
| 168 | + |
| 169 | + |
| 170 | +#### Container healthy |
| 171 | + |
| 172 | + |
| 173 | +#### Container unhealthy |
| 174 | + |
| 175 | + |
| 176 | +#### Container errored |
| 177 | + |
| 178 | + |
| 179 | +### Periodic notification |
| 180 | +#### Running containers |
| 181 | + |
| 182 | + |
| 183 | +#### All containers |
| 184 | + |
0 commit comments