home-services/README.md

Home Services

This repository manages home-lab application stacks using compose files and a small Python CLI that works with either Docker or Podman.

Repository layout

services/
  media/
    compose.yaml
composectl.py
update_containers.sh

• services/ contains one directory per deployed stack.
• Each stack directory contains its own compose.yaml file.
• composectl.py infers the stack name, compose file path, and project name from that directory structure.
• update_containers.sh is a compatibility shim that delegates to the Python tool.

Runtime support

The CLI detects and uses whichever runtime is available:

• docker compose ...
• podman compose ...

This means the same service directories can be managed from either backend without changing the compose files.

Common commands

From the repository root:

python3 composectl.py --help
python3 composectl.py --dry-run --all refresh
python3 composectl.py --stack media --dry-run up
python3 composectl.py --stack media pull
python3 composectl.py --stack media down
python3 composectl.py --stack media status

The shell entrypoint delegates to the Python tool:

bash update_containers.sh --dry-run --all refresh

Refresh flow

The repo-wide refresh flow does the following for each configured stack:

1. pull
2. down
3. up -d
4. prune

This preserves the same maintenance behavior as the old shell updater, but moves the logic into a portable Python implementation.