# 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

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

```yaml
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:

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

Repository secret required for publishing:

```text
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:

```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.