jwa91/vps-dependency-overview

Dependency Overview (Docker-compose monorepo)

Inventory script that walks a services/ directory of Docker-compose stacks and produces a Markdown or JSON report of:

• Compose images — image: references with tag/digest, classified by pinning quality (floating, implicit-latest, major, minor, semver, digest, custom)
• Build services — FROM lines from Dockerfiles, useful for spotting outdated base images
• Runtime hints — Node/Python versions inferred from .nvmrc, .node-version, .python-version, package.json engines, pyproject.toml
• Dependency manager signals — which lockfiles exist (pnpm-lock.yaml, package-lock.json, poetry.lock, uv.lock, …)
• Per-service update-check skills — <service>/.agents/skills/*-update-check/ if you've put deeper version-checking skills next to each service

It does not hit the network. It answers "what am I using?", not "what's the latest?".

Quick Start

From the repo root, with docker compose (v2) available locally:

python3 .agents/skills/vps-dependency-overview/scripts/vps_dependency_overview.py \
  --format markdown \
  --output /tmp/dependency-overview.md

Print to stdout instead:

python3 .agents/skills/vps-dependency-overview/scripts/vps_dependency_overview.py --format markdown

Focus on specific service folders:

python3 .agents/skills/vps-dependency-overview/scripts/vps_dependency_overview.py --only n8n --only postgres

JSON output for downstream tooling:

python3 .agents/skills/vps-dependency-overview/scripts/vps_dependency_overview.py --format json

Flags

| Flag | Default | Description | | ---------------- | ---------- | ------------------------------------------------------ | | --root | . | Workspace root | | --services-dir | services | Subdirectory containing per-service folders | | --format | markdown | markdown or json | | --output | stdout | Write to a file instead of stdout | | --only NAME | all | Restrict to specific service folder names (repeatable) |

Expected layout

<root>/
  <services-dir>/             # default: services/
    <service-a>/
      docker-compose.yml      # required for the service to be inventoried
      Dockerfile              # optional, parsed if present
      .nvmrc / .python-version / package.json / pyproject.toml   # optional, parsed for runtime hints
      .agents/skills/<svc>-update-check/SKILL.md                 # optional, surfaced in the report
    <service-b>/
      ...

A service folder without docker-compose.yml is skipped silently.

Requirements

• Python 3.11+ (uses tomllib)
• docker with Compose v2 (the script invokes docker compose -f … config --format json to resolve compose files; no images are pulled or built)

Optional: live container versions on a remote host

The script reports desired versions (what the compose files say). To compare against actually running versions on a remote VPS, run separately:

ssh <vps-host> "docker ps --format 'table {{.Names}}\t{{.Image}}\t{{.Status}}'"

Replace <vps-host> with your SSH alias from ~/.ssh/config.

How to read the report

| Pinning class | What it means | Reproducibility | | ----------------- | -------------------------------------------- | ------------------------------------------ | | digest | image@sha256:… | Best — content-addressed | | semver | 1.2.3, v1.2.3, 1.2.3-alpine | Good — explicit version | | minor | 1.2, 1.2-alpine | Major+minor pinned, patches float | | major | 22, 3-slim | Major pinned, minor+patch float on rebuild | | floating | latest, main, master, edge, stable | Bad — non-reproducible | | implicit-latest | no tag at all | Bad — equivalent to :latest | | custom | anything else | Worth a manual look |

Runtime fields:

• node_container / python_container — inferred from Dockerfile FROM lines (the runtime your container actually runs)
• node_repo / python_repo — inferred from .nvmrc/.python-version (what dev tooling expects)
• node_engine / python_requires — explicit constraints from package.json/pyproject.toml

A common red flag: node_container=18 while node_repo=22 means your dev environment and your container are on different majors.