{"id":26649080,"url":"https://github.com/vibhorgupta-gh/Argus","last_synced_at":"2025-03-25T00:48:00.030Z","repository":{"id":48604760,"uuid":"298047121","full_name":"vibhorgupta-gh/Argus","owner":"vibhorgupta-gh","description":"Update your Docker container to the latest base image effortlessly","archived":false,"fork":false,"pushed_at":"2025-03-12T10:16:36.000Z","size":1709,"stargazers_count":29,"open_issues_count":19,"forks_count":4,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-25T00:47:53.144Z","etag":null,"topics":["automation","docker","docker-container","docker-image","jest","typescript"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/vibhorgupta-gh.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":"2020-09-23T17:36:59.000Z","updated_at":"2024-11-08T06:04:51.000Z","dependencies_parsed_at":"2024-01-05T23:22:49.815Z","dependency_job_id":"27ff022e-e3ba-442c-b12d-09a86021d6e7","html_url":"https://github.com/vibhorgupta-gh/Argus","commit_stats":null,"previous_names":["vibhorcodeciangupta/argus"],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vibhorgupta-gh%2FArgus","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vibhorgupta-gh%2FArgus/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vibhorgupta-gh%2FArgus/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vibhorgupta-gh%2FArgus/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/vibhorgupta-gh","download_url":"https://codeload.github.com/vibhorgupta-gh/Argus/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245377954,"owners_count":20605375,"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":["automation","docker","docker-container","docker-image","jest","typescript"],"created_at":"2025-03-25T00:47:59.102Z","updated_at":"2025-03-25T00:48:00.021Z","avatar_url":"https://github.com/vibhorgupta-gh.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Argus\n\n![Argus](https://socialify.git.ci/VibhorCodecianGupta/Argus/image?description=1\u0026language=1\u0026pattern=Circuit%20Board\u0026stargazers=1\u0026theme=Light)\n\n## Overview and Intent\n\nA TypeScript-based cousin of [watchtower](https://github.com/v2tec/watchtower), with support for **_semantically versioned image tags_**. Update your Docker container to the latest base image effortlessly.\n\n![Demo-GIF](https://media.giphy.com/media/UkngTf9Y0kwKQnAMof/giphy.gif)\n\n**_Argus automatically updates your running Docker containers to the latest available image._**\nThe problem with managing docker images and containers manually, especially in an environment where containers are running across servers and need frequent updates due to constant images updates to the registry, is a series of CLI commands needed to update and rerun a container which quickly gets tiresome:\n\n```\ndocker stop ...\ndocker rm ...\ndocker pull ...\ndocker run ...\n```\n\nAdditionally, if you wish to cleanup redundant images, again `docker rmi -f ...`.\n\nArgus automates the job of updating Docker containers in favour of latest images available in an image registry. Assuming a developer is publishing new versions of a Docker image frequently for an application that resides in containers deployed on local/remote servers, the dev needs a way to propogate the image update to these containers. Traditionally, after SSHing in the remote machine the dev has to stop the existing container, pull the latest image as base, and restart the container. The entire process requires running a series of commands that get tedious, quick.\n\nAutomating the process of watching your containers, looking for latest images on a remote registry, exiting the running container, pulling the latest image and running a new container with the updated base ensures keeping up to date with newer, stable versions.\n\n---\n\n## Capabilities\n\n- [x] Container base image updates\n- [x] Support for semantically versioned tags\n- [x] Support for antipattern tag nomenclature (tag names like `latest`)\n- [x] Email notifications\n- [x] Telegram notifications\n- [x] Slack notifications\n- [x] Discord notifications\n- [x] Pushover notifications\n- [x] Prometheus integration for metrics monitoring\n- [x] InfluxDB integration for metrics monitoring\n- [x] Updates for major release\n- [x] Support for unstable release updates\n- [ ] Microsoft teams notifications\n- [ ] Support for Docker Swarm\n- [ ] Zero downtime deployments\n- [ ] Support for Deno (Make package Deno compatible)\n\n---\n\n## Usage\n\n**NPM package**\n\n`Argus` is available in the npm registry as a package. To use:\n\n`yarn global add argus-docker` or `npm i -g argus-docker`\n\n**Docker Image**\n\n`Argus` is also deployed via docker image like so:\n\n```bash\ndocker run -d --name argus \\\n  -v /var/run/docker.sock:/var/run/docker.sock \\\n  whaleit/argus\n```\n\n- Remove the `-d` flag to run in foreground\n- By default, running containers are polled every 300 seconds\n\n### Options\n\nAll arguments can be used together without conflicts with the exception of `-u` and `-p`.\n\n```\ndocker run --rm whaleit/argus --help\n```\n\n- `--host`, `-u`: Monitor and update containers on a remote system by providing its `host`. Defaults to `/var/run/docker.sock`\n- `--interval`, `-i`: Change interval b/w Argus checking the remote docker registry for image updates (in seconds). Defaults to `300`\n- `--monitor`, `-m`: Only monitor select containers by names. Defaults to all containers.\n- `--ignore`, `-ig`: Ignore only select containers by names. Defaults to none.\n- `--runonce`, `-r`: Update all running containers once and terminate. Defaults to `false`.\n- `--cleanup`, `-c`: Remove the older base image if a new one is found and updated. Defaults to `false`.\n- `--user`, `-u`: Specify username for private image registry. Defaults to `null`.\n- `--password`, `-p`: Specify password for private image registry. Defaults to `null`.\n- `--smtp-host`, `-H`: Specify SMTP relay hostname for email notifications. Defaults to `null`.\n- `--smtp-port`, `-I`: Specify SMTP relay port for email notifications. Defaults to `null`.\n- `--smtp-username`, `-U`: Specify SMTP relay username to login SMTP server. Defaults to `null`.\n- `--smtp-password`, `-G`: Specify SMTP relay password to login SMTP server. Defaults to `null`.\n- `--smtp-sender`, `-j`: Specify sender's email account for email notification. Defaults to `null`.\n- `--smtp-recipients`, `-J`: Specify all recipients' comma separated email accounts for email notification. Defaults to `null`.\n- `--webhook-urls`, `-w`: Specify comma separated Webhook urls to HTTP POST broadcast notifications to various platforms (supports Slack, Discord, Telegram, Pushover). Defaults to `null`.\n- `--pushover-token`, `-pt`: Specify Pushover App Token to broadcast notifications to your Pushover client. Defaults to `null`.\n- `--pushover-user`, `-pu`: Specify Pushover User Key to broadcast notifications to your Pushover client. Defaults to `null`.\n- `--pushover-device`, `-pd`: Specify Pushover device to broadcast notifications to your Pushover client. Defaults to `null`.\n- `--telegram-token`, `-tt`: Specify Telegram bot Token to broadcast notifications to Telegram. Defaults to `null`.\n- `--telegram-chat`, `-tc`: Specify Telegram Chat ID to broadcast notifications to Telegram. Defaults to `null`.\n- `--prometheus-host`, `-ph`: Specify server hostname for Prometheus to scrape metrics from. Defaults to `null`.\n- `--prometheus-port`, `-pi`: Specify server port for Prometheus to scrape metrics from. Defaults to `null`.\n- `--influx-url`, `-iu`: Specify url where InfluxDB is exposed. Defaults to `null`.\n- `--influx-token`, `-it`: Specify InfluxDB auth token for your organisation. Defaults to `null`.\n- `--influx-org`, `-io`: Specify InfluxDB organisation. Defaults to `null`.\n- `--influx-bucket`, `-ib`: Specify InfluxDB bucket for your organisation. Defaults to `null`.\n- `--private-registry`, `-reg`: Base URL to a private image registry. Defaults to `registry-1.docker.io`.\n- `--semver-update`, `-sv`: Allow updates according to semantically versioned images. Defaults to `false`.\n- `--allow-major-updates`, `-mu`: Updates to the latest major release. Defaults to `false`.\n- `--allow-patch-only`, `-po`: Only updates to latest patch release. Defaults to `false`.\n- `--allow-prerelease-updates`, `-pr`: Enables pre release updates if available. Defaults to `false`.\n\n**Using related flags:**\n\n- `-u` and `-p` flags are to be used in conjunction as credentials in case of private image registry.\n- `-H`, `-I`, `-U`,`-G`, `-j` and `-J`are to be used in conjunction as SMTP server credentials and sender/recipients in case of broadcasting notifications via email.\n- `w`, `-pt`, `-pu` and `-pd` are to be used in conjunction in case of broadcasting notifications to Pushover.\n- `w`, `-tt` and `-tc` are to be used in conjunction in case of broadcasting notifications to Telegram.\n- `w`, `-ph` and `-pi` are to be used in conjunction in case of exporting data to Prometheus.\n- `-iu`, `-it`, `-io` and `-ib` are to be used in conjunction in case of writing data to InfluxDB\n- Value of `-mu`, `-pr` and `-po` will be ignored if semver updates are not enabled\n- Precedence order if semver updates are enabled: `-mu` \u003e `-pr` \u003e `-pu` \u003e default behaviour (update to latest minor/patch release, whichever update is posted last)\n\n---\n\n## Examples\n\n### Update containers on a remote host\n\nArgus can monitor things other than just local, pass the `--host` argument to update a system with the Docker API exposed.\n\nDefaults to `/var/run/docker.sock`\n\n1. Running the docker image\n\n```bash\ndocker run -d --name argus \\\n  -v /var/run/docker.sock:/var/run/docker.sock \\\n  whaleit/argus --host='tcp://some-remote-docker-server:2375'\n```\n\n2. Running the npm package\n\n```bash\nargus --host='tcp://some-remote-docker-server:2375'\n```\n\n### Change update interval\n\nAn `interval` argument can be supplied to change interval b/w argus checking the remote docker registry for image updates (in seconds).\n\nDefaults to `300` seconds\n\n1. Running the docker image\n\n```bash\ndocker run -d --name argus \\\n  -v /var/run/docker.sock:/var/run/docker.sock \\\n  whaleit/argus --interval=900\n```\n\n2. Running the npm package\n\n```bash\nargus --interval=900\n```\n\n### Monitor select containers\n\nArgus monitors all running docker containers, but can be overridden to only monitor select containers by passing `monitor` supplied with container names.\n\nDefaults to all containers\n\n1. Running the docker image\n\n```bash\ndocker run -d --name argus \\\n  -v /var/run/docker.sock:/var/run/docker.sock \\\n  whaleit/argus --monitor='containerA','containerB','containerC'\n```\n\n2. Running the npm package\n\n```bash\nargus --monitor='containerA','containerB','containerC'\n```\n\n### Ignore select containers\n\nArgus monitors all running docker containers, but can be overridden to ignore select containers by passing `ignore` supplied with container names.\n\nDefaults to none\n\n1. Running the docker image\n\n```bash\ndocker run -d --name argus \\\n  -v /var/run/docker.sock:/var/run/docker.sock \\\n  whaleit/argus --ignore='containerA','containerB'\n```\n\n2. Running the npm package\n\n```bash\nargus --ignore='containerA','containerB'\n```\n\n### Update all containers once and quit\n\nIf you prefer Argus didn't run all the time and only update running containers once and exit, use the `runonce` argument and Argus terminates after updating all containers once.\n\nDefaults to `false`\n\n1. Running the docker image\n\n```bash\ndocker run -d --name argus \\\n  -v /var/run/docker.sock:/var/run/docker.sock \\\n  whaleit/argus --runonce=true\n```\n\n2. Running the npm package\n\n```bash\nargus --runonce=true\n```\n\n### Remove old docker images\n\nArgus has the option to remove the outdated base image if a new one is found and the container is updated. To clean up after updates, pass the `cleanup` argument.\n\nDefaults to `false`\n\n1. Running the docker image\n\n```bash\ndocker run -d --name argus \\\n  -v /var/run/docker.sock:/var/run/docker.sock \\\n  whaleit/argus --cleanup=true\n```\n\n2. Running the npm package\n\n```bash\nargus --cleanup=true\n```\n\n### Private Registries\n\nIf base images to running containers are stored in a secure registry that requires credentials, you can run Argus with arguments `--private-registry` and `--user` and `--password`.\n\n1. Running the docker image\n\n```bash\ndocker run -d --name argus \\\n  -v /var/run/docker.sock:/var/run/docker.sock \\\n  whaleit/argus --user='myUser' --password='myPassword' --private-registry='some-registry.azure.io'\n```\n\n2. Running the npm package\n\n```bash\nargus --user='myUser' --password='myPassword' --private-registry='some-registry.azure.io'\n```\n\nCredentials can also be passed via environment variables. Set the environment vars in your command line environment prior to running Argus like so:\n\n```bash\nexport PRIVATE_REGISTRY=some-registry.azure.io\nexport REPO_USER=myUser\nexport REPO_PASS=myPassword\n```\n\n### Semantically Versioned Tags\n\n- Argus provides support for updating your images according to semver nomenclature of your tags. This is switched OFF by default, and can be enabled by `--semver-update=true`. If semver updates are disabled, Argus looks for `latest` tag.\n- When semver updates are enabled, By default the image will be updated to the most **recent minor or patch release**\n- If you want to update to only the patch releases, use `--allow-patch-only=true` (disabled by default)\n- If you want to update to major releases, use `--allow-major-updates=true` (disabled by default)\n- If you want to update to the recent pre releases [so called unstable releases, eg. v1.0.0-alpha], use `--allow-prerelease-updates=true` (disabled by default)\n- Argus uses the Docker Registry API to determine the updated tags in the repository. If you are using a private registry, please specify the URL and credentials for the same.\n\nCredentials can be passed via CLI flags:\n\n```bash\n--user='myUser' --password='myPassword' --private-registry='some-registry.azure.io'\n```\n\nCredentials can also be passed via environment variables:\n\n```bash\nexport PRIVATE_REGISTRY=some-registry.azure.io\nexport REPO_USER=myUser\nexport REPO_PASS=myPassword\n```\n\n### Email notifications\n\nArgus can send notifications to subscribers via email, detailing about the count of containers being updated and their new hashes.\n\n1. Running the docker image\n\n```bash\ndocker run -d --name argus \\\n  -v /var/run/docker.sock:/var/run/docker.sock \\\n  whaleit/argus --smtp-host='smtp.gmail.com' --smtp-port='587' --smtp-username='someaccount@gmail.com' --smtp-password='someaccountpass' --smtp-recipients='somereceiver@gmail.com,anotherreceiver@gmail.com' --smtp-sender='somesender@gmail.com'\n```\n\n2. Running the npm package\n\n```bash\nargus --smtp-host='smtp.gmail.com' --smtp-port='587' --smtp-username='someaccount@gmail.com' --smtp-password='someaccountpass' --smtp-recipients='somereceiver@gmail.com,anotherreceiver@gmail.com' --smtp-sender='somesender@gmail.com'\n```\n\n### Webhook notifications\n\nArgus can broadcast notifiations to various platforms that support webhook POST urls, detailing about the count of containers being updated and their new hashes. Following platforms are supported (You're free to request for more platforms, preferably ones supporting webhooks):\n\n- Slack\n- Telegram\n- Discord\n- Pushover\n\nEach of these platforms requires separate flags with platform specific information that can be passed independant of any other in this list. Webhook URLs, however, have to be necessarily passed in specifying comma separated webhook URL strings of said platforms.\nThe pre-requisite is to register apps (Pushover, Slack)/ bots (Telegram)/ servers (Discord) and obtaining their webhook URLs.\n\n1. Running the docker image\n\n```bash\ndocker run -d --name argus \\\n  -v /var/run/docker.sock:/var/run/docker.sock \\\n  whaleit/argus --webhook-urls='https://discord.com/api/webhooks/some-url','https://hooks.slack.com/services/some-url' --pushover-token='\u003cpushover_token\u003e' --pushover-user='\u003cpushover_user_key\u003e' --pushover-device='\u003cpushover_device\u003e' --telegram-token='\u003cidentifier\u003e:\u003ctoken\u003e' --telegram-chat='\u003ctelegram_chat_id\u003e'\n```\n\n2. Running the npm package\n\n```bash\nargus --smtp-host='smtp.gmail.com' --smtp-port='587' --smtp-username='someaccount@gmail.com' --smtp-password='someaccountpass' --smtp-recipients='somereceiver@gmail.com,anotherreceiver@gmail.com' --smtp-sender='somesender@gmail.com'\n```\n\n### Prometheus metrics\n\nArgus is enabled with Prometheus data exporter from which Prometheus can scrape for metrics. Argus fires up a server for Prometheus to attach to, hostname and port being specified by the user. Prometheus is disabled by default if no hostname and port is found.\n\n1. Running the docker image\n\n```bash\ndocker run -d --name argus \\\n  -v /var/run/docker.sock:/var/run/docker.sock \\\n  whaleit/argus --prometheus-host='http://127.0.0.1' --prometheus-port='8000'\n```\n\n2. Running the npm package\n\n```bash\nargus --prometheus-host='http://127.0.0.1' --prometheus-port='8000'\n```\n\nYou can also easily set up a Grafana dashboard for said metrics captured which require minimal changes to `promotheus.yml` config file on your system, and configuring your Grafana subdomain accordingly. **An importable Grafana dashboard template is coming soon.**\n\n### InfluxDB metrics\n\nArgus is enabled with InfluxDB client which can write data to your local or hosted Influx service. User needs to start the Influx service and specify above mentioned parameters to activate influx exporter. InfluxDB is disabled by default if no URL and token is found.\n\n1. Running the docker image\n\n```bash\ndocker run -d --name argus \\\n  -v /var/run/docker.sock:/var/run/docker.sock \\\n  whaleit/argus  --influx-token='\u003cyour_token\u003e' --influx-url='http://127.0.0.1:8086/' --influx-org='\u003cyour_org\u003e' --influx-bucket='\u003cyour_bucket\u003e'\n```\n\n2. Running the npm package\n\n```bash\nargus --influx-token='\u003cyour_token\u003e' --influx-url='http://127.0.0.1:8086/' --influx-org='\u003cyour_org\u003e' --influx-bucket='\u003cyour_bucket\u003e'\n```\n\nYou can easily query the data written by Argus in either the influx CLI or the dashboard UI (live on your influx-url) to observe metrics. You an also use the influx client libraries to query this data in your applications.\n\n---\n\n## Development\n\nArgus is built with [Typescript](https://www.typescriptlang.org/) and utilizes this [Docker SDK](https://github.com/apocas/dockerode).\n\n### Installation\n\nEnsure you have the Docker engine installed and running. To setup a local copy, follow these simple steps.\n\n```\nnpm i -g typescript\ngit clone https://github.com/VibhorCodecianGupta/Argus.git\nyarn install\n```\n\n### Running a prod build\n\n```\nyarn run build\nyarn run start\n```\n\n### Running in dev mode\n\n```\nyarn run dev\n```\n\n---\n\n## Contributing\n\nAny and all contributions are welcome. You can check out Issue tracker and ongoing projects to look for existing issues and start contributing.\n\nFeel free to open issues for any bugs you discover or any feature ideas you have. Do make sure to open an issue before moving to implementation. This ensures sufficient discussion and context to incoming PRs.\n\n1. Fork the Project\n2. Create your feature breanch: `git checkout -b feature-branch`\n3. Commit your Changes: `git commit -m \"Add some feature\"`\n4. Push to your fork: `git push origin feature-branch`\n5. Open a Pull Request.\n\nIf you like what you see, do consider leaving a star :)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvibhorgupta-gh%2FArgus","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvibhorgupta-gh%2FArgus","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvibhorgupta-gh%2FArgus/lists"}