Add docker-compose-update tool for automated stack updates

[Copilot]

Adds docker-compose-update package that updates Docker Compose stacks with parallel execution and concurrency control. Updates running projects by default or scans filesystem with --all.

Implementation

• Detection modes

  • Default: queries container labels (com.docker.compose.project.working_dir) for running projects
  • --all: finds compose files via recursive search (home directory default, configurable with --root)

• Execution model

  • Parallel updates via xargs -P (CPU count default, override with --jobs)
  • Lock file (/var/lock/docker-compose-update.lock) prevents concurrent runs
  • Commands execute in project directory to respect overrides and .env files

• Docker operations

  • Pull: docker compose pull
  • Update: docker compose up -d --force-recreate --remove-orphans
  • Cleanup: docker system prune -a --volumes --force (once at end, per-project, or disabled)

CLI

# Update running projects
docker-compose-update

# Update all projects in home directory with 4 parallel jobs
docker-compose-update --all -j 4

# Scan custom directory with dry-run
docker-compose-update --all --root /srv --dry-run

Options: --all, --root DIR, --max-depth N, --jobs N, --no-prune, --prune-each, --dry-run, --help

Technical notes

• Null-delimited paths (xargs -0) handle spaces in directory names
• trap handlers ensure lock release and popd cleanup on exit/error
• Strict mode (set -euo pipefail) with proper error propagation

Original prompt

Create a new package for punppis/linux-utils that provides a robust Debian/Ubuntu-friendly bash tool to update Docker Compose stacks.

Background / current state:

• This repo is a collection of bash tools under packages/ and a create-package helper.
• User wants a tool that:
  • By default updates ONLY currently running Docker Compose projects.
  • With --all, scans for compose files (docker-compose.yml etc.) and updates all found projects.
  • Must execute compose commands from the correct working directory because stacks may rely on overrides (compose.override.yml) and local .env/relative paths.

Requirements:

1. Add a new package folder under packages/ (choose an appropriate name, e.g. docker-compose-update or similar) containing an executable bash script.
2. Script behavior:
   • Default mode (no args):
     • Detect running compose projects using Docker container labels (e.g. com.docker.compose.project.working_dir).
     • For each unique working directory found, cd into that directory and run:
       • docker compose pull
       • docker compose up -d --force-recreate --remove-orphans
   • --all mode:
     • Scan for compose files under a configurable root directory (default /opt) with configurable max depth (default 6).
     • For each compose file found, derive its directory, cd there, and run the same compose commands.
   • Provide CLI options:
     • --all
     • --root DIR
     • --max-depth N
     • --no-prune
     • --prune-each
     • --dry-run
     • --help
   • Docker cleanup:
     • Use docker system prune -a --volumes --force (correct flags).
     • Default: prune once at the end; optional per-project with --prune-each; can be disabled with --no-prune.
   • Add clear comments, Debian/Ubuntu assumptions, and strict-mode (set -euo pipefail).
   • Validate dependencies (docker + docker compose plugin).
   • Keep implementation portable for Debian/Ubuntu/Raspberry Pi.
3. Update repo documentation as appropriate (e.g. README Tools section) to mention the new package and basic usage.
4. Ensure the new script is executable and follows the style of existing packages.

Relevant existing files:

• create-package in repo root.
• Existing example package packages/docker-compose-update/docker-compose-update currently contains a placeholder hello-world script; replace it with the real implementation.

Acceptance criteria:

• Running packages/docker-compose-update/docker-compose-update with no args updates only running compose projects (based on container labels).
• Running with --all scans for compose files and updates each project directory.
• Commands are executed from the correct directory.
• Prune uses correct flags and defaults to once at end.
• --dry-run prints commands without executing.
• README updated with usage examples.

This pull request was created from Copilot chat.

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.