ots-containers 0.3.0__py3-none-any.whl → 0.3.2__py3-none-any.whl

ots_containers/__init__.py

@@ -1,3 +1,8 @@
 # src/ots_containers/__init__.py
 
-__version__ = "0.2.2"
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("ots-containers")
+except PackageNotFoundError:
+    __version__ = "0.0.0+dev"

ots_containers/commands/README.md

@@ -12,10 +12,10 @@ ots-containers <topic> <command> [identifiers] [flags]
 
 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 |
+| 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
@@ -39,14 +39,14 @@ ots instances logs --scheduler -f   # only scheduler logs
 
 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 |
+| 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`.
 
@@ -55,24 +55,28 @@ To add a new topic, create a module and register it in `cli.py`.
 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 |
+| 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

ots_containers/commands/assets.py

@@ -1,4 +1,5 @@
 # src/ots_containers/commands/assets.py
+
 """Asset management commands for OTS containers."""
 
 from typing import Annotated
@@ -25,5 +26,4 @@ def sync(
     on initial setup.
     """
     cfg = Config()
-    cfg.validate()
     assets_module.update(cfg, create_volume=create_volume)

ots_containers/commands/cloudinit/app.py

@@ -1,4 +1,5 @@
 # src/ots_containers/commands/cloudinit/app.py
+
 """Cloud-init configuration generation commands.
 
 Generates cloud-init YAML with Debian 13 (Trixie) DEB822-style apt sources.
@@ -74,7 +75,10 @@ def generate(
             "Warning: --include-postgresql specified but no --postgresql-key provided",
             file=sys.stderr,
         )
-        print("PostgreSQL repository will use inline key placeholder", 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()

ots_containers/commands/cloudinit/templates.py

@@ -1,4 +1,5 @@
 # src/ots_containers/commands/cloudinit/templates.py
+
 """Cloud-init configuration templates with Debian 13 DEB822 apt sources."""
 
 

ots_containers/commands/common.py

@@ -1,4 +1,5 @@
 # src/ots_containers/commands/common.py
+
 """Shared CLI annotations for consistency across commands.
 
 All common flags use long+short forms for consistency:

ots_containers/commands/env/app.py

@@ -1,4 +1,5 @@
 # src/ots_containers/commands/env/app.py
+
 """Environment file management commands.
 
 Process environment files to extract secrets and prepare for container deployment.
@@ -274,7 +275,10 @@ def quadlet_lines(
     parsed = EnvFile.parse(path)
 
     if not parsed.secret_variable_names:
-        print("Error: No SECRET_VARIABLE_NAMES defined in environment file.", file=sys.stderr)
+        print(
+            "Error: No SECRET_VARIABLE_NAMES defined in environment file.",
+            file=sys.stderr,
+        )
         return 1
 
     secrets, messages = extract_secrets(parsed)

ots_containers/commands/image/app.py

@@ -1,4 +1,5 @@
 # src/ots_containers/commands/image/app.py
+
 """Image management commands for OTS containers.
 
 Supports pulling from multiple registries:
@@ -33,12 +34,12 @@ app = cyclopts.App(
 @app.command
 def pull(
     tag: Annotated[
-        str,
+        str | None,
         cyclopts.Parameter(
             name=["--tag", "-t"],
-            help="Image tag to pull (e.g., v0.23.0, latest)",
+            help="Image tag to pull (default: from TAG env var)",
         ),
-    ],
+    ] = None,
     image: Annotated[
         str,
         cyclopts.Parameter(
@@ -60,6 +61,13 @@ def pull(
             help="Pull from private registry (uses configured OTS_REGISTRY)",
         ),
     ] = False,
+    platform: Annotated[
+        str | None,
+        cyclopts.Parameter(
+            name=["--platform", "-p"],
+            help="Target platform (e.g., linux/amd64, linux/arm64)",
+        ),
+    ] = None,
     quiet: Quiet = False,
 ):
     """Pull a container image from registry.
@@ -67,11 +75,19 @@ def pull(
     Examples:
         ots image pull --tag v0.23.0
         ots image pull --tag latest --current
+        TAG=dev ots image pull                  # Use TAG env var
         ots image pull --tag v0.23.0 --image docker.io/onetimesecret/onetimesecret
         ots image pull --tag v0.23.0 --private  # Pull from private registry
+        ots image pull --tag dev --platform linux/amd64  # Pull amd64 on Apple Silicon
     """
     cfg = Config()
 
+    # Resolve tag from env var if not provided
+    resolved_tag = tag or cfg.tag
+    if not resolved_tag:
+        print("Error: --tag is required (or set TAG env var)")
+        raise SystemExit(1)
+
     # Use private registry if requested
     if private:
         if not cfg.private_image:
@@ -79,20 +95,23 @@ def pull(
             raise SystemExit(1)
         image = cfg.private_image
 
-    full_image = f"{image}:{tag}"
+    full_image = f"{image}:{resolved_tag}"
 
     if not quiet:
         print(f"Pulling {full_image}...")
 
     try:
         # Use auth file for authenticated registries
-        podman.pull(
-            full_image,
-            authfile=str(cfg.registry_auth_file),
-            check=True,
-            capture_output=True,
-            text=True,
-        )
+        pull_kwargs = {
+            "authfile": str(cfg.registry_auth_file),
+            "check": True,
+            "capture_output": True,
+            "text": True,
+        }
+        if platform:
+            pull_kwargs["platform"] = platform
+
+        podman.pull(full_image, **pull_kwargs)
         if not quiet:
             print(f"Successfully pulled {full_image}")
     except Exception as e:
@@ -100,7 +119,7 @@ def pull(
         db.record_deployment(
             cfg.db_path,
             image=image,
-            tag=tag,
+            tag=resolved_tag,
             action="pull",
             success=False,
             notes=str(e),
@@ -111,19 +130,19 @@ def pull(
     db.record_deployment(
         cfg.db_path,
         image=image,
-        tag=tag,
+        tag=resolved_tag,
         action="pull",
         success=True,
     )
 
     # Set as current if requested
     if set_as_current:
-        previous = db.set_current(cfg.db_path, image, tag)
+        previous = db.set_current(cfg.db_path, image, resolved_tag)
         if not quiet:
             if previous:
-                print(f"Set CURRENT to {tag} (previous: {previous})")
+                print(f"Set CURRENT to {resolved_tag} (previous: {previous})")
             else:
-                print(f"Set CURRENT to {tag}")
+                print(f"Set CURRENT to {resolved_tag}")
 
 
 @app.default

ots_containers/commands/init.py

@@ -1,4 +1,5 @@
 # src/ots_containers/commands/init.py
+
 """Init command for idempotent setup of ots-containers.
 
 Creates required directories and initializes the deployment database.
@@ -13,7 +14,7 @@ from typing import Annotated
 import cyclopts
 
 from ots_containers import db
-from ots_containers.config import Config
+from ots_containers.config import CONFIG_FILES, Config
 
 app = cyclopts.App(
     name="init",
@@ -125,16 +126,17 @@ def init(
             prefix = "Re-initializing" if is_reinit else "Initializing"
             print(f"{prefix} ots-containers...")
 
-    # 1. App Configuration - user-managed config files
+    # 1. App Configuration - user-managed config files (all optional)
     # Note: /etc/default/onetimesecret and Podman secrets are managed separately
     if not quiet or check:
         print("\nApp Configuration:")
     if check:
-        if cfg.config_yaml.exists():
-            print(f"  [ok] {cfg.config_yaml}")
-        else:
-            print(f"  [missing] {cfg.config_yaml}")
-            all_ok = False
+        for fname in CONFIG_FILES:
+            fpath = cfg.config_dir / fname
+            if fpath.exists():
+                print(f"  [ok] {fpath}")
+            else:
+                print(f"  [optional] {fpath}")
     else:
         result = _create_directory(cfg.config_dir, mode=0o755, quiet=True)
         if result is None:
@@ -143,21 +145,27 @@ def init(
             # Directory exists or was created - now handle config files
             if source_dir:
                 src = Path(source_dir)
-                if _copy_template(src / "config.yaml", cfg.config_yaml, quiet=quiet) is None:
-                    all_ok = False
+                for fname in CONFIG_FILES:
+                    if _copy_template(src / fname, cfg.config_dir / fname, quiet=quiet) is None:
+                        all_ok = False
             elif not quiet:
-                # Report status of config files
-                if cfg.config_yaml.exists():
-                    print(f"  [ok] {cfg.config_yaml}")
-                else:
-                    print(f"  [missing] {cfg.config_yaml}")
+                for fname in CONFIG_FILES:
+                    fpath = cfg.config_dir / fname
+                    if fpath.exists():
+                        print(f"  [ok] {fpath}")
+                    else:
+                        print(f"  [optional] {fpath}")
 
     # 2. System Configuration - quadlet files
     if not quiet or check:
         print("\nSystem Configuration:")
     quadlet_dir = cfg.web_template_path.parent
     users_dir = quadlet_dir / "users"
-    template_paths = [cfg.web_template_path, cfg.worker_template_path, cfg.scheduler_template_path]
+    template_paths = [
+        cfg.web_template_path,
+        cfg.worker_template_path,
+        cfg.scheduler_template_path,
+    ]
     if check:
         for template_path in template_paths:
             if template_path.exists():
@@ -243,8 +251,7 @@ def init(
             print("\nInitialization incomplete - some operations failed.")
             print("Try running with elevated privileges: sudo ots init")
         print("\nNext steps:")
-        if not cfg.config_yaml.exists():
-            print(f"  1. Create {cfg.config_yaml}")
+        print(f"  1. (Optional) Place config overrides in {cfg.config_dir}/")
         print("  2. Create /etc/default/onetimesecret with infrastructure env vars")
         print("  3. Create Podman secrets: ots_hmac_secret, ots_secret, ots_session_secret")
         print("  4. Run 'ots image pull --tag <version>' to pull an image")

ots_containers/commands/instance/__init__.py

@@ -14,6 +14,7 @@ from .annotations import (
 )
 from .app import (
     app,
+    config_transform,
     deploy,
     disable,
     enable,
@@ -23,6 +24,7 @@ from .app import (
     redeploy,
     restart,
     run,
+    shell,
     show_env,
     start,
     status,
@@ -39,6 +41,7 @@ __all__ = [
     "WebFlag",
     "WorkerFlag",
     "app",
+    "config_transform",
     "deploy",
     "disable",
     "enable",
@@ -49,6 +52,7 @@ __all__ = [
     "resolve_instance_type",
     "restart",
     "run",
+    "shell",
     "show_env",
     "start",
     "status",

ots_containers/commands/instance/_helpers.py

@@ -1,11 +1,14 @@
 # src/ots_containers/commands/instance/_helpers.py
+
 """Internal helper functions for instance commands."""
 
 import shlex
 import time
 from collections.abc import Callable, Sequence
+from pathlib import Path
 
 from ots_containers import systemd
+from ots_containers.environment_file import get_secrets_from_env_file
 
 from .annotations import InstanceType
 
@@ -36,10 +39,32 @@ def format_journalctl_hint(instances: dict[InstanceType, list[str]]) -> str:
     if not tags:
         return ""
 
-    tag_args = " ".join(f"-t {tag}" for tag in tags)
+    tag_args = " ".join(f"-t {shlex.quote(tag)}" for tag in tags)
     return f"journalctl {tag_args} -f"
 
 
+def build_secret_args(env_file: Path) -> list[str]:
+    """Build podman --secret arguments from environment file.
+
+    Reads SECRET_VARIABLE_NAMES from the env file and generates
+    corresponding --secret flags for podman run.
+
+    Args:
+        env_file: Path to environment file (e.g., /etc/default/onetimesecret)
+
+    Returns:
+        List of command arguments: ["--secret", "name,type=env,target=VAR", ...]
+    """
+    if not env_file.exists():
+        return []
+
+    secret_specs = get_secrets_from_env_file(env_file)
+    args: list[str] = []
+    for spec in secret_specs:
+        args.extend(["--secret", f"{spec.secret_name},type=env,target={spec.env_var_name}"])
+    return args
+
+
 def resolve_identifiers(
     identifiers: tuple[str, ...],
     instance_type: InstanceType | None,

ots_containers/commands/instance/annotations.py

@@ -1,4 +1,5 @@
 # src/ots_containers/commands/instance/annotations.py
+
 """Type annotations for instance commands.
 
 Instance types:
@@ -12,13 +13,13 @@ Identifier patterns:
 - Scheduler: numeric or named (main, 1)
 """
 
-from enum import Enum
+from enum import StrEnum
 from typing import Annotated
 
 import cyclopts
 
 
-class InstanceType(str, Enum):
+class InstanceType(StrEnum):
     """Type of container instance."""
 
     WEB = "web"