Skip to content

Latest commit

 

History

History
94 lines (74 loc) · 4.14 KB

README.md

File metadata and controls

94 lines (74 loc) · 4.14 KB

Mooring

Update Docker and rootless Podman services from Git, using readable image tags and a JSON CLI for people, agents and systemd timers.

Early-stage software under the MIT license. Tested on both runtimes, with limited production use and no independent security audit. Contributions are welcome; support and response times are not guaranteed.

How it works

Git owns desired Compose files; each host owns its schedule, hooks and deployment records. Mooring discovers version tags, commits image-only updates, then backs up, checks readiness, recreates the selected service and verifies health. Containers keep readable tags; recorded image IDs preserve the approved bytes for rollback.

Initial deployments and configuration changes require explicit apply. Stateful services require a backup hook. Use idle/drain hooks or explicitly allow interruption during a quiet window. Image rollback requires declared data compatibility and cannot undo database migrations. Operations covers policies, hooks, supported Compose features and recovery.

Get started

Requires Python 3.11+, uv, Git, Skopeo and Docker Compose v2 or rootless Podman with podman-compose. Run as the runtime owner.

git clone https://github.com/KyleDerZweite/mooring.git
cd mooring
uv tool install .
mkdir -p ~/.config/mooring ~/services/example
cp examples/host.json ~/.config/mooring/host.json

Edit the host config to point at your existing deployment repository and its Compose file. The example is a stateless web service; configure backup and health hooks for your own workload. Keep credentials and private host state outside Git.

mooring services
mooring plan example
mooring apply example --revision <revision-from-plan>
mooring status example
mooring update example             # discover a version without committing
mooring update example --commit    # commit the image tag without deploying
mooring update example --now       # publish and deploy the latest allowed stable tag now
mooring update example --now --version 1.2.3 # select this exact stable tag
mooring run                        # run enabled automatic policies

update --now bypasses the automatic window and release-age delays for this invocation. It keeps the configured semver level unless --version TAG selects an exact higher stable tag in the same image repository and tag family. Use the complete tag, including any prefix or suffix. Existing Git image changes take precedence over discovery; a conflicting requested tag stops the command. It retains backup, health, locks and drift checks, and requires previously applied Compose and host policy. Initial deployment and configuration adoption still use apply. A healthy selected version is a no-op, not a restart or same-tag repull.

If publication succeeds but deployment fails, JSON includes published_revision, phase and recovery guidance. Retry the same command to finish that retained target and digest; it will not discover a newer release. Interrupted deployments require recover. See the agent guide for the error contract.

For scheduling, follow host setup: install the example user units, enable lingering, and verify the timer after a successful explicit deployment. For agent-driven deployment, read the agent guide.

Development

CI checks Python 3.11 and 3.14 with uv 0.11.16. Use the committed lockfile for development; Dependabot checks uv dependencies and GitHub Actions weekly.

uv sync --locked --group dev
uv run --locked pytest
uv run --locked ruff check .
uv run --locked ruff format --check .

To refresh compatible dependencies deliberately, run uv lock --upgrade, then repeat the checks above and include uv.lock in the change.

On an authorized test host with Docker and rootless Podman:

MOORING_INTEGRATION=1 uv run --locked pytest -q tests/test_integration.py

Integration tests create disposable containers, volumes and a loopback registry. See validation for tested versions and limits, and security for private vulnerability reporting.