lablink-cli 0.1.0__tar.gz → 0.2.0__tar.gz

{lablink_cli-0.1.0 → lablink_cli-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: lablink-cli
-Version: 0.1.0
+Version: 0.2.0
 Summary: CLI tool for deploying and managing LabLink infrastructure
 Author-email: Elizabeth Berrigan <eberrigan@salk.edu>, Talmo Pereira <talmo@salk.edu>, Andrew Park <hep003@ucsd.edu>
 Project-URL: Homepage, https://github.com/talmolab/lablink
@@ -13,7 +13,6 @@ Requires-Dist: textual>=3.0
 Requires-Dist: rich>=13.0
 Requires-Dist: pyyaml>=6.0
 Requires-Dist: boto3>=1.35
-Requires-Dist: psutil>=5.9
 Provides-Extra: dev
 Requires-Dist: pytest; extra == "dev"
 Requires-Dist: pytest-cov; extra == "dev"

{lablink_cli-0.1.0 → lablink_cli-0.2.0}/pyproject.toml

@@ -5,7 +5,7 @@ authors = [
   {name = "Talmo Pereira", email = "talmo@salk.edu"},
   {name = "Andrew Park", email = "hep003@ucsd.edu"},
 ]
-version = "0.1.0"
+version = "0.2.0"
 description = "CLI tool for deploying and managing LabLink infrastructure"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -19,7 +19,6 @@ dependencies = [
     "rich>=13.0",
     "pyyaml>=6.0",
     "boto3>=1.35",
-    "psutil>=5.9",
 ]
 
 [project.optional-dependencies]

{lablink_cli-0.1.0 → lablink_cli-0.2.0}/src/lablink_cli/app.py

@@ -272,9 +272,27 @@ def deploy(
         "redeploys (the previous value is carried forward). Supply it again "
         "to rotate. Manual provider only.",
     ),
+    render_only: bool = typer.Option(
+        False,
+        "--render-only",
+        help="Render the deployment bundle and print a launch sheet "
+        "instead of starting containers — for running the allocator "
+        "image on an external container platform (Run:AI, Kubernetes) "
+        "where no Docker daemon is available. Manual provider only.",
+    ),
 ) -> None:
     """Deploy LabLink infrastructure (AWS OpenTofu or docker-compose)."""
     cfg = _load_cfg(config)
+
+    if render_only and cfg.provider != "manual":
+        from rich.console import Console
+
+        Console().print(
+            "[red]--render-only is only meaningful with provider: manual "
+            f"(this config has provider: {cfg.provider}).[/red]"
+        )
+        raise typer.Exit(1)
+
     if cfg.provider == "manual":
         from lablink_cli.commands.deploy_compose import run_deploy_compose
 
@@ -283,6 +301,7 @@ def deploy(
             yes=yes,
             tailscale_authkey=tailscale_authkey,
             cloudflare_tunnel_token=cloudflare_tunnel_token,
+            render_only=render_only,
         )
         return
 

{lablink_cli-0.1.0 → lablink_cli-0.2.0}/src/lablink_cli/commands/cleanup.py

@@ -16,6 +16,7 @@ from rich.panel import Panel
 
 from lablink_allocator_service.conf.structured_config import Config
 
+from lablink_cli import manual
 from lablink_cli.commands.setup import (
     _get_session,
     check_credentials,
@@ -28,8 +29,6 @@ from lablink_cli.docker import Docker, default_docker
 
 console = Console()
 
-DEFAULT_COMPOSE_DIR = Path.home() / ".lablink" / "compose"
-
 
 def _delete_if_exists(
     action: str, fn, *args, **kwargs
@@ -614,15 +613,21 @@ def run_cleanup(
 # Manual-provider cleanup
 # ------------------------------------------------------------------
 def _run_cleanup_manual(
-    cfg: Config, *, dry_run: bool, docker: Docker | None = None
+    cfg: Config,
+    *,
+    dry_run: bool,
+    docker: Docker | None = None,
+    workdir_root: Path | None = None,
 ) -> None:
     """Tear down a local docker-compose allocator stack.
 
     Runs `docker compose down --volumes` in the deployment workdir and
     then removes the workdir itself. No AWS API calls are made.
+
+    `workdir_root` overrides the default compose root (used by tests).
     """
     docker = docker or default_docker()
-    workdir = DEFAULT_COMPOSE_DIR / (cfg.deployment_name or "lablink")
+    workdir = manual.workdir(cfg, workdir_root)
 
     console.print(
         f"[bold]Manual cleanup:[/bold] {cfg.deployment_name or 'lablink'}"

{lablink_cli-0.1.0 → lablink_cli-0.2.0}/src/lablink_cli/commands/deploy.py

@@ -273,6 +273,20 @@ def _prompt_passwords() -> dict[str, str]:
     }
 
 
+def _warn_letsencrypt_rate_limit(cfg: Config) -> None:
+    """Warn that LE issues ≤5 certs/domain/7 days — redeploys fail opaquely."""
+    if cfg.ssl.provider != "letsencrypt":
+        return
+    console.print(
+        "  [yellow]Note:[/yellow] Let's Encrypt issues at most 5 "
+        "certificates per domain per 7 days. Repeated deploys of "
+        f"'{cfg.dns.domain}' within a week will hit this limit and the "
+        "site will fail with ERR_SSL_PROTOCOL_ERROR. Use a fresh "
+        "subdomain for repeated test deploys."
+    )
+    console.print()
+
+
 def _build_health_poll_target(cfg: Config, ec2_ip: str) -> dict:
     """Pick the post-deploy poll URL + timeout. Caddy is Host-bound under
     letsencrypt/cloudflare, so those must poll the domain, not the IP."""
@@ -372,6 +386,8 @@ def run_deploy(
     )
     console.print()
 
+    _warn_letsencrypt_rate_limit(cfg)
+
     # Validate AWS credentials
     check_credentials(_get_session(cfg.app.region))
 

{lablink_cli-0.1.0 → lablink_cli-0.2.0}/src/lablink_cli/commands/deploy_compose.py

@@ -35,9 +35,15 @@ from lablink_cli.deployment_metrics import (
     write_metrics,
 )
 from lablink_cli.docker import Docker, DockerUnavailable, default_docker
+from lablink_cli.manual import (
+    CANONICAL_URL_FILENAME,
+    DEFAULT_COMPOSE_DIR,  # noqa: F401 — re-exported for callers/tests
+    DEFAULT_HTTP_PORT,
+    RUNTIME_FILENAME,
+    deployment_runtime,
+    workdir as compose_workdir,
+)
 
-DEFAULT_COMPOSE_DIR = Path.home() / ".lablink" / "compose"
-DEFAULT_HTTP_PORT = "80"
 HEALTH_POLL_TIMEOUT_SECONDS = 300
 ALLOCATOR_IMAGE_BASE = "ghcr.io/talmolab/lablink-allocator-image"
 # Only ssl=none is supported by the manual-provider compose stack today:
@@ -61,25 +67,9 @@ FUNNEL_ENABLE_RETRY_DELAY_SECONDS = 2
 # a few seconds; 6 tries 5s apart leaves ~25s of headroom over that.
 PUBLIC_HOSTNAME_MAX_ATTEMPTS = 6
 PUBLIC_HOSTNAME_RETRY_DELAY_SECONDS = 5
-# Name of the file carrying the allocator's real public URL, staged next to
-# config.yaml and bind-mounted to /config/<name>. Must stay in sync with
-# config_helpers.CANONICAL_URL_FILENAME in the allocator package — duplicated
-# rather than imported because each package's CI job installs only its own
-# dependencies, so a cross-package import would fail there. Guarded by
-# test_deploy_compose.py::TestCanonicalUrlFile::test_filename_matches_allocator.
-CANONICAL_URL_FILENAME = "allocator-url"
-
 console = Console()
 
 
-def compose_workdir(cfg: Config, root: Path | None = None) -> Path:
-    """Path to the rendered compose working directory for this deployment.
-
-    `root` overrides `DEFAULT_COMPOSE_DIR` (used by tests via `workdir_root`).
-    """
-    name = cfg.deployment_name or "lablink"
-    return (root or DEFAULT_COMPOSE_DIR) / name
-
 
 def _read_env_value(env_path: Path, key: str) -> str | None:
     """Read a single KEY=value line from an existing .env file.
@@ -292,8 +282,11 @@ def run_deploy_compose(
     tailscale_authkey: str | None = None,
     cloudflare_tunnel_token: str | None = None,
     docker: Docker | None = None,
+    render_only: bool = False,
 ) -> None:
-    """Bring up the allocator stack via docker-compose.
+    """Bring up the allocator stack via docker-compose, or (with
+    `render_only=True`) render it for an external container platform
+    instead.
 
     Renders the compose working directory (`compose_workdir(cfg)`),
     runs `docker compose up -d`, polls the allocator's `/api/health`
@@ -302,6 +295,14 @@ def run_deploy_compose(
 
     `yes=True` skips the interactive confirmation prompt.
     `workdir_root` overrides `DEFAULT_COMPOSE_DIR` (used by tests).
+    `render_only=True` renders the compose bundle (config.yaml,
+    custom-startup.sh, the canonical-URL file) and writes the
+    `RUNTIME_FILENAME` marker, then prints a launch sheet and returns —
+    no docker on this machine is required or used. For running the
+    allocator image as a workload on an external container platform
+    (Run:AI, Kubernetes) instead of via `docker compose up`. Rejected
+    up front when the config needs the Tailscale sidecar, which such
+    platforms do not grant kernel TUN/NET_ADMIN access for.
     `tailscale_authkey` is required when a tailnet join is needed for
     either `cfg.manual.connectivity == "mesh_overlay"` or
     `cfg.manual.participant_exposure == "tailscale_funnel"`, unless a
@@ -322,6 +323,28 @@ def run_deploy_compose(
     target = compose_workdir(cfg, workdir_root)
 
     needs_sidecar = _needs_tailscale_sidecar(cfg)
+
+    # Preflight: --render-only can't serve a config that needs the
+    # Tailscale sidecar — a managed external container platform (the
+    # whole point of --render-only) grants the workload no kernel TUN
+    # device / NET_ADMIN, which containerboot requires to join a tailnet.
+    # Placed before ANY docker use — including the
+    # _tailscale_state_volume_exists check just below, which calls
+    # docker.volume_exists() and therefore docker.require() — so a
+    # docker-less machine gets this clean message instead of an unhandled
+    # DockerUnavailable traceback.
+    if render_only and needs_sidecar:
+        console.print(
+            "[red]--render-only cannot serve this config: "
+            f"manual.connectivity={cfg.manual.connectivity!r} / "
+            f"manual.participant_exposure={cfg.manual.participant_exposure!r} "
+            "need the Tailscale sidecar (kernel TUN device + NET_ADMIN), "
+            "which managed container platforms do not grant. Use "
+            "connectivity=reverse_tunnel with "
+            "participant_exposure=cloudflare_tunnel instead.[/red]"
+        )
+        raise SystemExit(1)
+
     if needs_sidecar:
         # Checking ".env exists" alone (i.e. "is this a redeploy") isn't
         # enough: a redeploy that *switches* to needing the sidecar has
@@ -431,16 +454,19 @@ def run_deploy_compose(
         )
         raise SystemExit(1)
 
-    # Preflight: docker on PATH.
-    try:
-        docker.require()
-    except DockerUnavailable:
-        console.print(
-            "[red]docker not found on PATH.[/red] "
-            "Install Docker Engine + the Compose plugin "
-            "(https://docs.docker.com/engine/install/) and re-run."
-        )
-        raise SystemExit(1)
+    # Preflight: docker on PATH. Not needed for --render-only — the whole
+    # point is running the image on a platform without a local docker
+    # daemon.
+    if not render_only:
+        try:
+            docker.require()
+        except DockerUnavailable:
+            console.print(
+                "[red]docker not found on PATH.[/red] "
+                "Install Docker Engine + the Compose plugin "
+                "(https://docs.docker.com/engine/install/) and re-run."
+            )
+            raise SystemExit(1)
 
     # Resolve admin credentials (mirrors AWS deploy.py). The wizard does
     # NOT collect admin user/password — they're resolved here. Write the
@@ -473,13 +499,35 @@ def run_deploy_compose(
             raise SystemExit(1)
 
     if not yes:
-        action = "create" if not target.exists() else "update"
+        existed_before = target.exists()
+        action = "create" if not existed_before else "update"
+        verb = (
+            f"render an external-runtime bundle in {target}"
+            if render_only
+            else f"{action} compose stack in {target}"
+        )
         console.print(
-            f"About to {action} compose stack in {target}\n"
+            f"About to {verb}\n"
             f"  provider: manual\n"
             f"  ssl: {cfg.ssl.provider}\n"
             f"  admin user: {admin_user}\n"
         )
+        # A workdir that already exists with no external marker is a live
+        # compose-managed deployment. --render-only would flip it to
+        # external — after which `lablink destroy` stops managing any
+        # local compose stack for it at all, orphaning one still running.
+        # Only the marker transition is checked here (no docker probe):
+        # the transition itself is the signal, regardless of whether a
+        # stack happens to be up right now.
+        if render_only and existed_before and deployment_runtime(target) == "compose":
+            console.print(
+                "[bold red]Warning:[/bold red] this deployment is currently "
+                "managed by docker-compose. --render-only will flip it to "
+                "external-runtime — afterward, `lablink destroy` no longer "
+                "manages any local docker-compose stack for it. If a "
+                "compose stack is running for this deployment, tear it "
+                "down FIRST with `lablink destroy`, before proceeding here."
+            )
         if not typer.confirm("Proceed?", default=True):
             console.print("Aborted.")
             raise SystemExit(1)
@@ -514,6 +562,62 @@ def run_deploy_compose(
         )
         console.print(f"[green]Rendered {target}[/green]")
 
+        # Write or clear the runtime marker `deployment_runtime()` reads
+        # back (status/logs/destroy branch on it). render_only returns
+        # immediately after — no docker.compose/health-poll/summary,
+        # since an external platform runs the image, not this machine.
+        marker = target / RUNTIME_FILENAME
+        if render_only:
+            marker.write_text("external\n")
+
+            # A bundle with no recorded public URL leaves every day-2
+            # command broken: `status`/`logs` have no address to reach the
+            # externally-run allocator at, and (until now) `status` simply
+            # probed localhost, which has nothing listening on it for this
+            # mode. Read the canonical-URL file directly rather than
+            # importing status._public_url, to avoid a needless
+            # cross-module reach for one string check.
+            canonical_url = (target / CANONICAL_URL_FILENAME).read_text().strip()
+            if not canonical_url.startswith(("http://", "https://")):
+                console.print(
+                    "[red]--render-only produced a bundle with no public "
+                    "URL recorded.[/red]\n"
+                    "Day-2 `lablink status` / `lablink logs` need one to "
+                    "reach the externally-run allocator. The only exposure "
+                    "mode --render-only supports today is "
+                    "manual.participant_exposure: cloudflare_tunnel (with "
+                    "manual.public_hostname set) — update your config and "
+                    "re-render."
+                )
+                raise SystemExit(1)
+
+            # Render-only's own success write, mirroring the compose
+            # path's success write below (allocator_deploy_end_time /
+            # allocator_total_deployment_duration_seconds / status) —
+            # the render IS the deploy action here, so without this the
+            # in_progress record written above would never be finalized
+            # (the early return skips the compose path's write entirely).
+            # No compose_up/health_check phases ran in this path, so the
+            # duration sums to 0 — an honest reflection of "no docker
+            # phases," not a stand-in for a real elapsed time.
+            metrics.allocator_deploy_end_time = datetime.now(timezone.utc).isoformat()
+            metrics.allocator_total_deployment_duration_seconds = round(
+                sum(
+                    v
+                    for v in (
+                        metrics.allocator_compose_up_duration_seconds,
+                        metrics.allocator_health_check_duration_seconds,
+                    )
+                    if v is not None
+                ),
+                3,
+            )
+            metrics.status = "success"
+            write_metrics(metrics_path, metrics)
+            _print_launch_sheet(cfg, target, console)
+            return
+        marker.unlink(missing_ok=True)
+
         # Explicitly disable Funnel *before* _compose_up, whenever the new
         # config no longer wants it — this must run before --remove-orphans
         # potentially deletes the sidecar (a removed container can't be
@@ -860,6 +964,34 @@ def _print_last_log_lines(lines: int = 30, *, docker: Docker) -> None:
         console.print(_redact_secrets(result.stdout))
 
 
+def _print_launch_sheet(cfg: Config, workdir: Path, console: Console) -> None:
+    """Print everything needed to launch the rendered bundle on an
+    external container platform (the platform is the container runtime;
+    nothing needs docker on this machine)."""
+    cf_token = _read_env_value(workdir / ".env", "CLOUDFLARE_TUNNEL_TOKEN")
+    console.print("\n[bold]Bundle rendered — launch it on your platform:[/bold]")
+    console.print(f"  Image:    {_allocator_image(cfg)}  (default command)")
+    console.print("  Env vars:")
+    console.print(f"    PARTICIPANT_EXPOSURE={cfg.manual.participant_exposure}")
+    if cfg.manual.participant_exposure == "cloudflare_tunnel":
+        console.print(f"    CLOUDFLARE_TUNNEL_TOKEN={cf_token or '<missing>'}")
+    console.print("  Mounts (read-only files, all rendered in this dir):")
+    console.print(f"    {workdir}/config.yaml        -> /config/config.yaml")
+    console.print(f"    {workdir}/custom-startup.sh  -> /config/custom-startup.sh")
+    console.print(f"    {workdir}/allocator-url      -> /config/allocator-url")
+    console.print(
+        "  Persistent volume (optional): /var/lib/postgresql "
+        "(DB survives pod restarts)"
+    )
+    console.print("  Inbound ports: none required — every leg dials out.")
+    console.print("  The image expects to run as root (postgres + nginx).")
+    console.print(
+        "\n  After boot, the BYO register token prints in the workload's "
+        "log\n  (also at /var/log/lablink/allocator.log inside the "
+        "container).\n  See docs: CLI → External runtime (Run:AI walkthrough)."
+    )
+
+
 def _print_summary(
     cfg: Config,
     *,
@@ -1155,6 +1287,36 @@ def run_destroy_compose(
         )
         return
 
+    if deployment_runtime(target) == "external":
+        console.print(
+            "[bold]This deployment runs on an external platform[/bold] — "
+            "there is nothing to stop here.\n"
+            "Delete the platform workload yourself (e.g. "
+            "`runai workspace delete <name> -p <project>`); any Postgres "
+            "data lives in the volume you attached there.\n"
+            f"Removing only the local bundle at {target}."
+        )
+        if not yes:
+            confirmation = typer.prompt(
+                f"Type 'yes' to remove the local bundle at {target}",
+                default="no",
+                show_default=False,
+            )
+            if confirmation.strip().lower() != "yes":
+                console.print("Aborted.")
+                raise SystemExit(1)
+        shutil.rmtree(target)
+        console.print(f"[green]Removed {target}.[/green]")
+        console.print(
+            "\n[bold]Reminder:[/bold] this only removed the local rendered "
+            "bundle — every BYO client still has `lablink-client` running, "
+            "and any client submitted as its own platform workload is "
+            "still running there too.\n"
+            "Run [bold]lablink client unregister[/bold] on each BYO box, "
+            "and delete each client workload on the platform yourself."
+        )
+        return
+
     if not yes:
         if not keep_data:
             console.print(

{lablink_cli-0.1.0 → lablink_cli-0.2.0}/src/lablink_cli/commands/doctor.py

@@ -366,27 +366,6 @@ def _check_manual_prereqs(*, docker: Docker | None = None) -> None:
 # client on this machine actually working?"
 # --------------------------------------------------------------------
 
-# A shipper that is alive but hasn't shipped in this long is reporting a
-# problem no liveness check can see — the process is up and the container is
-# healthy, but nothing is reaching the allocator. That combination went
-# unnoticed for a week (lablink#428), which is the reason this command exists.
-SHIPPER_STALE_AFTER_S = 15 * 60
-
-
-def _format_age(seconds: float) -> str:
-    """Coarse human age ("6d", "3h", "20m") for the staleness message.
-
-    A raw minute count reads as noise once it passes a few hours
-    ("8687 min ago"), and this is the one line an operator scans to decide
-    whether logs are flowing.
-    """
-    if seconds >= 86400:
-        return f"{int(seconds // 86400)}d"
-    if seconds >= 3600:
-        return f"{int(seconds // 3600)}h"
-    return f"{int(seconds // 60)}m"
-
-
 def _check_client_registered() -> dict:
     """Check that `lablink client register` has run on this box."""
     from lablink_cli.commands.register import DEFAULT_ENV_FILE
@@ -409,7 +388,7 @@ def _check_client_container(docker: Docker) -> dict:
     "daemon_error" when the daemon is unreachable, so a separate probe would
     only duplicate the same `docker inspect` call.
     """
-    from lablink_cli.log_shipper import CONTAINER_NAME
+    from lablink_cli.commands.register import CONTAINER_NAME
 
     result = {"check": "Client container", "status": "fail"}
     status = docker.container_status(CONTAINER_NAME)
@@ -440,59 +419,34 @@ def _check_client_container(docker: Docker) -> dict:
     return result
 
 
-def _check_log_shipper(now: float | None = None) -> dict:
-    """Check the log shipper is alive AND actually shipping.
+def _check_log_shipper(docker: Docker) -> dict:
+    """Check the in-container ship_logs worker is running.
 
-    Liveness alone is not enough. A shipper can sit blocked on a quiet
-    container with a full buffer, process up, nothing delivered — so this
-    also reports how long ago a batch last landed.
+    The shipper lives inside the client container — start.sh feeds every
+    service's output through the client package's ship_logs worker when
+    SHIP_LOGS=1 — so the probe is a pgrep inside the container. The old
+    host-side staleness check (lablink#428's alive-but-not-shipping
+    hazard) moved in-container with it: a worker that can't reach the
+    allocator says so in `docker logs lablink-client`
+    ("ship_logs: dropped N lines after retries").
     """
-    import time
-    from datetime import datetime, timezone
-
-    from lablink_cli.commands.register import _shipper_alive
-    from lablink_cli.log_shipper import STATE_FILE, read_last_shipped_ts
+    from lablink_cli.commands.register import CONTAINER_NAME
 
     result = {"check": "Log shipper", "status": "fail"}
 
-    if not _shipper_alive():
-        result["detail"] = (
-            "Not running — client logs are not reaching the allocator. "
-            "Run `lablink client register` to restart it."
-        )
-        return result
-
-    last = read_last_shipped_ts(STATE_FILE)
-    if last is None:
-        result["status"] = "warn"
-        result["detail"] = (
-            "Running, but has never shipped a batch. Normal for the first "
-            "minute after registering; otherwise check the allocator URL "
-            "and client secret."
-        )
-        return result
-
-    try:
-        shipped_at = datetime.strptime(last, "%Y-%m-%dT%H:%M:%SZ").replace(
-            tzinfo=timezone.utc
-        )
-    except ValueError:
-        result["status"] = "warn"
-        result["detail"] = f"Running; unparseable last-shipped value {last!r}"
-        return result
-
-    current = now if now is not None else time.time()
-    age_s = current - shipped_at.timestamp()
-    if age_s > SHIPPER_STALE_AFTER_S:
-        result["status"] = "warn"
-        result["detail"] = (
-            f"Running, but last shipped {_format_age(age_s)} ago ({last}). "
-            "The process is up but nothing is reaching the allocator."
-        )
+    probe = docker.exec_in(CONTAINER_NAME, ["pgrep", "-f", "ship_logs"])
+    if probe.ok:
+        result["status"] = "pass"
+        result["detail"] = "ship_logs worker running inside the container"
         return result
 
-    result["status"] = "pass"
-    result["detail"] = f"Running; last shipped {last}"
+    result["detail"] = (
+        "No ship_logs worker inside the container — client logs are not "
+        "reaching the allocator. The container is either down (see the "
+        "check above), running an image that predates in-container "
+        "shipping, or missing SHIP_LOGS=1 in its env. Re-run "
+        "`lablink client register --force` to recreate it."
+    )
     return result
 
 
@@ -512,7 +466,7 @@ def run_client_doctor(*, docker: Docker | None = None) -> None:
     checks = [
         _check_client_registered(),
         _check_client_container(docker),
-        _check_log_shipper(),
+        _check_log_shipper(docker),
     ]
 
     _render_checks(