compose-farm 0.1.0__tar.gz

compose_farm-0.1.0/.envrc

@@ -0,0 +1 @@
+source .venv/bin/activate

compose_farm-0.1.0/.github/release-drafter.yml

@@ -0,0 +1,4 @@
+template: |
+  ## What’s Changed
+
+  $CHANGES

compose_farm-0.1.0/.github/renovate.json

@@ -0,0 +1,35 @@
+{
+    "$schema": "https://docs.renovatebot.com/renovate-schema.json",
+    "rebaseWhen": "behind-base-branch",
+    "dependencyDashboard": true,
+    "labels": [
+        "dependencies",
+        "no-stale"
+    ],
+    "commitMessagePrefix": "⬆️",
+    "commitMessageTopic": "{{depName}}",
+    "prBodyDefinitions": {
+        "Release": "yes"
+    },
+    "packageRules": [
+        {
+            "matchManagers": [
+                "github-actions"
+            ],
+            "addLabels": [
+                "github_actions"
+            ],
+            "rangeStrategy": "pin"
+        },
+        {
+            "matchManagers": [
+                "github-actions"
+            ],
+            "matchUpdateTypes": [
+                "minor",
+                "patch"
+            ],
+            "automerge": true
+        }
+    ]
+}

compose_farm-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,60 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        python-version: ["3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync --all-extras --dev
+
+      - name: Run tests
+        run: uv run pytest
+
+      - name: Upload coverage reports to Codecov
+        if: matrix.os == 'ubuntu-latest' && matrix.python-version == '3.13'
+        uses: codecov/codecov-action@v5
+        env:
+          CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
+
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+
+      - name: Set up Python
+        run: uv python install 3.12
+
+      - name: Install dependencies
+        run: uv sync --all-extras --dev
+
+      - name: Run ruff check
+        run: uv run ruff check .
+
+      - name: Run ruff format check
+        run: uv run ruff format --check .
+
+      - name: Run mypy
+        run: uv run mypy src/compose_farm

compose_farm-0.1.0/.github/workflows/release-drafter.yml

@@ -0,0 +1,14 @@
+name: Release Drafter
+
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  update_release_draft:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: release-drafter/release-drafter@v6
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

compose_farm-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,22 @@
+name: Upload Python Package
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/${{ github.repository }}
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+      - name: Build
+        run: uv build
+      - name: Publish package distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

compose_farm-0.1.0/.github/workflows/renovate.json

@@ -0,0 +1,35 @@
+{
+    "$schema": "https://docs.renovatebot.com/renovate-schema.json",
+    "rebaseWhen": "behind-base-branch",
+    "dependencyDashboard": true,
+    "labels": [
+        "dependencies",
+        "no-stale"
+    ],
+    "commitMessagePrefix": "⬆️",
+    "commitMessageTopic": "{{depName}}",
+    "prBodyDefinitions": {
+        "Release": "yes"
+    },
+    "packageRules": [
+        {
+            "matchManagers": [
+                "github-actions"
+            ],
+            "addLabels": [
+                "github_actions"
+            ],
+            "rangeStrategy": "pin"
+        },
+        {
+            "matchManagers": [
+                "github-actions"
+            ],
+            "matchUpdateTypes": [
+                "minor",
+                "patch"
+            ],
+            "automerge": true
+        }
+    ]
+}

compose_farm-0.1.0/.github/workflows/toc.yaml

@@ -0,0 +1,10 @@
+on: push
+name: TOC Generator
+jobs:
+  generateTOC:
+    name: TOC Generator
+    runs-on: ubuntu-latest
+    steps:
+      - uses: technote-space/toc-generator@v4
+        with:
+          TOC_TITLE: ""

compose_farm-0.1.0/.github/workflows/update-readme.yml

@@ -0,0 +1,53 @@
+name: Update README.md
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+
+jobs:
+  update_readme:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+          fetch-depth: 0
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+
+      - name: Run markdown-code-runner
+        env:
+          TERM: dumb
+          NO_COLOR: 1
+          TERMINAL_WIDTH: 90
+        run: |
+          uvx --with . markdown-code-runner README.md
+          sed -i 's/[[:space:]]*$//' README.md
+
+      - name: Commit updated README.md
+        id: commit
+        run: |
+          git add README.md
+          git config --local user.email "github-actions[bot]@users.noreply.github.com"
+          git config --local user.name "github-actions[bot]"
+          if git diff --quiet && git diff --staged --quiet; then
+            echo "No changes in README.md, skipping commit."
+            echo "commit_status=skipped" >> $GITHUB_ENV
+          else
+            git commit -m "Update README.md"
+            echo "commit_status=committed" >> $GITHUB_ENV
+          fi
+
+      - name: Push changes
+        if: env.commit_status == 'committed'
+        uses: ad-m/github-push-action@master
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          branch: ${{ github.head_ref || github.ref_name }}

compose_farm-0.1.0/.gitignore

@@ -0,0 +1,44 @@
+# Python
+__pycache__/
+src/compose_farm/_version.py
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+.DS_Store
+
+# Testing
+.coverage
+.pytest_cache/
+htmlcov/
+
+# Local config (don't commit real configs)
+compose-farm.yaml
+!examples/compose-farm.yaml
+coverage.xml

compose_farm-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,27 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-added-large-files
+      - id: check-merge-conflict
+      - id: debug-statements
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.8.4
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v1.14.0
+    hooks:
+      - id: mypy
+        additional_dependencies:
+          - pydantic>=2.0.0
+          - typer>=0.9.0
+          - asyncssh>=2.14.0
+          - types-PyYAML

compose_farm-0.1.0/.python-version

@@ -0,0 +1 @@
+3.14

compose_farm-0.1.0/AGENTS.md

@@ -0,0 +1 @@
+CLAUDE.md

compose_farm-0.1.0/CLAUDE.md

@@ -0,0 +1,47 @@
+# Compose Farm Development Guidelines
+
+## Core Principles
+
+- **KISS**: Keep it simple. This is a thin wrapper around `docker compose` over SSH.
+- **YAGNI**: Don't add features until they're needed. No orchestration, no service discovery, no health checks.
+- **DRY**: Reuse patterns. Common CLI options are defined once, SSH logic is centralized.
+
+## Architecture
+
+```
+compose_farm/
+├── config.py  # Pydantic models, YAML loading
+├── ssh.py     # asyncssh execution, streaming
+└── cli.py     # Typer commands
+```
+
+## Key Design Decisions
+
+1. **asyncssh over Paramiko/Fabric**: Native async support, built-in streaming
+2. **Parallel by default**: Multiple services run concurrently via `asyncio.gather`
+3. **Streaming output**: Real-time stdout/stderr with `[service]` prefix
+4. **SSH key auth only**: Uses ssh-agent, no password handling (YAGNI)
+5. **NFS assumption**: Compose files at same path on all hosts
+6. **Local execution**: When host is `localhost`/`local`, skip SSH and run locally
+
+## Communication Notes
+
+- Clarify ambiguous wording (e.g., homophones like "right"/"write", "their"/"there").
+
+## Git Safety
+
+- Never amend commits.
+- Never merge into a branch; prefer fast-forward or rebase as directed.
+- Never force push.
+
+## Commands Quick Reference
+
+| Command | Docker Compose Equivalent |
+|---------|--------------------------|
+| `up`    | `docker compose up -d`   |
+| `down`  | `docker compose down`    |
+| `pull`  | `docker compose pull`    |
+| `restart` | `down` + `up -d`       |
+| `update` | `pull` + `down` + `up -d` |
+| `logs`  | `docker compose logs`    |
+| `ps`    | `docker compose ps`      |

compose_farm-0.1.0/GEMINI.md

@@ -0,0 +1 @@
+CLAUDE.md

compose_farm-0.1.0/PKG-INFO

@@ -0,0 +1,196 @@
+Metadata-Version: 2.4
+Name: compose-farm
+Version: 0.1.0
+Summary: Compose Farm - run docker compose commands across multiple hosts
+Author-email: Bas Nijholt <bas@nijho.lt>
+Requires-Python: >=3.11
+Requires-Dist: asyncssh>=2.14.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: typer>=0.9.0
+Description-Content-Type: text/markdown
+
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+
+- [Compose Farm](#compose-farm)
+  - [Why Compose Farm?](#why-compose-farm)
+  - [Key Assumption: Shared Storage](#key-assumption-shared-storage)
+  - [Installation](#installation)
+  - [Configuration](#configuration)
+  - [Usage](#usage)
+  - [Traefik Multihost Ingress (File Provider)](#traefik-multihost-ingress-file-provider)
+  - [Requirements](#requirements)
+  - [How It Works](#how-it-works)
+  - [License](#license)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+# Compose Farm
+
+A minimal CLI tool to run Docker Compose commands across multiple hosts via SSH.
+
+## Why Compose Farm?
+
+I run 100+ Docker Compose stacks on an LXC container that frequently runs out of memory. I needed a way to distribute services across multiple machines without the complexity of:
+
+- **Kubernetes**: Overkill for my use case. I don't need pods, services, ingress controllers, or YAML manifests 10x the size of my compose files.
+- **Docker Swarm**: Effectively in maintenance mode—no longer being invested in by Docker.
+
+**Compose Farm is intentionally simple**: one YAML config mapping services to hosts, and a CLI that runs `docker compose` commands over SSH. That's it.
+
+## Key Assumption: Shared Storage
+
+Compose Farm assumes **all your compose files are accessible at the same path on all hosts**. This is typically achieved via:
+
+- **NFS mount** (e.g., `/opt/compose` mounted from a NAS)
+- **Synced folders** (e.g., Syncthing, rsync)
+- **Shared filesystem** (e.g., GlusterFS, Ceph)
+
+```
+# Example: NFS mount on all hosts
+nas:/volume1/compose  →  /opt/compose (on nas01)
+nas:/volume1/compose  →  /opt/compose (on nas02)
+nas:/volume1/compose  →  /opt/compose (on nas03)
+```
+
+Compose Farm simply runs `docker compose -f /opt/compose/{service}/docker-compose.yml` on the appropriate host—it doesn't copy or sync files.
+
+## Installation
+
+```bash
+pip install compose-farm
+# or
+uv pip install compose-farm
+```
+
+## Configuration
+
+Create `~/.config/compose-farm/compose-farm.yaml` (or `./compose-farm.yaml` in your working directory):
+
+```yaml
+compose_dir: /opt/compose  # Must be the same path on all hosts
+
+hosts:
+  nas01:
+    address: 192.168.1.10
+    user: docker
+  nas02:
+    address: 192.168.1.11
+    # user defaults to current user
+  local: localhost  # Run locally without SSH
+
+services:
+  plex: nas01
+  jellyfin: nas02
+  sonarr: nas01
+  radarr: local  # Runs on the machine where you invoke compose-farm
+```
+
+Compose files are expected at `{compose_dir}/{service}/docker-compose.yml`.
+
+## Usage
+
+```bash
+# Start services
+compose-farm up plex jellyfin
+compose-farm up --all
+
+# Stop services
+compose-farm down plex
+
+# Pull latest images
+compose-farm pull --all
+
+# Restart (down + up)
+compose-farm restart plex
+
+# Update (pull + down + up) - the end-to-end update command
+compose-farm update --all
+
+# Capture image digests to a TOML log (per service or all)
+compose-farm snapshot plex
+compose-farm snapshot --all  # writes ~/.config/compose-farm/dockerfarm-log.toml
+
+# View logs
+compose-farm logs plex
+compose-farm logs -f plex  # follow
+
+# Show status
+compose-farm ps
+```
+
+## Traefik Multihost Ingress (File Provider)
+
+If you run a single Traefik instance on one “front‑door” host and want it to route to
+Compose Farm services on other hosts, Compose Farm can generate a Traefik file‑provider
+fragment from your existing compose labels.
+
+**How it works**
+
+- Your `docker-compose.yml` remains the source of truth. Put normal `traefik.*` labels on
+  the container you want exposed.
+- Labels and port specs may use `${VAR}` / `${VAR:-default}`; Compose Farm resolves these
+  using the stack’s `.env` file and your current environment, just like Docker Compose.
+- Publish a host port for that container (via `ports:`). The generator prefers
+  host‑published ports so Traefik can reach the service across hosts; if none are found,
+  it warns and you’d need L3 reachability to container IPs.
+- If a router label doesn’t specify `traefik.http.routers.<name>.service` and there’s only
+  one Traefik service defined on that container, Compose Farm wires the router to it.
+- `compose-farm.yaml` stays unchanged: just `hosts` and `services: service → host`.
+
+Example `docker-compose.yml` pattern:
+
+```yaml
+services:
+  plex:
+    ports: ["32400:32400"]
+    labels:
+      - traefik.enable=true
+      - traefik.http.routers.plex.rule=Host(`plex.lab.mydomain.org`)
+      - traefik.http.routers.plex.entrypoints=websecure
+      - traefik.http.routers.plex.tls.certresolver=letsencrypt
+      - traefik.http.services.plex.loadbalancer.server.port=32400
+```
+
+**One‑time Traefik setup**
+
+Enable a file provider watching a directory (any path is fine; a common choice is on your
+shared/NFS mount):
+
+```yaml
+providers:
+  file:
+    directory: /mnt/data/traefik/dynamic.d
+    watch: true
+```
+
+**Generate the fragment**
+
+```bash
+compose-farm traefik-file --output /mnt/data/traefik/dynamic.d/compose-farm.generated.yml
+```
+
+Re‑run this after changing Traefik labels, moving a service to another host, or changing
+published ports.
+
+## Requirements
+
+- Python 3.11+
+- SSH key-based authentication to your hosts (uses ssh-agent)
+- Docker and Docker Compose installed on all target hosts
+- **Shared storage**: All compose files at the same path on all hosts (NFS, Syncthing, etc.)
+
+## How It Works
+
+1. You run `compose-farm up plex`
+2. Compose Farm looks up which host runs `plex` (e.g., `nas01`)
+3. It SSHs to `nas01` (or runs locally if `localhost`)
+4. It executes `docker compose -f /opt/compose/plex/docker-compose.yml up -d`
+5. Output is streamed back with `[plex]` prefix
+
+That's it. No orchestration, no service discovery, no magic.
+
+## License
+
+MIT

compose_farm-0.1.0/PLAN.md

@@ -0,0 +1,35 @@
+# Compose Farm – Traefik Multihost Ingress Plan
+
+## Goal
+Generate a Traefik file-provider fragment from existing docker-compose Traefik labels (no config duplication) so a single front-door Traefik on 192.168.1.66 with wildcard `*.lab.mydomain.org` can route to services running on other hosts. Keep the current simplicity (SSH + docker compose); no Swarm/K8s.
+
+## Requirements
+- Traefik stays on main host; keep current `dynamic.yml` and Docker provider for local containers.
+- Add a watched directory provider (any path works) and load a generated fragment (e.g., `compose-farm.generated.yml`).
+- No edits to compose files: reuse existing `traefik.*` labels as the single source of truth; Compose Farm only reads them.
+- Generator infers routing from labels and reachability from `ports:` mappings; prefer host-published ports so Traefik can reach services across hosts. Upstreams point to `<host address>:<published host port>`; warn if no published port is found.
+- Only minimal data in `compose-farm.yaml`: hosts map and service→host mapping (already present).
+- No new orchestration/discovery layers; respect KISS/YAGNI/DRY.
+
+## Non-Goals
+- No Swarm/Kubernetes adoption.
+- No global Docker provider across hosts.
+- No health checks/service discovery layer.
+
+## Current State (Dec 2025)
+- Compose Farm: Typer CLI wrapping `docker compose` over SSH; config in `compose-farm.yaml`; parallel by default; snapshot/log tooling present.
+- Traefik: single instance on 192.168.1.66, wildcard `*.lab.mydomain.org`, Docker provider for local services, file provider via `dynamic.yml` already in use.
+
+## Proposed Implementation Steps
+1) Add generator command: `compose-farm traefik-file --output <path>`.
+2) Resolve per-service host from `compose-farm.yaml`; read compose file at `{compose_dir}/{service}/docker-compose.yml`.
+3) Parse `traefik.*` labels to build routers/services/middlewares as in compose; map container port to published host port (from `ports:`) to form upstream URLs with host address.
+4) Emit file-provider YAML to the watched directory (recommended default: `/mnt/data/traefik/dynamic.d/compose-farm.generated.yml`, but user chooses via `--output`).
+5) Warnings: if no published port is found, warn that cross-host reachability requires L3 reachability to container IPs.
+6) Tests: label parsing, port mapping, YAML render; scenario with published port; scenario without published port.
+7) Docs: update README/CLAUDE to describe directory provider flags and the generator workflow; note that compose files remain unchanged.
+
+## Open Questions
+- How to derive target host address: use `hosts.<name>.address` verbatim, or allow override per service? (Default: use host address.)
+- Should we support multiple hosts/backends per service for LB/HA? (Start with single server.)
+- Where to store generated file by default? (Default to user-specified `--output`; maybe fallback to `./compose-farm-traefik.yml`.)