ots-containers 0.3.0__py3-none-any.whl

ots_containers/__init__.py

@@ -0,0 +1,3 @@
+# src/ots_containers/__init__.py
+
+__version__ = "0.2.2"

ots_containers/assets.py

@@ -0,0 +1,32 @@
+# src/ots_containers/assets.py
+
+import subprocess
+from pathlib import Path
+
+from .config import Config
+from .podman import podman
+
+
+def update(cfg: Config, create_volume: bool = True) -> None:
+    if create_volume:
+        podman.volume.create("static_assets", check=False)
+
+    try:
+        result = podman.volume.mount("static_assets", capture_output=True, text=True, check=True)
+    except subprocess.CalledProcessError as e:
+        stderr = e.stderr.strip() if e.stderr else "unknown error"
+        raise SystemExit(f"Failed to mount volume 'static_assets': {stderr}")
+    assets_dir = Path(result.stdout.strip())
+
+    result = podman.create(cfg.resolved_image_with_tag, capture_output=True, text=True, check=True)
+    container_id = result.stdout.strip()
+
+    try:
+        podman.cp(f"{container_id}:/app/public/.", str(assets_dir), check=True)
+        manifest = assets_dir / "web/dist/.vite/manifest.json"
+        if manifest.exists():
+            print(f"Manifest found: {manifest}")
+        else:
+            print(f"Warning: manifest not found at {manifest}")
+    finally:
+        podman.rm(container_id, check=True)

ots_containers/cli.py

@@ -0,0 +1,86 @@
+# src/ots_containers/cli.py
+
+"""
+Manage OTS Podman containers via Quadlets.
+
+Usage:
+
+    ots-containers init
+    ots-containers image pull --tag v0.23.0 --current
+    ots-containers instance deploy 7043
+    ots-containers instance redeploy 7044
+    ots-containers image rollback
+    ots-containers instance redeploy
+    ots-containers assets sync
+
+    # Or run directly without installing:
+    $ cd src/
+    $ pip install -e .
+    $ python -m ots_containers.cli instance deploy 7043
+"""
+
+import cyclopts
+
+from . import __version__
+from .commands import assets as assets_cmd
+from .commands import cloudinit, env, image, init, instance, proxy, service
+from .podman import podman
+
+app = cyclopts.App(
+    name="ots-containers",
+    help="Service orchestration for OTS: Podman Quadlets and systemd services",
+    version=__version__,
+)
+
+# Register topic sub-apps
+app.command(init.app)
+app.command(instance.app)
+app.command(image.app)
+app.command(assets_cmd.app)
+app.command(proxy.app)
+app.command(service.app)
+app.command(cloudinit.app)
+app.command(env.app)
+
+
+@app.default
+def _default():
+    """Show help when no command is specified."""
+    app.help_print([])
+
+
+# Root-level command for quick access
+@app.command
+def ps():
+    """Show running OTS containers (podman view)."""
+    podman.ps(
+        filter="name=onetime",
+        format="table {{.ID}}\t{{.Image}}\t{{.Status}}\t{{.Ports}}\t{{.Names}}",
+    )
+
+
+@app.command
+def version():
+    """Show version and build info."""
+    import subprocess
+    from pathlib import Path
+
+    print(f"ots-containers {__version__}")
+
+    # Try to get git info if available
+    try:
+        pkg_dir = Path(__file__).parent
+        result = subprocess.run(
+            ["git", "-C", str(pkg_dir), "rev-parse", "--short", "HEAD"],
+            capture_output=True,
+            text=True,
+        )
+        if result.returncode == 0:
+            commit = result.stdout.strip()
+            print(f"git commit: {commit}")
+    except Exception:
+        pass
+
+
+if __name__ == "__main__":
+    app()

ots_containers/commands/README.md

@@ -0,0 +1,124 @@
+# CLI Style Guide
+
+## Command Structure
+
+We follow a Heroku-style `topic:command` pattern:
+
+```
+ots-containers <topic> <command> [identifiers] [flags]
+```
+
+## Instance Types
+
+Three container types, each with explicit naming:
+
+| Type | Systemd Unit | Identifier | Use |
+|------|--------------|------------|-----|
+| `web` | `onetime-web@{port}` | Port number | HTTP servers |
+| `worker` | `onetime-worker@{id}` | Name or number | Background jobs |
+| `scheduler` | `onetime-scheduler@{id}` | Name or number | Scheduled tasks |
+
+## Command Syntax
+
+```bash
+# Positional identifiers with type flag
+ots instances restart --web 7043 7044
+ots instances restart --worker billing emails
+ots instances restart --scheduler main
+
+# Auto-discover all types when no args
+ots instances stop                  # stops ALL running instances
+ots instances status                # shows ALL configured instances
+
+# Type-specific discovery
+ots instances status --web          # only web instances
+ots instances logs --scheduler -f   # only scheduler logs
+```
+
+## Topics
+
+Each topic is a separate module with its own `cyclopts.App`:
+
+| Topic | Purpose |
+|-------|---------|
+| `instance` | Container lifecycle and runtime control |
+| `service` | Native systemd services (Valkey, Redis) |
+| `image` | Container image management |
+| `assets` | Static asset management |
+| `cloudinit` | Cloud-init configuration generation |
+| `env` | Environment file management |
+
+To add a new topic, create a module and register it in `cli.py`.
+
+## Two-Level Abstraction
+
+Commands are categorized by their impact:
+
+### High-level (affects config + state)
+Commands that modify quadlet templates, database records, or both:
+- `deploy`, `redeploy`, `undeploy`
+
+These commands should document their config impact in the docstring.
+
+### Low-level (runtime control only)
+Commands that only interact with systemd, no config changes:
+- `start`, `stop`, `restart`, `status`, `logs`, `enable`, `disable`, `exec`
+
+These commands should explicitly state they do NOT refresh config.
+
+## Naming Conventions
+
+| Pattern | Example | Use for |
+|---------|---------|---------|
+| Verb | `deploy`, `sync` | Actions |
+| `--flag` | `--force`, `--yes` | Boolean options |
+| `--option VALUE` | `--delay 5`, `--lines 50` | Value options |
+| `--type` shortcuts | `--web`, `--worker`, `--scheduler` | Instance type selection |
+
+## Default Commands
+
+Use `@app.default` for the "list" operation when invoking a topic without a subcommand:
+
+```python
+@app.default
+def list_instances(
+    identifiers: Identifiers = (),
+    web: WebFlag = False,
+    worker: WorkerFlag = False,
+    scheduler: SchedulerFlag = False,
+):
+    """List instances with status and deployment info."""
+    ...
+```
+
+This follows Heroku's pattern where `heroku apps` lists apps.
+
+## Help Text
+
+First line: Brief imperative description.
+Blank line, then: Config impact and usage notes.
+Include Examples section with common use cases:
+
+```python
+@app.command
+def redeploy(...):
+    """Regenerate quadlet and restart containers.
+
+    Rewrites quadlet config, restarts service. Records to timeline for audit.
+    Use --force to fully teardown and recreate.
+
+    Examples:
+        ots instances redeploy                      # Redeploy all running
+        ots instances redeploy --web                # Redeploy web instances
+        ots instances redeploy --web 7043 7044      # Redeploy specific web
+        ots instances redeploy --scheduler main     # Redeploy specific scheduler
+    """
+```
+
+## Adding Commands
+
+1. Add to existing topic module, or create new topic
+2. Use shared helpers from `_helpers.py` (`resolve_identifiers`, `for_each_instance`)
+3. Use type annotations from `annotations.py` (`Identifiers`, `WebFlag`, etc.)
+4. Document config impact and include Examples in docstring
+5. Register new topics in `cli.py` via `app.command(topic.app)`

ots_containers/commands/__init__.py

@@ -0,0 +1,9 @@
+# src/ots_containers/commands/__init__.py
+"""Command topic modules for ots-containers CLI."""
+
+from . import assets as assets
+from . import image as image
+from . import init as init
+from . import instance as instance
+from . import proxy as proxy
+from . import service as service

ots_containers/commands/assets.py

@@ -0,0 +1,29 @@
+# src/ots_containers/commands/assets.py
+"""Asset management commands for OTS containers."""
+
+from typing import Annotated
+
+import cyclopts
+
+from .. import assets as assets_module
+from ..config import Config
+
+app = cyclopts.App(name="assets", help="Extract web assets from container image to volume")
+
+
+@app.command
+def sync(
+    create_volume: Annotated[
+        bool,
+        cyclopts.Parameter(help="Create volume if it doesn't exist (use on first deploy)"),
+    ] = False,
+):
+    """Copy /app/public from container image to static_assets podman volume.
+
+    Extracts web assets (JS, CSS, images) from the OTS container image
+    to a shared volume that Caddy serves directly. Use --create-volume
+    on initial setup.
+    """
+    cfg = Config()
+    cfg.validate()
+    assets_module.update(cfg, create_volume=create_volume)

ots_containers/commands/cloudinit/__init__.py

@@ -0,0 +1,6 @@
+# src/ots_containers/commands/cloudinit/__init__.py
+"""Cloud-init configuration generation for OTS infrastructure."""
+
+from .app import app
+
+__all__ = ["app"]

ots_containers/commands/cloudinit/app.py

@@ -0,0 +1,158 @@
+# src/ots_containers/commands/cloudinit/app.py
+"""Cloud-init configuration generation commands.
+
+Generates cloud-init YAML with Debian 13 (Trixie) DEB822-style apt sources.
+"""
+
+import sys
+from pathlib import Path
+from typing import Annotated
+
+import cyclopts
+
+from .templates import generate_cloudinit_config
+
+app = cyclopts.App(
+    name="cloudinit",
+    help="Generate cloud-init configurations for OTS infrastructure",
+)
+
+
+@app.default
+def _default():
+    """Show cloud-init commands help."""
+    print("Cloud-init configuration generation for OTS infrastructure")
+    print()
+    print("Supports Debian 13 (Trixie) DEB822-style apt sources")
+    print()
+    print("Use 'ots-containers cloudinit --help' for available commands")
+
+
+@app.command
+def generate(
+    output: Annotated[
+        str | None,
+        cyclopts.Parameter(help="Output file path (default: stdout)"),
+    ] = None,
+    *,
+    include_postgresql: Annotated[
+        bool, cyclopts.Parameter(help="Include PostgreSQL apt repository")
+    ] = False,
+    include_valkey: Annotated[
+        bool, cyclopts.Parameter(help="Include Valkey apt repository")
+    ] = False,
+    postgresql_key: Annotated[
+        str | None,
+        cyclopts.Parameter(help="Path to PostgreSQL GPG key file"),
+    ] = None,
+    valkey_key: Annotated[
+        str | None,
+        cyclopts.Parameter(help="Path to Valkey GPG key file"),
+    ] = None,
+):
+    """Generate cloud-init configuration with Debian 13 apt sources.
+
+    Generates a cloud-init YAML file with:
+    - Debian 13 (Trixie) main repositories in DEB822 format
+    - Optional PostgreSQL official repository
+    - Optional Valkey repository
+    - Package update/upgrade configuration
+
+    Example:
+        ots-containers cloudinit generate > user-data.yaml
+        ots-containers cloudinit generate --output /tmp/cloud-init.yaml
+        ots-containers cloudinit generate --include-postgresql --postgresql-key /path/to/pgp.asc
+    """
+    # Read GPG keys if provided
+    postgresql_gpg = None
+    valkey_gpg = None
+
+    if include_postgresql and postgresql_key:
+        postgresql_gpg = Path(postgresql_key).read_text()
+    elif include_postgresql:
+        print(
+            "Warning: --include-postgresql specified but no --postgresql-key provided",
+            file=sys.stderr,
+        )
+        print("PostgreSQL repository will use inline key placeholder", file=sys.stderr)
+
+    if include_valkey and valkey_key:
+        valkey_gpg = Path(valkey_key).read_text()
+    elif include_valkey:
+        print(
+            "Warning: --include-valkey specified but no --valkey-key provided",
+            file=sys.stderr,
+        )
+        print("Valkey repository will use inline key placeholder", file=sys.stderr)
+
+    # Generate configuration
+    config = generate_cloudinit_config(
+        include_postgresql=include_postgresql,
+        include_valkey=include_valkey,
+        postgresql_gpg_key=postgresql_gpg,
+        valkey_gpg_key=valkey_gpg,
+    )
+
+    # Output
+    if output:
+        Path(output).write_text(config)
+        print(f"[created] {output}")
+    else:
+        print(config)
+
+
+@app.command
+def validate(
+    file_path: Annotated[
+        str,
+        cyclopts.Parameter(help="Path to cloud-init YAML file"),
+    ],
+):
+    """Validate a cloud-init configuration file.
+
+    Checks for:
+    - Valid YAML syntax
+    - Required cloud-init sections
+    - DEB822 apt sources format
+
+    Example:
+        ots-containers cloudinit validate user-data.yaml
+    """
+    import yaml
+
+    try:
+        config_path = Path(file_path)
+        if not config_path.exists():
+            print(f"[error] File not found: {file_path}", file=sys.stderr)
+            sys.exit(1)
+
+        content = config_path.read_text()
+        data = yaml.safe_load(content)
+
+        # Basic validation
+        errors = []
+
+        if not isinstance(data, dict):
+            errors.append("Root element must be a dictionary")
+
+        if "apt" in data and "sources_list" in data["apt"]:
+            sources_list = data["apt"]["sources_list"]
+            # Check for DEB822 format indicators
+            if "Types:" not in sources_list and "URIs:" not in sources_list:
+                errors.append("apt.sources_list doesn't appear to use DEB822 format")
+
+        if errors:
+            print(f"[error] Validation failed for {file_path}:", file=sys.stderr)
+            for error in errors:
+                print(f"  - {error}", file=sys.stderr)
+            sys.exit(1)
+        else:
+            print(f"[ok] {file_path} is valid")
+
+    except yaml.YAMLError as e:
+        print(f"[error] Invalid YAML in {file_path}:", file=sys.stderr)
+        print(f"  {e}", file=sys.stderr)
+        sys.exit(1)
+    except Exception as e:
+        print(f"[error] Validation failed: {e}", file=sys.stderr)
+        sys.exit(1)

ots_containers/commands/cloudinit/templates.py

@@ -0,0 +1,127 @@
+# src/ots_containers/commands/cloudinit/templates.py
+"""Cloud-init configuration templates with Debian 13 DEB822 apt sources."""
+
+
+def get_debian13_sources_list() -> str:
+    """Get just the Debian 13 DEB822 sources.list content.
+
+    Returns:
+        DEB822-formatted sources.list content
+    """
+    return """Types: deb
+URIs: http://deb.debian.org/debian
+Suites: trixie trixie-updates
+Components: main contrib non-free non-free-firmware
+Signed-By: /usr/share/keyrings/debian-archive-keyring.gpg
+
+Types: deb
+URIs: http://deb.debian.org/debian
+Suites: trixie-backports
+Components: main contrib non-free non-free-firmware
+Signed-By: /usr/share/keyrings/debian-archive-keyring.gpg
+
+Types: deb
+URIs: http://security.debian.org/debian-security
+Suites: trixie-security
+Components: main contrib non-free non-free-firmware
+Signed-By: /usr/share/keyrings/debian-archive-keyring.gpg
+"""
+
+
+def generate_cloudinit_config(
+    *,
+    include_postgresql: bool = False,
+    include_valkey: bool = False,
+    postgresql_gpg_key: str | None = None,
+    valkey_gpg_key: str | None = None,
+) -> str:
+    """Generate cloud-init YAML with Debian 13 DEB822-style apt sources.
+
+    Args:
+        include_postgresql: Include PostgreSQL official repository
+        include_valkey: Include Valkey repository
+        postgresql_gpg_key: PostgreSQL GPG public key content
+        valkey_gpg_key: Valkey GPG public key content
+
+    Returns:
+        Complete cloud-init YAML configuration as string
+    """
+    # Base configuration with Debian 13 main repositories
+    # Get the sources list and indent it for YAML
+    sources_list = get_debian13_sources_list().rstrip("\n")
+    indented_sources = "\n".join(f"    {line}" for line in sources_list.split("\n"))
+
+    config_parts = [
+        "#cloud-config",
+        "# Generated cloud-init configuration for OTS infrastructure",
+        "# Debian 13 (Trixie) with DEB822-style apt sources",
+        "",
+        "package_update: true",
+        "package_upgrade: true",
+        "package_reboot_if_required: true",
+        "",
+        "apt:",
+        "  sources_list: |",
+        indented_sources,
+    ]
+
+    # Add third-party repositories if requested
+    sources = []
+
+    if include_postgresql:
+        postgresql_source = {
+            "source": "deb http://apt.postgresql.org/pub/repos/apt trixie-pgdg main",
+        }
+        if postgresql_gpg_key:
+            postgresql_source["key"] = postgresql_gpg_key
+        else:
+            postgresql_source["key"] = "# PostgreSQL GPG key placeholder - replace with actual key"
+        sources.append(("postgresql", postgresql_source))
+
+    if include_valkey:
+        valkey_source = {
+            "source": "deb https://packages.valkey.io/deb/ trixie main",
+        }
+        if valkey_gpg_key:
+            valkey_source["key"] = valkey_gpg_key
+        else:
+            valkey_source["key"] = "# Valkey GPG key placeholder - replace with actual key"
+        sources.append(("valkey", valkey_source))
+
+    # Add sources section if we have any
+    if sources:
+        config_parts.append("  sources:")
+        for name, source_config in sources:
+            config_parts.append(f"    {name}:")
+            config_parts.append(f'      source: "{source_config["source"]}"')
+            if "key" in source_config:
+                # Multi-line key handling
+                key_content = source_config["key"]
+                if "\n" in key_content:
+                    config_parts.append("      key: |")
+                    for line in key_content.split("\n"):
+                        config_parts.append(f"        {line}")
+                else:
+                    config_parts.append(f'      key: "{key_content}"')
+
+    # Add common packages section
+    config_parts.extend(
+        [
+            "",
+            "packages:",
+            "  - curl",
+            "  - wget",
+            "  - git",
+            "  - vim",
+            "  - podman",
+            "  - systemd-container",
+        ]
+    )
+
+    if include_postgresql:
+        config_parts.append("  - postgresql-client")
+
+    if include_valkey:
+        config_parts.append("  - valkey")
+
+    return "\n".join(config_parts) + "\n"

ots_containers/commands/common.py

@@ -0,0 +1,71 @@
+# src/ots_containers/commands/common.py
+"""Shared CLI annotations for consistency across commands.
+
+All common flags use long+short forms for consistency:
+  --quiet, -q
+  --dry-run, -n
+  --yes, -y
+  --follow, -f
+  --lines, -n
+  --json, -j
+"""
+
+from typing import Annotated
+
+import cyclopts
+
+# Output control
+Quiet = Annotated[
+    bool,
+    cyclopts.Parameter(
+        name=["--quiet", "-q"],
+        help="Suppress output",
+    ),
+]
+
+DryRun = Annotated[
+    bool,
+    cyclopts.Parameter(
+        name=["--dry-run", "-n"],
+        help="Show what would be done without doing it",
+        negative=[],  # Disable --no-dry-run generation
+    ),
+]
+
+
+# Confirmation
+Yes = Annotated[
+    bool,
+    cyclopts.Parameter(
+        name=["--yes", "-y"],
+        help="Skip confirmation prompts",
+    ),
+]
+
+
+# Log viewing
+Follow = Annotated[
+    bool,
+    cyclopts.Parameter(
+        name=["--follow", "-f"],
+        help="Follow log output",
+    ),
+]
+
+Lines = Annotated[
+    int,
+    cyclopts.Parameter(
+        name=["--lines", "-n"],
+        help="Number of lines to show",
+    ),
+]
+
+
+# JSON output
+JsonOutput = Annotated[
+    bool,
+    cyclopts.Parameter(
+        name=["--json", "-j"],
+        help="Output as JSON",
+    ),
+]

ots_containers/commands/env/__init__.py

@@ -0,0 +1,6 @@
+# src/ots_containers/commands/env/__init__.py
+"""Environment file management commands."""
+
+from .app import app
+
+__all__ = ["app"]