Initial Dockge image update checker

README.md

@@ -0,0 +1,79 @@
+# Dockge Image Update Checker
+
+Companion service for Dockge that checks images used by stack compose files against registry manifest digests and reports whether the locally used image digest is behind.
+
+Dockge already has an update button per stack. This project focuses on the missing scheduled/read-only check: it tells you which stacks likely have image updates available without redeploying anything.
+
+<p align="center"><img src="https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/rainbow.png" alt="-----------------------------------------------------" width="100%"></p>
+
+## Features
+
+- Scans Dockge stack folders for `compose.yaml`, `compose.yml`, `docker-compose.yaml`, and `docker-compose.yml`.
+- Extracts `image:` references from services.
+- Queries OCI/Docker Registry v2 manifests and compares remote digests to Docker Engine `RepoDigests`.
+- Exposes a small HTTP API for dashboards, notifications, or future Dockge integration.
+- Runs without package dependencies.
+- Does not pull images, restart containers, or modify compose files.
+
+## API
+
+```text
+GET /healthz
+GET /api/stacks
+GET /api/check
+GET /api/check?stack=example
+```
+
+`/api/check` returns JSON with one result per service image:
+
+```json
+{
+  "checkedAt": "2026-05-14T12:00:00.000Z",
+  "stacksDir": "/opt/stacks",
+  "summary": {
+    "total": 2,
+    "updatesAvailable": 1,
+    "unknown": 0,
+    "errors": 0
+  },
+  "results": []
+}
+```
+
+<p align="center"><img src="https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/rainbow.png" alt="-----------------------------------------------------" width="100%"></p>
+
+## Docker Compose
+
+```yaml
+services:
+  dockge-image-update-checker:
+    build: .
+    container_name: dockge-image-update-checker
+    restart: unless-stopped
+    ports:
+      - "8080:8080"
+    environment:
+      STACKS_DIR: /opt/stacks
+      CHECK_INTERVAL_SECONDS: 3600
+    volumes:
+      - /opt/stacks:/opt/stacks:ro
+      - /var/run/docker.sock:/var/run/docker.sock:ro
+```
+
+## Local Development
+
+```bash
+npm test
+npm run build
+npm start
+```
+
+For a one-shot JSON check:
+
+```bash
+STACKS_DIR=/opt/stacks npm run check
+```
+
+## Status
+
+This is a first working implementation. It is intentionally read-only and registry support starts with public registries that follow the standard bearer-token flow.