{"id":15115377,"url":"https://github.com/ravanbod/dockerwatcher","last_synced_at":"2025-04-11T04:51:17.918Z","repository":{"id":241568586,"uuid":"797090095","full_name":"ravanbod/dockerwatcher","owner":"ravanbod","description":"DockerWatcher is a lightweight Go-based tool designed for real-time Docker event monitoring and system notification. It offers flexible running modes, supports Redis queues, and integrates with Telegram for instant alerts. Simplify Docker monitoring with DockerWatcher.","archived":false,"fork":false,"pushed_at":"2024-05-28T15:12:43.000Z","size":56,"stargazers_count":29,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2024-05-29T03:42:14.601Z","etag":null,"topics":["devops","docker","go","golang","redis"],"latest_commit_sha":null,"homepage":"https://behrad.dev","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ravanbod.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-05-07T07:16:11.000Z","updated_at":"2024-05-29T03:42:20.713Z","dependencies_parsed_at":"2024-05-29T03:42:19.684Z","dependency_job_id":"0a5c506d-b5df-4a27-b1a5-9fe9bd792c77","html_url":"https://github.com/ravanbod/dockerwatcher","commit_stats":null,"previous_names":["ravanbod/dockerwatcher"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ravanbod%2Fdockerwatcher","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ravanbod%2Fdockerwatcher/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ravanbod%2Fdockerwatcher/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ravanbod%2Fdockerwatcher/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ravanbod","download_url":"https://codeload.github.com/ravanbod/dockerwatcher/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248345289,"owners_count":21088243,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["devops","docker","go","golang","redis"],"created_at":"2024-09-26T01:43:48.415Z","updated_at":"2025-04-11T04:51:17.895Z","avatar_url":"https://github.com/ravanbod.png","language":"Go","readme":"## DockerWatcher\n\n**DockerWatcher** is a monitoring solution written in Go, designed to track Docker events and notify system administrators in real-time. By leveraging Docker's event system, DockerWatcher helps you stay informed about crucial changes such as container creation or termination, ensuring you are always aware of the state of your Docker environment.\n\n### Key Features\n\n- **Event Monitoring:** Capture and filter events from Docker's event system.\n- **Multi-Platform Notifications:** Receive alerts on your preferred communication platforms, including Telegram (Supported), Mattermost (Supported), Generic webhook (Supported) and more (Soon).\n- **Scalable Architecture:** Designed with a modular approach to efficiently handle and process event data.\n- **Written in Go:** Utilizes the powerful and efficient Go programming language for high performance and reliability.\n\n### Project Structure\n\nDockerWatcher consists of two main services:\n\n1. **Watcher Service:**\n    - Collects and filters data from Docker's event system.\n    - Pushes the relevant event data to the queue for further processing.\n    \n2. **Notification Service:**\n    - Retrieves filtered event data from the queue.\n    - Sends notifications to users via the configured communication platforms.\n\n### Running Modes\n\nDockerWatcher can be run in three different modes, providing flexibility based on your requirements:\n\n1. **Watcher Mode:**\n    - Collects data from Docker's event system and pushes it to the queue.\n    - Ideal for distributed environments where multiple instances collect data from different Docker engines.\n\n2. **Notification Mode:**\n    - Retrieves data from the queue and sends notifications to users.\n    - Useful for centralizing the notification logic in a single service.\n\n3. **Watcher and Notification Mode:**\n    - Combines both watcher and notification functionalities.\n    - Collects data and sends notifications in one go, simplifying the deployment.\n\nBy using lists in Redis, DockerWatcher creates queues of messages, ensuring efficient and orderly processing of events. (Also you can use dwqueue instead of redis!)\n\n### Notification Platforms\n\n- [x] Telegram\n- [x] Generic webhook\n- [x] Mattermost\n\n\n### Motivation\n\nDockerWatcher was created to address the need for a reliable and efficient way to monitor Docker environments. By providing timely notifications about critical events, DockerWatcher helps system administrators maintain better control and oversight of their Docker containers, improving overall system reliability and responsiveness.\n\n## Usage\n\n### Build from Source Code\n\nTo build DockerWatcher from source, follow these steps:\n\n1. **Clone the Repository:**\n    ```sh\n    git clone https://github.com/ravanbod/dockerwatcher.git\n    cd dockerwatcher\n    ```\n\n2. **Build the Project:**\n    ```sh\n    go build -o dockerwatcher cmd/dockerwatcher/main.go\n    ```\n\n### Build with Docker\n\nTo build DockerWatcher with docker, follow these steps:\n\n1. **Clone the Repository:**\n    ```sh\n    git clone https://github.com/ravanbod/dockerwatcher.git\n    cd dockerwatcher\n    ```\n\n2. **Build the Project:**\n    ```sh\n    docker build -t dockerwatcher:$(git describe --exact-match --tags 2\u003e /dev/null || git rev-parse --short HEAD) -t dockerwatcher:latest .\n    ```\n\n## How to run\n\n### Environment Variables\n\nplease see `.env.example` file. create another file like this and name it `.env`.\n\nAlso you can export these variables in the shell you use.\n\n| Key                      | Description               | Optional/Required        |\n|--------------------------|---------------------------|--------------------------|\n| QUEUE_TYPE               | redis,dwqueue             | Required                 |\n| REDIS_URL                |                           | Required if qt=redis     |\n| REDIS_QUEUE_WRITE_NAME   |                           | Required if qt=redis     |\n| REDIS_QUEUE_READ_NAMES   |                           | Required if qt=redis     |\n| ENABLE_WATCHER           | 0 (disabled), 1 (enabled) | Required                 |\n| ENABLE_NOTIFICATION      | 0 (disabled), 1 (enabled) | Required                 |\n| GRACEFUL_SHUTDOWN_TIMEOUT| Integer (seconds)         | Required                 |\n| EVENTS_FILTER            |                           | Optional                 |\n| NOTIFICATION_PLATFORM    |generic,telegram,mattermost| Required                 |\n| TELEGRAM_BOT_API_TOKEN   |                           | Required if np=telegram  |\n| TELEGRAM_CHAT_ID         |                           | Required if np=telegram  |\n| GENERIC_NOTIFICATION_URL |                           | Required if np=generic   |\n| MATTERMOST_HOST          |                           | Required if np=mattermost|\n| MATTERMOST_BEARER_AUTH   |                           | Required if np=mattermost|\n| MATTERMOST_CHANNEL_ID    |                           | Required if np=mattermost|\n\n*qt = QUEUE_TYPE\n*np = NOTIFICATION_PLATFORM\n\nfor example, if you want to set `NOTIFICATION_PLATFORM=telegram`, `TELEGRAM_BOT_API_TOKEN` and `TELEGRAM_CHAT_ID` are necessary.\n\n`REDIS_QUEUE_READ_NAMES` and `EVENTS_FILTER` are comma seperated. watch `.env.example`.\n\nfor `EVENTS_FILTER`, see [this link](https://docs.docker.com/reference/cli/docker/system/events/#filter).\n\nif `QUEUE_TYPE` is `dwqueue`, `ENABLE_WATCHER` and `ENABLE_NOTIFICATION` must be `1`.\n\n### Run without docker\n\nTo run the project without docker, You can simply run this command (after Build from source code).\n\n```\n./dockerwatcher\n```\n\n### Run with docker\n\nTo run the project with docker, You can simply run this command (after Build with docker).\n\n```\ndocker run --name dockerwatcher -it -v $(pwd)/.env:/app/.env -v /var/run/docker.sock:/var/run/docker.sock --network dockerwatcher dockerwatcher\n```\n\nA redis has to be in `dockerwatcher` network.\n\n### Run with docker-compose (Recommended)\n\nIf you have an existing redis, you can use `docker-compose.yml`. else you can use `docker-compose-full.yml` that has redis and DockerWatcher.\n\n#### Run multiple instances\n\nIt is recommended that launch a watcher service in every docker engine and use a shared Redis between them. And launch a Notification instance that sends Redis messages to your notification platform.\n\n### Run single instance without Redis\n\nWe have a built-in queue system (a simple channel :) ) that you can use that instead of Redis. the point is that you can use dwqueue when `ENABLE_WATCHER` and `ENABLE_NOTIFICATION` are `1`.\n\n## Messages\nYou will get the messages in the markdown format. this is an example of dying mysql container.\n```\n# Docker Event \n\n ## Event Details \n\n- **Type**: `container`\n- **Action**: `die`\n- **Scope**: `local`\n- **Time**: `1716908784`\n- **TimeNano**: `1716908784342468156`\n## Actor \n- **Actor.ID**: `ab1bec9756b03eb3c12c42fe08496a94d73b037c8e60e41344ae869fd41e38cb`\n  - **name**: `mysql`\n  - **execDuration**: `5`\n  - **exitCode**: `0`\n  - **image**: `mysql`\n```\n","funding_links":[],"categories":["Go"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fravanbod%2Fdockerwatcher","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fravanbod%2Fdockerwatcher","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fravanbod%2Fdockerwatcher/lists"}