compose-farm 0.1.0__py3-none-any.whl

compose_farm/__init__.py

@@ -0,0 +1,9 @@
+"""Compose Farm - run docker compose commands across multiple hosts."""
+
+try:
+    from compose_farm._version import __version__, __version_tuple__
+except ImportError:
+    __version__ = "0.0.0"
+    __version_tuple__ = (0, 0, 0)
+
+__all__ = ["__version__", "__version_tuple__"]

compose_farm/_version.py

@@ -0,0 +1,34 @@
+# file generated by setuptools-scm
+# don't change, don't track in version control
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+TYPE_CHECKING = False
+if TYPE_CHECKING:
+    from typing import Tuple
+    from typing import Union
+
+    VERSION_TUPLE = Tuple[Union[int, str], ...]
+    COMMIT_ID = Union[str, None]
+else:
+    VERSION_TUPLE = object
+    COMMIT_ID = object
+
+version: str
+__version__: str
+__version_tuple__: VERSION_TUPLE
+version_tuple: VERSION_TUPLE
+commit_id: COMMIT_ID
+__commit_id__: COMMIT_ID
+
+__version__ = version = '0.1.0'
+__version_tuple__ = version_tuple = (0, 1, 0)
+
+__commit_id__ = commit_id = None

compose_farm/cli.py

@@ -0,0 +1,247 @@
+"""CLI interface using Typer."""
+
+from __future__ import annotations
+
+import asyncio
+from pathlib import Path
+from typing import TYPE_CHECKING, Annotated, TypeVar
+
+import typer
+import yaml
+
+from . import __version__
+from .config import Config, load_config
+from .logs import snapshot_services
+from .ssh import (
+    CommandResult,
+    run_on_services,
+    run_sequential_on_services,
+)
+
+if TYPE_CHECKING:
+    from collections.abc import Coroutine
+
+T = TypeVar("T")
+
+def _version_callback(value: bool) -> None:
+    """Print version and exit."""
+    if value:
+        typer.echo(f"compose-farm {__version__}")
+        raise typer.Exit
+
+
+app = typer.Typer(
+    name="compose-farm",
+    help="Compose Farm - run docker compose commands across multiple hosts",
+    no_args_is_help=True,
+)
+
+
+@app.callback()
+def main(
+    version: Annotated[
+        bool,
+        typer.Option(
+            "--version",
+            "-v",
+            help="Show version and exit",
+            callback=_version_callback,
+            is_eager=True,
+        ),
+    ] = False,
+) -> None:
+    """Compose Farm - run docker compose commands across multiple hosts."""
+
+
+def _get_services(
+    services: list[str],
+    all_services: bool,
+    config_path: Path | None,
+) -> tuple[list[str], Config]:
+    """Resolve service list and load config."""
+    config = load_config(config_path)
+
+    if all_services:
+        return list(config.services.keys()), config
+    if not services:
+        typer.echo("Error: Specify services or use --all", err=True)
+        raise typer.Exit(1)
+    return list(services), config
+
+
+def _run_async(coro: Coroutine[None, None, T]) -> T:
+    """Run async coroutine."""
+    return asyncio.run(coro)
+
+
+def _report_results(results: list[CommandResult]) -> None:
+    """Report command results and exit with appropriate code."""
+    failed = [r for r in results if not r.success]
+    if failed:
+        for r in failed:
+            typer.echo(f"[{r.service}] Failed with exit code {r.exit_code}", err=True)
+        raise typer.Exit(1)
+
+
+ServicesArg = Annotated[
+    list[str] | None,
+    typer.Argument(help="Services to operate on"),
+]
+AllOption = Annotated[
+    bool,
+    typer.Option("--all", "-a", help="Run on all services"),
+]
+ConfigOption = Annotated[
+    Path | None,
+    typer.Option("--config", "-c", help="Path to config file"),
+]
+LogPathOption = Annotated[
+    Path | None,
+    typer.Option("--log-path", "-l", help="Path to Dockerfarm TOML log"),
+]
+
+
+@app.command()
+def up(
+    services: ServicesArg = None,
+    all_services: AllOption = False,
+    config: ConfigOption = None,
+) -> None:
+    """Start services (docker compose up -d)."""
+    svc_list, cfg = _get_services(services or [], all_services, config)
+    results = _run_async(run_on_services(cfg, svc_list, "up -d"))
+    _report_results(results)
+
+
+@app.command()
+def down(
+    services: ServicesArg = None,
+    all_services: AllOption = False,
+    config: ConfigOption = None,
+) -> None:
+    """Stop services (docker compose down)."""
+    svc_list, cfg = _get_services(services or [], all_services, config)
+    results = _run_async(run_on_services(cfg, svc_list, "down"))
+    _report_results(results)
+
+
+@app.command()
+def pull(
+    services: ServicesArg = None,
+    all_services: AllOption = False,
+    config: ConfigOption = None,
+) -> None:
+    """Pull latest images (docker compose pull)."""
+    svc_list, cfg = _get_services(services or [], all_services, config)
+    results = _run_async(run_on_services(cfg, svc_list, "pull"))
+    _report_results(results)
+
+
+@app.command()
+def restart(
+    services: ServicesArg = None,
+    all_services: AllOption = False,
+    config: ConfigOption = None,
+) -> None:
+    """Restart services (down + up)."""
+    svc_list, cfg = _get_services(services or [], all_services, config)
+    results = _run_async(run_sequential_on_services(cfg, svc_list, ["down", "up -d"]))
+    _report_results(results)
+
+
+@app.command()
+def update(
+    services: ServicesArg = None,
+    all_services: AllOption = False,
+    config: ConfigOption = None,
+) -> None:
+    """Update services (pull + down + up)."""
+    svc_list, cfg = _get_services(services or [], all_services, config)
+    results = _run_async(run_sequential_on_services(cfg, svc_list, ["pull", "down", "up -d"]))
+    _report_results(results)
+
+
+@app.command()
+def logs(
+    services: ServicesArg = None,
+    all_services: AllOption = False,
+    follow: Annotated[bool, typer.Option("--follow", "-f", help="Follow logs")] = False,
+    tail: Annotated[int, typer.Option("--tail", "-n", help="Number of lines")] = 100,
+    config: ConfigOption = None,
+) -> None:
+    """Show service logs."""
+    svc_list, cfg = _get_services(services or [], all_services, config)
+    cmd = f"logs --tail {tail}"
+    if follow:
+        cmd += " -f"
+    results = _run_async(run_on_services(cfg, svc_list, cmd))
+    _report_results(results)
+
+
+@app.command()
+def ps(
+    config: ConfigOption = None,
+) -> None:
+    """Show status of all services."""
+    cfg = load_config(config)
+    results = _run_async(run_on_services(cfg, list(cfg.services.keys()), "ps"))
+    _report_results(results)
+
+
+@app.command()
+def snapshot(
+    services: ServicesArg = None,
+    all_services: AllOption = False,
+    log_path: LogPathOption = None,
+    config: ConfigOption = None,
+) -> None:
+    """Record current image digests into the Dockerfarm TOML log."""
+    svc_list, cfg = _get_services(services or [], all_services, config)
+    try:
+        path = _run_async(snapshot_services(cfg, svc_list, log_path=log_path))
+    except RuntimeError as exc:  # pragma: no cover - error path
+        typer.echo(str(exc), err=True)
+        raise typer.Exit(1) from exc
+
+    typer.echo(f"Snapshot written to {path}")
+
+
+@app.command("traefik-file")
+def traefik_file(
+    services: ServicesArg = None,
+    all_services: AllOption = False,
+    output: Annotated[
+        Path | None,
+        typer.Option(
+            "--output",
+            "-o",
+            help="Write Traefik file-provider YAML to this path (stdout if omitted)",
+        ),
+    ] = None,
+    config: ConfigOption = None,
+) -> None:
+    """Generate a Traefik file-provider fragment from compose Traefik labels."""
+    from .traefik import generate_traefik_config
+
+    svc_list, cfg = _get_services(services or [], all_services, config)
+    try:
+        dynamic, warnings = generate_traefik_config(cfg, svc_list)
+    except (FileNotFoundError, ValueError) as exc:
+        typer.echo(str(exc), err=True)
+        raise typer.Exit(1) from exc
+
+    rendered = yaml.safe_dump(dynamic, sort_keys=False)
+
+    if output:
+        output.parent.mkdir(parents=True, exist_ok=True)
+        output.write_text(rendered)
+        typer.echo(f"Traefik config written to {output}")
+    else:
+        typer.echo(rendered)
+
+    for warning in warnings:
+        typer.echo(warning, err=True)
+
+
+if __name__ == "__main__":
+    app()

compose_farm/config.py

@@ -0,0 +1,93 @@
+"""Configuration loading and Pydantic models."""
+
+from __future__ import annotations
+
+import getpass
+from pathlib import Path
+
+import yaml
+from pydantic import BaseModel, Field, model_validator
+
+
+class Host(BaseModel):
+    """SSH host configuration."""
+
+    address: str
+    user: str = Field(default_factory=getpass.getuser)
+    port: int = 22
+
+
+class Config(BaseModel):
+    """Main configuration."""
+
+    compose_dir: Path = Path("/opt/compose")
+    hosts: dict[str, Host]
+    services: dict[str, str]  # service_name -> host_name
+
+    @model_validator(mode="after")
+    def validate_service_hosts(self) -> Config:
+        """Ensure all services reference valid hosts."""
+        for service, host_name in self.services.items():
+            if host_name not in self.hosts:
+                msg = f"Service '{service}' references unknown host '{host_name}'"
+                raise ValueError(msg)
+        return self
+
+    def get_host(self, service: str) -> Host:
+        """Get host config for a service."""
+        if service not in self.services:
+            msg = f"Unknown service: {service}"
+            raise ValueError(msg)
+        return self.hosts[self.services[service]]
+
+    def get_compose_path(self, service: str) -> Path:
+        """Get compose file path for a service."""
+        return self.compose_dir / service / "docker-compose.yml"
+
+
+def _parse_hosts(raw_hosts: dict[str, str | dict[str, str | int]]) -> dict[str, Host]:
+    """Parse hosts from config, handling both simple and full forms."""
+    hosts = {}
+    for name, value in raw_hosts.items():
+        if isinstance(value, str):
+            # Simple form: hostname: address
+            hosts[name] = Host(address=value)
+        else:
+            # Full form: hostname: {address: ..., user: ..., port: ...}
+            hosts[name] = Host(**value)
+    return hosts
+
+
+def load_config(path: Path | None = None) -> Config:
+    """Load configuration from YAML file.
+
+    Search order:
+    1. Explicit path if provided
+    2. ./compose-farm.yaml
+    3. ~/.config/compose-farm/compose-farm.yaml
+    """
+    search_paths = [
+        Path("compose-farm.yaml"),
+        Path.home() / ".config" / "compose-farm" / "compose-farm.yaml",
+    ]
+
+    if path:
+        config_path = path
+    else:
+        config_path = None
+        for p in search_paths:
+            if p.exists():
+                config_path = p
+                break
+
+    if config_path is None or not config_path.exists():
+        msg = f"Config file not found. Searched: {', '.join(str(p) for p in search_paths)}"
+        raise FileNotFoundError(msg)
+
+    with config_path.open() as f:
+        raw = yaml.safe_load(f)
+
+    # Parse hosts with flexible format support
+    raw["hosts"] = _parse_hosts(raw.get("hosts", {}))
+
+    return Config(**raw)

compose_farm/logs.py

@@ -0,0 +1,231 @@
+"""Snapshot current compose images into a TOML log."""
+
+from __future__ import annotations
+
+import json
+import tomllib
+from dataclasses import dataclass
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+from .ssh import run_compose
+
+if TYPE_CHECKING:
+    from collections.abc import Awaitable, Callable, Iterable
+
+    from .config import Config
+    from .ssh import CommandResult
+
+
+DEFAULT_LOG_PATH = Path.home() / ".config" / "compose-farm" / "dockerfarm-log.toml"
+DIGEST_HEX_LENGTH = 64
+
+
+@dataclass(frozen=True)
+class SnapshotEntry:
+    """Normalized image snapshot for a single service."""
+
+    service: str
+    host: str
+    compose_file: Path
+    image: str
+    digest: str
+    captured_at: datetime
+
+    def as_dict(self, first_seen: str, last_seen: str) -> dict[str, str]:
+        """Render snapshot as a TOML-friendly dict."""
+        return {
+            "service": self.service,
+            "host": self.host,
+            "compose_file": str(self.compose_file),
+            "image": self.image,
+            "digest": self.digest,
+            "first_seen": first_seen,
+            "last_seen": last_seen,
+        }
+
+
+def _isoformat(dt: datetime) -> str:
+    return dt.astimezone(UTC).replace(microsecond=0).isoformat().replace("+00:00", "Z")
+
+
+def _escape(value: str) -> str:
+    return value.replace("\\", "\\\\").replace('"', '\\"')
+
+
+def _parse_images_output(raw: str) -> list[dict[str, Any]]:
+    """Parse `docker compose images --format json` output.
+
+    Handles both a JSON array and newline-separated JSON objects for robustness.
+    """
+    raw = raw.strip()
+    if not raw:
+        return []
+
+    try:
+        parsed = json.loads(raw)
+    except json.JSONDecodeError:
+        objects = []
+        for line in raw.splitlines():
+            if not line.strip():
+                continue
+            objects.append(json.loads(line))
+        return objects
+
+    if isinstance(parsed, list):
+        return parsed
+    if isinstance(parsed, dict):
+        return [parsed]
+    return []
+
+
+def _extract_image_fields(record: dict[str, Any]) -> tuple[str, str]:
+    """Extract image name and digest with fallbacks."""
+    image = record.get("Image") or record.get("Repository") or record.get("Name") or ""
+    tag = record.get("Tag") or record.get("Version")
+    if tag and ":" not in image.rsplit("/", 1)[-1]:
+        image = f"{image}:{tag}"
+
+    digest = (
+        record.get("Digest")
+        or record.get("Image ID")
+        or record.get("ImageID")
+        or record.get("ID")
+        or ""
+    )
+
+    if digest and not digest.startswith("sha256:") and len(digest) == DIGEST_HEX_LENGTH:
+        digest = f"sha256:{digest}"
+
+    return image, digest
+
+
+async def _collect_service_entries(
+    config: Config,
+    service: str,
+    *,
+    now: datetime,
+    run_compose_fn: Callable[..., Awaitable[CommandResult]] = run_compose,
+) -> list[SnapshotEntry]:
+    """Run `docker compose images` for a service and normalize results."""
+    result = await run_compose_fn(config, service, "images --format json", stream=False)
+    if not result.success:
+        msg = result.stderr or f"compose images exited with {result.exit_code}"
+        error = f"[{service}] Unable to read images: {msg}"
+        raise RuntimeError(error)
+
+    records = _parse_images_output(result.stdout)
+    host_name = config.services[service]
+    compose_path = config.get_compose_path(service)
+
+    entries: list[SnapshotEntry] = []
+    for record in records:
+        image, digest = _extract_image_fields(record)
+        if not digest:
+            continue
+        entries.append(
+            SnapshotEntry(
+                service=service,
+                host=host_name,
+                compose_file=compose_path,
+                image=image,
+                digest=digest,
+                captured_at=now,
+            )
+        )
+    return entries
+
+
+def _load_existing_entries(log_path: Path) -> list[dict[str, str]]:
+    if not log_path.exists():
+        return []
+    data = tomllib.loads(log_path.read_text())
+    return list(data.get("entries", []))
+
+
+def _merge_entries(
+    existing: Iterable[dict[str, str]],
+    new_entries: Iterable[SnapshotEntry],
+    *,
+    now_iso: str,
+) -> list[dict[str, str]]:
+    merged: dict[tuple[str, str, str], dict[str, str]] = {
+        (e["service"], e["host"], e["digest"]): dict(e) for e in existing
+    }
+
+    for entry in new_entries:
+        key = (entry.service, entry.host, entry.digest)
+        first_seen = merged.get(key, {}).get("first_seen", now_iso)
+        merged[key] = entry.as_dict(first_seen, now_iso)
+
+    return list(merged.values())
+
+
+def _write_toml(log_path: Path, *, meta: dict[str, str], entries: list[dict[str, str]]) -> None:
+    lines: list[str] = ["[meta]"]
+    lines.extend(f'{key} = "{_escape(meta[key])}"' for key in sorted(meta))
+
+    if entries:
+        lines.append("")
+
+    for entry in sorted(entries, key=lambda e: (e["service"], e["host"], e["digest"])):
+        lines.append("[[entries]]")
+        for field in [
+            "service",
+            "host",
+            "compose_file",
+            "image",
+            "digest",
+            "first_seen",
+            "last_seen",
+        ]:
+            value = entry[field]
+            lines.append(f'{field} = "{_escape(str(value))}"')
+        lines.append("")
+
+    content = "\n".join(lines).rstrip() + "\n"
+    log_path.parent.mkdir(parents=True, exist_ok=True)
+    log_path.write_text(content)
+
+
+async def snapshot_services(
+    config: Config,
+    services: list[str],
+    *,
+    log_path: Path | None = None,
+    now: datetime | None = None,
+    run_compose_fn: Callable[..., Awaitable[CommandResult]] = run_compose,
+) -> Path:
+    """Capture current image digests for services and write them to a TOML log.
+
+    - Preserves the earliest `first_seen` per (service, host, digest)
+    - Updates `last_seen` for digests observed in this snapshot
+    - Leaves untouched digests that were not part of this run (history is kept)
+    """
+    if not services:
+        error = "No services specified for snapshot"
+        raise RuntimeError(error)
+
+    log_path = log_path or DEFAULT_LOG_PATH
+    now_dt = now or datetime.now(UTC)
+    now_iso = _isoformat(now_dt)
+
+    existing_entries = _load_existing_entries(log_path)
+
+    snapshot_entries: list[SnapshotEntry] = []
+    for service in services:
+        snapshot_entries.extend(
+            await _collect_service_entries(
+                config, service, now=now_dt, run_compose_fn=run_compose_fn
+            )
+        )
+
+    if not snapshot_entries:
+        error = "No image digests were captured"
+        raise RuntimeError(error)
+
+    merged_entries = _merge_entries(existing_entries, snapshot_entries, now_iso=now_iso)
+    meta = {"generated_at": now_iso, "compose_dir": str(config.compose_dir)}
+    _write_toml(log_path, meta=meta, entries=merged_entries)
+    return log_path