dockge-image-update-checker/README.md

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.

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

GET /healthz
GET /api/stacks
GET /api/check
GET /api/check?stack=example

/api/check returns JSON with one result per service image:

{
  "checkedAt": "2026-05-14T12:00:00.000Z",
  "stacksDir": "/opt/stacks",
  "summary": {
    "total": 2,
    "updatesAvailable": 1,
    "unknown": 0,
    "errors": 0
  },
  "results": []
}

Docker Compose

For Dockge, use the registry-backed compose file from this repository:

services:
  dockge-image-update-checker:
    image: git.wilkensxl.de/mrsphay/dockge-image-update-checker:latest
    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

If your Dockge stacks directory is not /opt/stacks, change both the host-side volume path and STACKS_DIR.

The Gitea workflow publishes this image to the registry:

git.wilkensxl.de/mrsphay/dockge-image-update-checker:latest

Repository secret required for publishing:

REGISTRY_TOKEN

REGISTRY_TOKEN must be a Gitea access token for MrSphay with package write access.

For local development you can still build from source:

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

npm test
npm run build
npm start

For a one-shot JSON check:

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.