imagenudge-lite 0.1.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- imagenudge_lite-0.1.0/LICENSE +21 -0
- imagenudge_lite-0.1.0/MANIFEST.in +5 -0
- imagenudge_lite-0.1.0/PKG-INFO +144 -0
- imagenudge_lite-0.1.0/README.md +116 -0
- imagenudge_lite-0.1.0/imagenudge_lite.egg-info/PKG-INFO +144 -0
- imagenudge_lite-0.1.0/imagenudge_lite.egg-info/SOURCES.txt +11 -0
- imagenudge_lite-0.1.0/imagenudge_lite.egg-info/dependency_links.txt +1 -0
- imagenudge_lite-0.1.0/imagenudge_lite.egg-info/entry_points.txt +2 -0
- imagenudge_lite-0.1.0/imagenudge_lite.egg-info/top_level.txt +1 -0
- imagenudge_lite-0.1.0/imagenudge_lite.py +504 -0
- imagenudge_lite-0.1.0/pyproject.toml +50 -0
- imagenudge_lite-0.1.0/setup.cfg +4 -0
- imagenudge_lite-0.1.0/test_imagenudge_lite.py +369 -0
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 PyForge (https://py-forge.com)
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,144 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: imagenudge-lite
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Check running Docker containers for newer images: digest changes and newer version tags. Read-only, no pulls.
|
|
5
|
+
Author: Alessio Auretto
|
|
6
|
+
License-Expression: MIT
|
|
7
|
+
Project-URL: Homepage, https://github.com/alessio1999xx-debug/imagenudge-lite
|
|
8
|
+
Project-URL: Pro version, https://py-forge.com/products/imagenudge-container-update-notifier
|
|
9
|
+
Keywords: docker,docker-image,container-updates,image-update-checker,self-hosted,homelab,docker-registry,cli,stdlib
|
|
10
|
+
Classifier: Development Status :: 4 - Beta
|
|
11
|
+
Classifier: Environment :: Console
|
|
12
|
+
Classifier: Intended Audience :: Developers
|
|
13
|
+
Classifier: Intended Audience :: System Administrators
|
|
14
|
+
Classifier: Operating System :: POSIX
|
|
15
|
+
Classifier: Programming Language :: Python :: 3
|
|
16
|
+
Classifier: Programming Language :: Python :: 3.9
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
19
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
20
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
21
|
+
Classifier: Topic :: System :: Monitoring
|
|
22
|
+
Classifier: Topic :: System :: Systems Administration
|
|
23
|
+
Classifier: Topic :: Utilities
|
|
24
|
+
Requires-Python: >=3.9
|
|
25
|
+
Description-Content-Type: text/markdown
|
|
26
|
+
License-File: LICENSE
|
|
27
|
+
Dynamic: license-file
|
|
28
|
+
|
|
29
|
+
# imagenudge-lite: Docker image update checker for running containers, read-only
|
|
30
|
+
|
|
31
|
+
imagenudge-lite helps with a Docker image update checker for a quick "which of my containers are behind?" check on one Docker host: it lists the running containers through the local Docker socket, asks the registry whether each container's tag now points to a different image digest, and whether a newer version tag exists (for example `1.25.1` -> `1.26.0`). It prints a plain-text list and exits `1` when something can be updated, so it fits a cron job. It never pulls, restarts or edits anything. One file, Python 3.9+ standard library only, MIT.
|
|
32
|
+
|
|
33
|
+
Need compose-file scanning, webhook / ntfy / SMTP email alerts, or JSON output? That is the full [ImageNudge](https://py-forge.com/products/imagenudge-container-update-notifier?utm_source=github&utm_medium=readme&utm_campaign=imagenudge-lite) (one-time payment, yours to keep, no subscription). A table later in this README lists what lite does and what the paid tool adds. Or get every PyForge tool, current and future, with the [All-Access Pass](https://py-forge.com/pass?utm_source=github&utm_medium=readme&utm_campaign=imagenudge-lite) ($99, one payment).
|
|
34
|
+
|
|
35
|
+
- Optional `pip install`, or just download the one file. No config, no state, no agent to run.
|
|
36
|
+
- Only `GET` requests to the Docker socket (`/containers/json`, `/images/<id>/json`). Registry checks are `HEAD` on the manifest plus the tag list; no image layers are downloaded.
|
|
37
|
+
- Public images only, anonymous access (Docker Hub, and registries that hand out anonymous pull tokens, e.g. public `ghcr.io` and `quay.io` images). No credentials are read or sent.
|
|
38
|
+
- Flags: `--socket`, `--no-tags`, `--demo`, `--timeout`, `--version`. After `pip install`, use `imagenudge-lite` in place of `python3 imagenudge_lite.py`.
|
|
39
|
+
|
|
40
|
+
<!-- TODO: terminal GIF of `--demo` or a live run is still missing. Place it under the intro, before Install. Do not invent a GIF. -->
|
|
41
|
+
|
|
42
|
+
## Install
|
|
43
|
+
|
|
44
|
+
```bash
|
|
45
|
+
pip install imagenudge-lite
|
|
46
|
+
imagenudge-lite --help
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
Or download the single file (Python 3.9+, stdlib only, no extra packages):
|
|
50
|
+
|
|
51
|
+
```bash
|
|
52
|
+
curl -fsSLO https://raw.githubusercontent.com/alessio1999xx-debug/imagenudge-lite/main/imagenudge_lite.py
|
|
53
|
+
python3 imagenudge_lite.py --help
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
## See the output first (offline demo)
|
|
57
|
+
|
|
58
|
+
```bash
|
|
59
|
+
python3 imagenudge_lite.py --demo
|
|
60
|
+
# imagenudge-lite 0.1.0: demo (sample data, no Docker, no network)
|
|
61
|
+
#
|
|
62
|
+
# UPDATE gitea gitea/gitea:1.21.0 newer tag 1.21.3
|
|
63
|
+
# UPDATE redis-cache redis:7.2-alpine new digest for :7.2-alpine (b2b2b2b2b2b2 -> d4d4d4d4d4d4); newer tag 7.4-alpine
|
|
64
|
+
# OK traefik traefik:v2.10.4 digest matches :v2.10.4
|
|
65
|
+
# SKIP my-app my-app:dev no registry digest locally (built or loaded locally?)
|
|
66
|
+
#
|
|
67
|
+
# 4 container(s): 2 update(s) available, 1 up to date, 1 skipped, 0 could not be checked.
|
|
68
|
+
# Nothing was pulled or restarted. Review the changelog, then update when you choose.
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
## Check running Docker containers for newer images
|
|
72
|
+
|
|
73
|
+
```bash
|
|
74
|
+
python3 imagenudge_lite.py
|
|
75
|
+
# needs read access to /var/run/docker.sock (root, or a user in the docker group)
|
|
76
|
+
|
|
77
|
+
python3 imagenudge_lite.py --socket /run/user/1000/docker.sock # rootless Docker
|
|
78
|
+
python3 imagenudge_lite.py --no-tags # digests only, skip the tag list
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
If `DOCKER_HOST` is set to a `unix://` path it is used as the default socket. TCP / SSH Docker hosts are not supported by the lite version.
|
|
82
|
+
|
|
83
|
+
## How a Docker image update is detected
|
|
84
|
+
|
|
85
|
+
| Status | Meaning |
|
|
86
|
+
| --- | --- |
|
|
87
|
+
| `UPDATE` | The registry digest for the tag the container runs differs from the local image's digest (e.g. `:latest` or `:7.2-alpine` was rebuilt upstream), and/or a newer version tag exists |
|
|
88
|
+
| `OK` | Digest matches and no newer version tag was found |
|
|
89
|
+
| `SKIP` | Nothing to compare: container started from an image ID, pinned by digest only, or an image built/loaded locally with no registry digest |
|
|
90
|
+
| `ERROR` | The registry could not be checked (private or missing image, rate limit, no network). Shown with the reason |
|
|
91
|
+
|
|
92
|
+
Newer tags keep the same style and suffix as the tag you run: `1.25.1` is compared with `X.Y.Z` tags, `16-alpine` with `N-alpine`, `v2.10.4` with `vX.Y.Z`. Tags like `latest` or `stable` only get the digest check. The lite version reads up to 3 pages (3,000 tags) of the tag list, so on repositories with huge tag lists the "newer tag" suggestion can be lower than the real newest one. Multi-arch images are compared by their index digest, which is what `docker pull` by tag records locally.
|
|
93
|
+
|
|
94
|
+
## Exit codes for cron
|
|
95
|
+
|
|
96
|
+
| Exit code | Meaning |
|
|
97
|
+
| --- | --- |
|
|
98
|
+
| `0` | Every image that could be checked is up to date (or no running containers) |
|
|
99
|
+
| `1` | At least one container has an update available |
|
|
100
|
+
| `2` | Docker socket not reachable, bad arguments, or no image could be checked at all |
|
|
101
|
+
|
|
102
|
+
```bash
|
|
103
|
+
# crontab: check every morning at 07:00, keep the last report
|
|
104
|
+
0 7 * * * python3 /opt/imagenudge_lite.py > /var/log/imagenudge-lite.txt 2>&1
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
Scheduling is up to you (cron, a systemd timer). The lite version does not send any alerts.
|
|
108
|
+
|
|
109
|
+
## imagenudge-lite vs ImageNudge
|
|
110
|
+
|
|
111
|
+
imagenudge-lite checks the running containers on one local Docker socket and prints a plain-text list. That's it.
|
|
112
|
+
|
|
113
|
+
The full [ImageNudge](https://py-forge.com/products/imagenudge-container-update-notifier?utm_source=github&utm_medium=readme&utm_campaign=imagenudge-lite) adds compose-file scanning, webhook / ntfy-style and SMTP email alerts, JSON output and a printed list of the `docker pull` commands to run yourself. One-time payment, yours to keep. No subscription.
|
|
114
|
+
|
|
115
|
+
Lite is not a strict subset: its `0` / `1` / `2` exit codes for cron are not in the paid tool.
|
|
116
|
+
|
|
117
|
+
| Capability | Lite (free) | Paid ImageNudge |
|
|
118
|
+
| --- | --- | --- |
|
|
119
|
+
| Running containers via the local Docker socket | Yes | Yes |
|
|
120
|
+
| `docker-compose.yml` files (`--compose-file`, several at once) | No | Yes |
|
|
121
|
+
| New digest for the same tag | Yes | Yes |
|
|
122
|
+
| Newer semver tag (same suffix and style) | Yes (up to 3 tag-list pages) | Yes (up to 5 tag-list pages) |
|
|
123
|
+
| Registries | Public images, anonymous access | Public images, anonymous access |
|
|
124
|
+
| Alerts | No | Webhook / ntfy-compatible POST (`--notify-url`) and SMTP email (`--email-to`) |
|
|
125
|
+
| Output | Plain text list | Text or JSON (`--format json`) |
|
|
126
|
+
| Prints the `docker pull` commands to run (`--apply`, never runs them) | No | Yes |
|
|
127
|
+
| Exit code `1` when updates are available | Yes | No (exits `0`) |
|
|
128
|
+
| Offline `--demo` | Yes | Yes, plus a built-in `--self-test` |
|
|
129
|
+
|
|
130
|
+
Neither version pulls images, restarts containers, edits files, or reads registry credentials.
|
|
131
|
+
|
|
132
|
+
Or get every PyForge tool, current and future, with the [All-Access Pass](https://py-forge.com/pass?utm_source=github&utm_medium=readme&utm_campaign=imagenudge-lite) ($99, one payment).
|
|
133
|
+
|
|
134
|
+
## Tests
|
|
135
|
+
|
|
136
|
+
```bash
|
|
137
|
+
python3 test_imagenudge_lite.py
|
|
138
|
+
```
|
|
139
|
+
|
|
140
|
+
The tests are offline: a fake registry, and a tiny fake Docker API on a temporary unix socket. No Docker and no network needed.
|
|
141
|
+
|
|
142
|
+
## License
|
|
143
|
+
|
|
144
|
+
MIT (this lite version). The full ImageNudge is sold separately under its own license.
|
|
@@ -0,0 +1,116 @@
|
|
|
1
|
+
# imagenudge-lite: Docker image update checker for running containers, read-only
|
|
2
|
+
|
|
3
|
+
imagenudge-lite helps with a Docker image update checker for a quick "which of my containers are behind?" check on one Docker host: it lists the running containers through the local Docker socket, asks the registry whether each container's tag now points to a different image digest, and whether a newer version tag exists (for example `1.25.1` -> `1.26.0`). It prints a plain-text list and exits `1` when something can be updated, so it fits a cron job. It never pulls, restarts or edits anything. One file, Python 3.9+ standard library only, MIT.
|
|
4
|
+
|
|
5
|
+
Need compose-file scanning, webhook / ntfy / SMTP email alerts, or JSON output? That is the full [ImageNudge](https://py-forge.com/products/imagenudge-container-update-notifier?utm_source=github&utm_medium=readme&utm_campaign=imagenudge-lite) (one-time payment, yours to keep, no subscription). A table later in this README lists what lite does and what the paid tool adds. Or get every PyForge tool, current and future, with the [All-Access Pass](https://py-forge.com/pass?utm_source=github&utm_medium=readme&utm_campaign=imagenudge-lite) ($99, one payment).
|
|
6
|
+
|
|
7
|
+
- Optional `pip install`, or just download the one file. No config, no state, no agent to run.
|
|
8
|
+
- Only `GET` requests to the Docker socket (`/containers/json`, `/images/<id>/json`). Registry checks are `HEAD` on the manifest plus the tag list; no image layers are downloaded.
|
|
9
|
+
- Public images only, anonymous access (Docker Hub, and registries that hand out anonymous pull tokens, e.g. public `ghcr.io` and `quay.io` images). No credentials are read or sent.
|
|
10
|
+
- Flags: `--socket`, `--no-tags`, `--demo`, `--timeout`, `--version`. After `pip install`, use `imagenudge-lite` in place of `python3 imagenudge_lite.py`.
|
|
11
|
+
|
|
12
|
+
<!-- TODO: terminal GIF of `--demo` or a live run is still missing. Place it under the intro, before Install. Do not invent a GIF. -->
|
|
13
|
+
|
|
14
|
+
## Install
|
|
15
|
+
|
|
16
|
+
```bash
|
|
17
|
+
pip install imagenudge-lite
|
|
18
|
+
imagenudge-lite --help
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
Or download the single file (Python 3.9+, stdlib only, no extra packages):
|
|
22
|
+
|
|
23
|
+
```bash
|
|
24
|
+
curl -fsSLO https://raw.githubusercontent.com/alessio1999xx-debug/imagenudge-lite/main/imagenudge_lite.py
|
|
25
|
+
python3 imagenudge_lite.py --help
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
## See the output first (offline demo)
|
|
29
|
+
|
|
30
|
+
```bash
|
|
31
|
+
python3 imagenudge_lite.py --demo
|
|
32
|
+
# imagenudge-lite 0.1.0: demo (sample data, no Docker, no network)
|
|
33
|
+
#
|
|
34
|
+
# UPDATE gitea gitea/gitea:1.21.0 newer tag 1.21.3
|
|
35
|
+
# UPDATE redis-cache redis:7.2-alpine new digest for :7.2-alpine (b2b2b2b2b2b2 -> d4d4d4d4d4d4); newer tag 7.4-alpine
|
|
36
|
+
# OK traefik traefik:v2.10.4 digest matches :v2.10.4
|
|
37
|
+
# SKIP my-app my-app:dev no registry digest locally (built or loaded locally?)
|
|
38
|
+
#
|
|
39
|
+
# 4 container(s): 2 update(s) available, 1 up to date, 1 skipped, 0 could not be checked.
|
|
40
|
+
# Nothing was pulled or restarted. Review the changelog, then update when you choose.
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
## Check running Docker containers for newer images
|
|
44
|
+
|
|
45
|
+
```bash
|
|
46
|
+
python3 imagenudge_lite.py
|
|
47
|
+
# needs read access to /var/run/docker.sock (root, or a user in the docker group)
|
|
48
|
+
|
|
49
|
+
python3 imagenudge_lite.py --socket /run/user/1000/docker.sock # rootless Docker
|
|
50
|
+
python3 imagenudge_lite.py --no-tags # digests only, skip the tag list
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
If `DOCKER_HOST` is set to a `unix://` path it is used as the default socket. TCP / SSH Docker hosts are not supported by the lite version.
|
|
54
|
+
|
|
55
|
+
## How a Docker image update is detected
|
|
56
|
+
|
|
57
|
+
| Status | Meaning |
|
|
58
|
+
| --- | --- |
|
|
59
|
+
| `UPDATE` | The registry digest for the tag the container runs differs from the local image's digest (e.g. `:latest` or `:7.2-alpine` was rebuilt upstream), and/or a newer version tag exists |
|
|
60
|
+
| `OK` | Digest matches and no newer version tag was found |
|
|
61
|
+
| `SKIP` | Nothing to compare: container started from an image ID, pinned by digest only, or an image built/loaded locally with no registry digest |
|
|
62
|
+
| `ERROR` | The registry could not be checked (private or missing image, rate limit, no network). Shown with the reason |
|
|
63
|
+
|
|
64
|
+
Newer tags keep the same style and suffix as the tag you run: `1.25.1` is compared with `X.Y.Z` tags, `16-alpine` with `N-alpine`, `v2.10.4` with `vX.Y.Z`. Tags like `latest` or `stable` only get the digest check. The lite version reads up to 3 pages (3,000 tags) of the tag list, so on repositories with huge tag lists the "newer tag" suggestion can be lower than the real newest one. Multi-arch images are compared by their index digest, which is what `docker pull` by tag records locally.
|
|
65
|
+
|
|
66
|
+
## Exit codes for cron
|
|
67
|
+
|
|
68
|
+
| Exit code | Meaning |
|
|
69
|
+
| --- | --- |
|
|
70
|
+
| `0` | Every image that could be checked is up to date (or no running containers) |
|
|
71
|
+
| `1` | At least one container has an update available |
|
|
72
|
+
| `2` | Docker socket not reachable, bad arguments, or no image could be checked at all |
|
|
73
|
+
|
|
74
|
+
```bash
|
|
75
|
+
# crontab: check every morning at 07:00, keep the last report
|
|
76
|
+
0 7 * * * python3 /opt/imagenudge_lite.py > /var/log/imagenudge-lite.txt 2>&1
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
Scheduling is up to you (cron, a systemd timer). The lite version does not send any alerts.
|
|
80
|
+
|
|
81
|
+
## imagenudge-lite vs ImageNudge
|
|
82
|
+
|
|
83
|
+
imagenudge-lite checks the running containers on one local Docker socket and prints a plain-text list. That's it.
|
|
84
|
+
|
|
85
|
+
The full [ImageNudge](https://py-forge.com/products/imagenudge-container-update-notifier?utm_source=github&utm_medium=readme&utm_campaign=imagenudge-lite) adds compose-file scanning, webhook / ntfy-style and SMTP email alerts, JSON output and a printed list of the `docker pull` commands to run yourself. One-time payment, yours to keep. No subscription.
|
|
86
|
+
|
|
87
|
+
Lite is not a strict subset: its `0` / `1` / `2` exit codes for cron are not in the paid tool.
|
|
88
|
+
|
|
89
|
+
| Capability | Lite (free) | Paid ImageNudge |
|
|
90
|
+
| --- | --- | --- |
|
|
91
|
+
| Running containers via the local Docker socket | Yes | Yes |
|
|
92
|
+
| `docker-compose.yml` files (`--compose-file`, several at once) | No | Yes |
|
|
93
|
+
| New digest for the same tag | Yes | Yes |
|
|
94
|
+
| Newer semver tag (same suffix and style) | Yes (up to 3 tag-list pages) | Yes (up to 5 tag-list pages) |
|
|
95
|
+
| Registries | Public images, anonymous access | Public images, anonymous access |
|
|
96
|
+
| Alerts | No | Webhook / ntfy-compatible POST (`--notify-url`) and SMTP email (`--email-to`) |
|
|
97
|
+
| Output | Plain text list | Text or JSON (`--format json`) |
|
|
98
|
+
| Prints the `docker pull` commands to run (`--apply`, never runs them) | No | Yes |
|
|
99
|
+
| Exit code `1` when updates are available | Yes | No (exits `0`) |
|
|
100
|
+
| Offline `--demo` | Yes | Yes, plus a built-in `--self-test` |
|
|
101
|
+
|
|
102
|
+
Neither version pulls images, restarts containers, edits files, or reads registry credentials.
|
|
103
|
+
|
|
104
|
+
Or get every PyForge tool, current and future, with the [All-Access Pass](https://py-forge.com/pass?utm_source=github&utm_medium=readme&utm_campaign=imagenudge-lite) ($99, one payment).
|
|
105
|
+
|
|
106
|
+
## Tests
|
|
107
|
+
|
|
108
|
+
```bash
|
|
109
|
+
python3 test_imagenudge_lite.py
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
The tests are offline: a fake registry, and a tiny fake Docker API on a temporary unix socket. No Docker and no network needed.
|
|
113
|
+
|
|
114
|
+
## License
|
|
115
|
+
|
|
116
|
+
MIT (this lite version). The full ImageNudge is sold separately under its own license.
|
|
@@ -0,0 +1,144 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: imagenudge-lite
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Check running Docker containers for newer images: digest changes and newer version tags. Read-only, no pulls.
|
|
5
|
+
Author: Alessio Auretto
|
|
6
|
+
License-Expression: MIT
|
|
7
|
+
Project-URL: Homepage, https://github.com/alessio1999xx-debug/imagenudge-lite
|
|
8
|
+
Project-URL: Pro version, https://py-forge.com/products/imagenudge-container-update-notifier
|
|
9
|
+
Keywords: docker,docker-image,container-updates,image-update-checker,self-hosted,homelab,docker-registry,cli,stdlib
|
|
10
|
+
Classifier: Development Status :: 4 - Beta
|
|
11
|
+
Classifier: Environment :: Console
|
|
12
|
+
Classifier: Intended Audience :: Developers
|
|
13
|
+
Classifier: Intended Audience :: System Administrators
|
|
14
|
+
Classifier: Operating System :: POSIX
|
|
15
|
+
Classifier: Programming Language :: Python :: 3
|
|
16
|
+
Classifier: Programming Language :: Python :: 3.9
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
19
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
20
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
21
|
+
Classifier: Topic :: System :: Monitoring
|
|
22
|
+
Classifier: Topic :: System :: Systems Administration
|
|
23
|
+
Classifier: Topic :: Utilities
|
|
24
|
+
Requires-Python: >=3.9
|
|
25
|
+
Description-Content-Type: text/markdown
|
|
26
|
+
License-File: LICENSE
|
|
27
|
+
Dynamic: license-file
|
|
28
|
+
|
|
29
|
+
# imagenudge-lite: Docker image update checker for running containers, read-only
|
|
30
|
+
|
|
31
|
+
imagenudge-lite helps with a Docker image update checker for a quick "which of my containers are behind?" check on one Docker host: it lists the running containers through the local Docker socket, asks the registry whether each container's tag now points to a different image digest, and whether a newer version tag exists (for example `1.25.1` -> `1.26.0`). It prints a plain-text list and exits `1` when something can be updated, so it fits a cron job. It never pulls, restarts or edits anything. One file, Python 3.9+ standard library only, MIT.
|
|
32
|
+
|
|
33
|
+
Need compose-file scanning, webhook / ntfy / SMTP email alerts, or JSON output? That is the full [ImageNudge](https://py-forge.com/products/imagenudge-container-update-notifier?utm_source=github&utm_medium=readme&utm_campaign=imagenudge-lite) (one-time payment, yours to keep, no subscription). A table later in this README lists what lite does and what the paid tool adds. Or get every PyForge tool, current and future, with the [All-Access Pass](https://py-forge.com/pass?utm_source=github&utm_medium=readme&utm_campaign=imagenudge-lite) ($99, one payment).
|
|
34
|
+
|
|
35
|
+
- Optional `pip install`, or just download the one file. No config, no state, no agent to run.
|
|
36
|
+
- Only `GET` requests to the Docker socket (`/containers/json`, `/images/<id>/json`). Registry checks are `HEAD` on the manifest plus the tag list; no image layers are downloaded.
|
|
37
|
+
- Public images only, anonymous access (Docker Hub, and registries that hand out anonymous pull tokens, e.g. public `ghcr.io` and `quay.io` images). No credentials are read or sent.
|
|
38
|
+
- Flags: `--socket`, `--no-tags`, `--demo`, `--timeout`, `--version`. After `pip install`, use `imagenudge-lite` in place of `python3 imagenudge_lite.py`.
|
|
39
|
+
|
|
40
|
+
<!-- TODO: terminal GIF of `--demo` or a live run is still missing. Place it under the intro, before Install. Do not invent a GIF. -->
|
|
41
|
+
|
|
42
|
+
## Install
|
|
43
|
+
|
|
44
|
+
```bash
|
|
45
|
+
pip install imagenudge-lite
|
|
46
|
+
imagenudge-lite --help
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
Or download the single file (Python 3.9+, stdlib only, no extra packages):
|
|
50
|
+
|
|
51
|
+
```bash
|
|
52
|
+
curl -fsSLO https://raw.githubusercontent.com/alessio1999xx-debug/imagenudge-lite/main/imagenudge_lite.py
|
|
53
|
+
python3 imagenudge_lite.py --help
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
## See the output first (offline demo)
|
|
57
|
+
|
|
58
|
+
```bash
|
|
59
|
+
python3 imagenudge_lite.py --demo
|
|
60
|
+
# imagenudge-lite 0.1.0: demo (sample data, no Docker, no network)
|
|
61
|
+
#
|
|
62
|
+
# UPDATE gitea gitea/gitea:1.21.0 newer tag 1.21.3
|
|
63
|
+
# UPDATE redis-cache redis:7.2-alpine new digest for :7.2-alpine (b2b2b2b2b2b2 -> d4d4d4d4d4d4); newer tag 7.4-alpine
|
|
64
|
+
# OK traefik traefik:v2.10.4 digest matches :v2.10.4
|
|
65
|
+
# SKIP my-app my-app:dev no registry digest locally (built or loaded locally?)
|
|
66
|
+
#
|
|
67
|
+
# 4 container(s): 2 update(s) available, 1 up to date, 1 skipped, 0 could not be checked.
|
|
68
|
+
# Nothing was pulled or restarted. Review the changelog, then update when you choose.
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
## Check running Docker containers for newer images
|
|
72
|
+
|
|
73
|
+
```bash
|
|
74
|
+
python3 imagenudge_lite.py
|
|
75
|
+
# needs read access to /var/run/docker.sock (root, or a user in the docker group)
|
|
76
|
+
|
|
77
|
+
python3 imagenudge_lite.py --socket /run/user/1000/docker.sock # rootless Docker
|
|
78
|
+
python3 imagenudge_lite.py --no-tags # digests only, skip the tag list
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
If `DOCKER_HOST` is set to a `unix://` path it is used as the default socket. TCP / SSH Docker hosts are not supported by the lite version.
|
|
82
|
+
|
|
83
|
+
## How a Docker image update is detected
|
|
84
|
+
|
|
85
|
+
| Status | Meaning |
|
|
86
|
+
| --- | --- |
|
|
87
|
+
| `UPDATE` | The registry digest for the tag the container runs differs from the local image's digest (e.g. `:latest` or `:7.2-alpine` was rebuilt upstream), and/or a newer version tag exists |
|
|
88
|
+
| `OK` | Digest matches and no newer version tag was found |
|
|
89
|
+
| `SKIP` | Nothing to compare: container started from an image ID, pinned by digest only, or an image built/loaded locally with no registry digest |
|
|
90
|
+
| `ERROR` | The registry could not be checked (private or missing image, rate limit, no network). Shown with the reason |
|
|
91
|
+
|
|
92
|
+
Newer tags keep the same style and suffix as the tag you run: `1.25.1` is compared with `X.Y.Z` tags, `16-alpine` with `N-alpine`, `v2.10.4` with `vX.Y.Z`. Tags like `latest` or `stable` only get the digest check. The lite version reads up to 3 pages (3,000 tags) of the tag list, so on repositories with huge tag lists the "newer tag" suggestion can be lower than the real newest one. Multi-arch images are compared by their index digest, which is what `docker pull` by tag records locally.
|
|
93
|
+
|
|
94
|
+
## Exit codes for cron
|
|
95
|
+
|
|
96
|
+
| Exit code | Meaning |
|
|
97
|
+
| --- | --- |
|
|
98
|
+
| `0` | Every image that could be checked is up to date (or no running containers) |
|
|
99
|
+
| `1` | At least one container has an update available |
|
|
100
|
+
| `2` | Docker socket not reachable, bad arguments, or no image could be checked at all |
|
|
101
|
+
|
|
102
|
+
```bash
|
|
103
|
+
# crontab: check every morning at 07:00, keep the last report
|
|
104
|
+
0 7 * * * python3 /opt/imagenudge_lite.py > /var/log/imagenudge-lite.txt 2>&1
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
Scheduling is up to you (cron, a systemd timer). The lite version does not send any alerts.
|
|
108
|
+
|
|
109
|
+
## imagenudge-lite vs ImageNudge
|
|
110
|
+
|
|
111
|
+
imagenudge-lite checks the running containers on one local Docker socket and prints a plain-text list. That's it.
|
|
112
|
+
|
|
113
|
+
The full [ImageNudge](https://py-forge.com/products/imagenudge-container-update-notifier?utm_source=github&utm_medium=readme&utm_campaign=imagenudge-lite) adds compose-file scanning, webhook / ntfy-style and SMTP email alerts, JSON output and a printed list of the `docker pull` commands to run yourself. One-time payment, yours to keep. No subscription.
|
|
114
|
+
|
|
115
|
+
Lite is not a strict subset: its `0` / `1` / `2` exit codes for cron are not in the paid tool.
|
|
116
|
+
|
|
117
|
+
| Capability | Lite (free) | Paid ImageNudge |
|
|
118
|
+
| --- | --- | --- |
|
|
119
|
+
| Running containers via the local Docker socket | Yes | Yes |
|
|
120
|
+
| `docker-compose.yml` files (`--compose-file`, several at once) | No | Yes |
|
|
121
|
+
| New digest for the same tag | Yes | Yes |
|
|
122
|
+
| Newer semver tag (same suffix and style) | Yes (up to 3 tag-list pages) | Yes (up to 5 tag-list pages) |
|
|
123
|
+
| Registries | Public images, anonymous access | Public images, anonymous access |
|
|
124
|
+
| Alerts | No | Webhook / ntfy-compatible POST (`--notify-url`) and SMTP email (`--email-to`) |
|
|
125
|
+
| Output | Plain text list | Text or JSON (`--format json`) |
|
|
126
|
+
| Prints the `docker pull` commands to run (`--apply`, never runs them) | No | Yes |
|
|
127
|
+
| Exit code `1` when updates are available | Yes | No (exits `0`) |
|
|
128
|
+
| Offline `--demo` | Yes | Yes, plus a built-in `--self-test` |
|
|
129
|
+
|
|
130
|
+
Neither version pulls images, restarts containers, edits files, or reads registry credentials.
|
|
131
|
+
|
|
132
|
+
Or get every PyForge tool, current and future, with the [All-Access Pass](https://py-forge.com/pass?utm_source=github&utm_medium=readme&utm_campaign=imagenudge-lite) ($99, one payment).
|
|
133
|
+
|
|
134
|
+
## Tests
|
|
135
|
+
|
|
136
|
+
```bash
|
|
137
|
+
python3 test_imagenudge_lite.py
|
|
138
|
+
```
|
|
139
|
+
|
|
140
|
+
The tests are offline: a fake registry, and a tiny fake Docker API on a temporary unix socket. No Docker and no network needed.
|
|
141
|
+
|
|
142
|
+
## License
|
|
143
|
+
|
|
144
|
+
MIT (this lite version). The full ImageNudge is sold separately under its own license.
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
LICENSE
|
|
2
|
+
MANIFEST.in
|
|
3
|
+
README.md
|
|
4
|
+
imagenudge_lite.py
|
|
5
|
+
pyproject.toml
|
|
6
|
+
test_imagenudge_lite.py
|
|
7
|
+
imagenudge_lite.egg-info/PKG-INFO
|
|
8
|
+
imagenudge_lite.egg-info/SOURCES.txt
|
|
9
|
+
imagenudge_lite.egg-info/dependency_links.txt
|
|
10
|
+
imagenudge_lite.egg-info/entry_points.txt
|
|
11
|
+
imagenudge_lite.egg-info/top_level.txt
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
imagenudge_lite
|