copydock 0.1.0__py3-none-any.whl

copydock/__init__.py

@@ -0,0 +1,3 @@
+"""CopyDock: package a Docker Compose app into a portable deployment bundle."""
+
+__version__ = "0.1.0"

copydock/__main__.py

@@ -0,0 +1,4 @@
+from copydock.cli import app
+
+if __name__ == "__main__":
+    app()

copydock/analysis.py

@@ -0,0 +1,223 @@
+"""Read a Compose project and report what packaging it would need.
+
+`load_config` asks Docker Compose to resolve the file (profiles, extends, merges, paths).
+`analyze` is a pure function over that result, so it can be tested without Docker.
+
+Anything v1 does not support is reported as an error rather than silently skipped (see V1.md).
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import subprocess
+from dataclasses import asdict, dataclass, field
+from pathlib import Path
+
+from copydock.errors import CopyDockError
+
+COMPOSE_FILE_NAMES = ("compose.yaml", "compose.yml", "docker-compose.yaml", "docker-compose.yml")
+
+# ${VAR:?message} and ${VAR?message}: Compose refuses to run unless VAR is set.
+_REQUIRED_VAR = re.compile(r"\$\{([A-Za-z_][A-Za-z0-9_]*):?\?")
+_SECRET_FILE_HINTS = (".env", ".pem", ".key", ".p12", ".pfx")
+_UNSUPPORTED_BUILD_KEYS = {"additional_contexts", "dockerfile_inline", "secrets", "ssh"}
+
+
+@dataclass
+class Finding:
+    level: str  # "error" (v1 cannot package this) or "warning" (works, but check it)
+    message: str
+    code: str = ""  # machine-readable tag, e.g. "secret-file"
+
+
+@dataclass
+class ServiceInfo:
+    name: str
+    image: str | None
+    build_context: str | None
+    published_ports: list[int] = field(default_factory=list)
+    bind_mounts: list[str] = field(default_factory=list)  # relative to the project
+    named_volumes: list[str] = field(default_factory=list)
+
+
+@dataclass
+class Report:
+    project: str
+    compose_file: str
+    services: list[ServiceInfo] = field(default_factory=list)
+    required_env: list[str] = field(default_factory=list)
+    findings: list[Finding] = field(default_factory=list)
+
+    @property
+    def published_ports(self) -> list[int]:
+        return sorted({p for s in self.services for p in s.published_ports})
+
+    @property
+    def errors(self) -> list[Finding]:
+        return [f for f in self.findings if f.level == "error"]
+
+    @property
+    def warnings(self) -> list[Finding]:
+        return [f for f in self.findings if f.level == "warning"]
+
+    def to_dict(self) -> dict:
+        data = asdict(self)
+        data["published_ports"] = self.published_ports
+        return data
+
+
+def find_compose_file(project: Path, name: str | None) -> Path:
+    project = project.resolve()
+    if name:
+        path = project / name
+        if not path.is_file():
+            raise CopyDockError(f"Compose file not found: {path}")
+        return path
+    for candidate in COMPOSE_FILE_NAMES:
+        if (project / candidate).is_file():
+            return project / candidate
+    raise CopyDockError(
+        f"No Compose file in {project}. Looked for: {', '.join(COMPOSE_FILE_NAMES)}. "
+        "Use --compose to name it."
+    )
+
+
+def load_config(project: Path, compose_file: Path) -> dict:
+    """Resolve the Compose file with `docker compose config`.
+
+    Interpolation is left off on purpose: values like ${POSTGRES_PASSWORD} are filled in on the
+    destination server, never at package time, so inspect must not need them.
+    """
+    project = project.resolve()  # also used as cwd, so a relative path would be applied twice
+    compose_file = compose_file.resolve()
+    cmd = [
+        "docker", "compose",
+        "--project-directory", str(project),
+        "-f", str(compose_file),
+        "--profile", "*",
+        "config", "--no-interpolate", "--format", "json",
+    ]  # fmt: skip
+    try:
+        result = subprocess.run(cmd, capture_output=True, text=True, cwd=project, check=False)
+    except FileNotFoundError:
+        raise CopyDockError("Docker was not found. Install Docker with the Compose plugin.") from None
+    if result.returncode != 0:
+        detail = result.stderr.strip() or "no details from docker"
+        raise CopyDockError(f"`docker compose config` failed for {compose_file.name}:\n{detail}")
+    try:
+        return json.loads(result.stdout)
+    except json.JSONDecodeError:
+        raise CopyDockError("Could not read the output of `docker compose config`.") from None
+
+
+def _inside(path: Path, root: Path) -> bool:
+    try:
+        path.resolve().relative_to(root.resolve())
+    except ValueError:
+        return False
+    return True
+
+
+def _relative(path: Path, root: Path) -> str:
+    return str(path.resolve().relative_to(root.resolve()))
+
+
+def analyze(config: dict, raw_text: str, project: Path, compose_file: str) -> Report:
+    report = Report(project=str(project), compose_file=compose_file)
+    root = project.resolve()
+    project_name = config.get("name") or root.name.lower()
+
+    # Required variables are found in the raw text: the resolved config does not list them.
+    # Limitation: variables used only in `include:`d or `extends:`d files are not seen.
+    report.required_env = sorted(set(_REQUIRED_VAR.findall(raw_text)))
+
+    for kind in ("volumes", "networks"):
+        for name, spec in (config.get(kind) or {}).items():
+            if spec and spec.get("external"):
+                report.findings.append(
+                    Finding("error", f"{kind[:-1].capitalize()} '{name}' is external. "
+                            "v1 only packages volumes and networks that Compose creates itself.")
+                )  # fmt: skip
+    for kind in ("secrets", "configs"):
+        for name in config.get(kind) or {}:
+            report.findings.append(
+                Finding("error", f"Top-level {kind[:-1]} '{name}' is not supported in v1. "
+                        "Pass the value as an environment variable instead.")
+            )  # fmt: skip
+
+    for name, svc in (config.get("services") or {}).items():
+        # A built service with no `image:` gets the name Compose would give it.
+        image = svc.get("image") or (f"{project_name}-{name}" if svc.get("build") else None)
+        info = ServiceInfo(name=name, image=image, build_context=None)
+
+        build = svc.get("build")
+        if build:
+            context = Path(build["context"] if isinstance(build, dict) else build)
+            for key in _UNSUPPORTED_BUILD_KEYS & set(build if isinstance(build, dict) else ()):
+                report.findings.append(
+                    Finding("error", f"{name}: build option '{key}' is not supported in v1.")
+                )
+            for arg, value in ((build.get("args") or {}) if isinstance(build, dict) else {}).items():
+                if value is not None and "$" in str(value):
+                    report.findings.append(
+                        Finding("error", f"{name}: build arg {arg} uses a variable. Build args "
+                                "must be fixed values, because images are built before install.")
+                    )  # fmt: skip
+            if _inside(context, root):
+                info.build_context = _relative(context, root) or "."
+            else:
+                info.build_context = str(context)
+                report.findings.append(
+                    Finding("error", f"{name}: build context {context} is outside the project.")
+                )
+
+        for port in svc.get("ports") or []:
+            published = port.get("published") if isinstance(port, dict) else None
+            if published is None:
+                continue  # container-only port, nothing opens on the host
+            try:
+                info.published_ports.append(int(published))
+            except ValueError:
+                report.findings.append(
+                    Finding("warning", f"{name}: port '{published}' is a range or uses a variable; "
+                            "it was not included in the port check.")
+                )  # fmt: skip
+
+        for vol in svc.get("volumes") or []:
+            if vol.get("type") == "volume":
+                info.named_volumes.append(vol.get("source") or "(anonymous)")
+            elif vol.get("type") == "bind":
+                source = Path(vol["source"])
+                if source.name == "docker.sock":
+                    report.findings.append(
+                        Finding("error", f"{name}: mounts the Docker socket. That gives the "
+                                "container control of the host, and v1 does not package it.")
+                    )  # fmt: skip
+                elif not _inside(source, root):
+                    report.findings.append(
+                        Finding("error", f"{name}: bind mount {source} is outside the project, "
+                                "so it cannot be bundled.")
+                    )  # fmt: skip
+                else:
+                    rel = _relative(source, root)
+                    info.bind_mounts.append(rel)
+                    if source.name.startswith(".env") or source.suffix in _SECRET_FILE_HINTS:
+                        report.findings.append(
+                            Finding("warning", f"{name}: bind mount {rel} looks like it may "
+                                    "hold secrets. Check it before bundling.", "secret-file")
+                        )  # fmt: skip
+
+        if svc.get("env_file"):
+            report.findings.append(
+                Finding("error", f"{name}: uses env_file, which is not supported in v1. Move the "
+                        "values into `environment:` as ${VARIABLES}, so the server provides them.")
+            )  # fmt: skip
+        if svc.get("privileged"):
+            report.findings.append(Finding("warning", f"{name}: runs privileged."))
+        if svc.get("network_mode") == "host":
+            report.findings.append(Finding("warning", f"{name}: uses host networking."))
+
+        report.services.append(info)
+
+    return report

copydock/cli.py

@@ -0,0 +1,117 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import typer
+
+from copydock import __version__, ui
+from copydock.analysis import analyze, find_compose_file, load_config
+from copydock.errors import CopyDockError
+from copydock.packager import package_project
+
+app = typer.Typer(
+    help="Package a Docker Compose app into a portable bundle for any Linux server.",
+    no_args_is_help=True,
+    add_completion=False,
+    rich_markup_mode=None,
+)
+
+
+def _shorten(path: Path) -> str:
+    """Show a path relative to the current folder when it lives below it."""
+    try:
+        return str(path.relative_to(Path.cwd()))
+    except ValueError:
+        return str(path)
+
+
+def _version_callback(value: bool) -> None:
+    if value:
+        ui.console.print(f"copydock {__version__}")
+        raise typer.Exit()
+
+
+@app.callback()
+def main(
+    version: bool = typer.Option(
+        False, "--version", callback=_version_callback, is_eager=True, help="Show version."
+    ),
+) -> None:
+    pass
+
+
+@app.command()
+def inspect(
+    project: Path = typer.Argument(..., exists=True, file_okay=False, help="Project directory."),
+    compose: str = typer.Option(
+        None, "--compose", "-f", help="Compose file name (default: auto-detect)."
+    ),
+    as_json: bool = typer.Option(False, "--json", help="Print the report as JSON."),
+) -> None:
+    """Show what a project needs to be packaged (images, ports, variables, unsupported features)."""
+    if not as_json:
+        ui.banner(f"inspecting {project.resolve().name}")
+    try:
+        compose_path = find_compose_file(project, compose)
+        config = load_config(project, compose_path)
+        report = analyze(config, compose_path.read_text(), project, compose_path.name)
+    except CopyDockError as e:
+        ui.error("Could not inspect", str(e))
+        raise typer.Exit(1) from None
+
+    if as_json:
+        ui.console.print_json(json.dumps(report.to_dict()))
+    else:
+        ui.print_report(report)
+    if report.errors:
+        raise typer.Exit(1)
+
+
+@app.command()
+def package(
+    project: Path = typer.Argument(..., exists=True, file_okay=False, help="Project directory."),
+    compose: str = typer.Option(
+        None, "--compose", "-f", help="Compose file name (default: auto-detect)."
+    ),
+    platform: str = typer.Option(
+        None,
+        "--platform",
+        help="Platform of the SERVER: linux/amd64 or linux/arm64. "
+        "Default: the platform of this machine's Docker.",
+    ),
+    app_version: str = typer.Option("latest", "--app-version", help="Version label for the bundle."),
+    output: Path = typer.Option(Path("."), "--output", "-o", help="Folder for the bundle."),
+    include_secret_files: bool = typer.Option(
+        False,
+        "--include-secret-files",
+        help="Bundle bind-mounted files that look like secrets (.env, .pem, .key).",
+    ),
+) -> None:
+    """Build a .tar.gz bundle that installs on a Linux server, online or offline."""
+    ui.banner(f"packaging {project.resolve().name}")
+    try:
+        result = package_project(
+            project, compose, platform, output, app_version, include_secret_files
+        )
+    except CopyDockError as e:
+        ui.error("Could not package", str(e))
+        raise typer.Exit(1) from None
+
+    name = result.archive.name
+    folder = name.removesuffix(".tar.gz")
+    ui.print_bundle(
+        archive_name=name,
+        size=result.size,
+        sha256=result.sha256,
+        platform=result.manifest.platform,
+        images=result.manifest.images,
+        sidecar=result.sidecar.name,
+        next_steps=[
+            f"Copy to the server:  scp {_shorten(result.archive)} user@server:~/",
+            f"On the server:       tar xzf {name} && cd {folder} && ./install.sh",
+        ],
+    )
+    if result.findings:
+        ui.print_findings(result.findings)
+        ui.console.print()

copydock/docker.py

@@ -0,0 +1,76 @@
+"""Thin wrapper around the `docker` command. All Docker work goes through here."""
+
+from __future__ import annotations
+
+import json
+import subprocess
+from pathlib import Path
+
+from copydock.errors import CopyDockError
+
+SUPPORTED_PLATFORMS = ("linux/amd64", "linux/arm64")
+
+
+def run(args: list[str], what: str) -> str:
+    """Run `docker <args>`; on failure raise an error that shows the last lines of output."""
+    try:
+        result = subprocess.run(["docker", *args], capture_output=True, text=True, check=False)
+    except FileNotFoundError:
+        raise CopyDockError("Docker was not found. Install Docker and try again.") from None
+    if result.returncode != 0:
+        output = (result.stderr or result.stdout).strip().splitlines()
+        raise CopyDockError(f"{what} failed:\n" + "\n".join(output[-15:]))
+    return result.stdout
+
+
+def server_platform() -> str:
+    """Platform of the local Docker engine, e.g. linux/amd64. Also proves the daemon is up."""
+    try:
+        out = run(["version", "--format", "{{.Server.Os}}/{{.Server.Arch}}"], "Docker")
+    except CopyDockError as e:
+        if "not found" in str(e):
+            raise
+        raise CopyDockError(
+            "Docker is installed but not running. Start Docker, then try again."
+        ) from None
+    return out.strip()
+
+
+def build(ref: str, context: Path, dockerfile: str, platform: str, args: dict[str, str],
+          target: str | None) -> None:  # fmt: skip
+    cmd = ["build", "--platform", platform, "-t", ref, "-f", str(context / dockerfile)]
+    for key, value in args.items():
+        cmd += ["--build-arg", f"{key}={value}"]
+    if target:
+        cmd += ["--target", target]
+    cmd.append(str(context))
+    run(cmd, f"Building {ref}")
+
+
+def pull(ref: str, platform: str) -> None:
+    run(["pull", "--platform", platform, ref], f"Pulling {ref}")
+
+
+def _with_platform(prefix: list[str], rest: list[str], platform: str, what: str) -> str:
+    """Run `docker <prefix> --platform P <rest>`.
+
+    Docker 25+ keeps several platforms under one tag, and without --platform shows or saves the
+    variant matching THIS machine, which is wrong when packaging for another CPU type. Older Docker
+    keeps one platform per tag and does not know the flag; fall back to the plain command only
+    when the flag itself is unknown, never on other errors.
+    """
+    try:
+        return run([*prefix, "--platform", platform, *rest], what)
+    except CopyDockError as e:
+        if "unknown flag" not in str(e):
+            raise
+        return run([*prefix, *rest], what)
+
+
+def inspect_image(ref: str, platform: str) -> dict:
+    out = _with_platform(["image", "inspect"], [ref], platform, f"Inspecting {ref}")
+    return json.loads(out)[0]
+
+
+def save(refs: list[str], dest: Path, platform: str) -> None:
+    _with_platform(["save"], ["-o", str(dest), *refs], platform, "Saving images")

copydock/errors.py

@@ -0,0 +1,6 @@
+class CopyDockError(Exception):
+    """An expected, user-facing failure. The message must say what to do next."""
+
+
+class UnsupportedComposeFeature(CopyDockError):
+    """The Compose file uses something v1 deliberately rejects (see V1.md, Limits)."""

copydock/manifest.py

@@ -0,0 +1,48 @@
+"""Bundle manifest: the packing list. What is inside a bundle, in a form the installer and
+humans can check."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import asdict, dataclass, field
+
+FORMAT_VERSION = 1
+
+
+@dataclass
+class ImageEntry:
+    reference: str  # name:tag used in the rewritten compose file
+    services: list[str]  # compose services that use this image
+    image_id: str  # sha256 of the image config; identical on every machine that loads it
+    repo_digest: str | None  # registry digest, for images pulled from a registry
+    built: bool  # True if built from the project, False if pulled from a registry
+    size_bytes: int
+
+
+@dataclass
+class Manifest:
+    app_name: str
+    app_version: str
+    platform: str  # e.g. linux/amd64
+    created_at: str  # UTC, ISO 8601
+    copydock_version: str
+    images_archive: str = "images/images.tar"
+    images: list[ImageEntry] = field(default_factory=list)
+    required_ports: list[int] = field(default_factory=list)
+    required_env: list[str] = field(default_factory=list)  # names only, never values
+    checksums: dict[str, str] = field(default_factory=dict)  # relative path -> sha256
+    format_version: int = FORMAT_VERSION
+
+    def to_json(self) -> str:
+        return json.dumps(asdict(self), indent=2, sort_keys=True)
+
+    @classmethod
+    def from_json(cls, text: str) -> Manifest:
+        data = json.loads(text)
+        if data.get("format_version") != FORMAT_VERSION:
+            raise ValueError(
+                f"Unsupported bundle format {data.get('format_version')!r}; "
+                f"this CopyDock reads format {FORMAT_VERSION}."
+            )
+        images = [ImageEntry(**i) for i in data.pop("images", [])]
+        return cls(images=images, **data)