octopize.deploy_tool 0.1.0__py3-none-any.whl

octopize_avatar_deploy/version_compat.py

@@ -0,0 +1,344 @@
+"""
+Version compatibility checking for Avatar deployment tool.
+
+Ensures that the script version is compatible with template and config versions.
+Prevents old scripts from modifying new templates (forward compatibility).
+"""
+
+import re
+from pathlib import Path
+
+# Script version (semantic versioning: MAJOR.MINOR.PATCH)
+SCRIPT_VERSION = "2.1.0"
+
+
+class VersionError(Exception):
+    """Raised when version compatibility check fails."""
+
+    pass
+
+
+def parse_version(version_str: str) -> tuple[int, int, int]:
+    """
+    Parse semantic version string into tuple.
+
+    Args:
+        version_str: Version string like "1.2.3"
+
+    Returns:
+        Tuple of (major, minor, patch)
+
+    Raises:
+        ValueError: If version string is invalid
+    """
+    match = re.match(r"^(\d+)\.(\d+)\.(\d+)$", version_str.strip())
+    if not match:
+        raise ValueError(f"Invalid version string: {version_str}")
+    return (int(match.group(1)), int(match.group(2)), int(match.group(3)))
+
+
+def parse_version_constraint(constraint: str) -> tuple[str, tuple[int, int, int]]:
+    """
+    Parse version constraint like ">=1.0.0" or "<2.0.0".
+
+    Args:
+        constraint: Version constraint string
+
+    Returns:
+        Tuple of (operator, version_tuple)
+    """
+    match = re.match(r"^([><=]+)([\d.]+)$", constraint.strip())
+    if not match:
+        raise ValueError(f"Invalid constraint: {constraint}")
+
+    operator, version_str = match.groups()
+    version = parse_version(version_str)
+    return operator, version
+
+
+def check_constraint(
+    version: tuple[int, int, int],
+    operator: str,
+    constraint_version: tuple[int, int, int],
+) -> bool:
+    """
+    Check if version satisfies constraint.
+
+    Args:
+        version: Version tuple to check
+        operator: Comparison operator (>=, <, >, <=, ==)
+        constraint_version: Version tuple to compare against
+
+    Returns:
+        True if constraint is satisfied
+    """
+    if operator == ">=":
+        return version >= constraint_version
+    elif operator == ">":
+        return version > constraint_version
+    elif operator == "<=":
+        return version <= constraint_version
+    elif operator == "<":
+        return version < constraint_version
+    elif operator == "==":
+        return version == constraint_version
+    else:
+        raise ValueError(f"Unknown operator: {operator}")
+
+
+def check_version_compatibility(script_version: str, required_version: str) -> bool:
+    """
+    Check if script version satisfies requirement.
+
+    Args:
+        script_version: Current script version (e.g., "1.0.0")
+        required_version: Required version spec (e.g., ">=1.0.0,<2.0.0")
+
+    Returns:
+        True if compatible
+
+    Raises:
+        VersionError: If versions are incompatible
+    """
+    script_ver = parse_version(script_version)
+
+    # Parse requirement (can be comma-separated constraints)
+    constraints = [c.strip() for c in required_version.split(",")]
+
+    for constraint in constraints:
+        operator, required_ver = parse_version_constraint(constraint)
+        if not check_constraint(script_ver, operator, required_ver):
+            return False
+
+    return True
+
+
+def extract_template_version(template_path: Path) -> str | None:
+    """
+    Extract version from template file header.
+
+    Expected format:
+    # Template Version: 1.0.0
+    # Compatible with octopize-avatar-deploy: >=1.0.0,<2.0.0
+
+    Args:
+        template_path: Path to template file
+
+    Returns:
+        Version string or None if not found
+    """
+    try:
+        content = template_path.read_text()
+
+        # Look for version in first 20 lines
+        lines = content.split("\n")[:20]
+
+        for line in lines:
+            # Match: # Template Version: 1.0.0
+            if "template version:" in line.lower():
+                match = re.search(r"(\d+\.\d+\.\d+)", line)
+                if match:
+                    return match.group(1)
+
+        return None
+    except Exception:
+        return None
+
+
+def extract_compatibility_spec(template_path: Path) -> str | None:
+    """
+    Extract compatibility spec from template file header.
+
+    Args:
+        template_path: Path to template file
+
+    Returns:
+        Compatibility spec string or None if not found
+    """
+    try:
+        content = template_path.read_text()
+        lines = content.split("\n")[:20]
+
+        for line in lines:
+            # Match: # Compatible with octopize-avatar-deploy: >=1.0.0,<2.0.0
+            if "compatible with" in line.lower():
+                match = re.search(r":\s*([\d\s.,<>=]+)$", line)
+                if match:
+                    return match.group(1).strip()
+
+        return None
+    except Exception:
+        return None
+
+
+def validate_template_compatibility(
+    template_path: Path, script_version: str = SCRIPT_VERSION, verbose: bool = False
+) -> bool:
+    """
+    Validate that script version is compatible with template.
+
+    Args:
+        template_path: Path to template file
+        script_version: Script version to check
+        verbose: Print validation details
+
+    Returns:
+        True if compatible or no version info found
+
+    Raises:
+        VersionError: If versions are incompatible
+    """
+    template_version = extract_template_version(template_path)
+    compatibility_spec = extract_compatibility_spec(template_path)
+
+    if verbose:
+        print(f"Validating {template_path.name}:")
+        print(f"  Template version: {template_version or 'not specified'}")
+        print(f"  Compatibility: {compatibility_spec or 'not specified'}")
+        print(f"  Script version: {script_version}")
+
+    # If no version info in template, assume compatible (legacy template)
+    if not compatibility_spec:
+        if verbose:
+            print("  ✓ No version constraints (assuming compatible)")
+        return True
+
+    # Check compatibility
+    try:
+        compatible = check_version_compatibility(script_version, compatibility_spec)
+
+        if compatible:
+            if verbose:
+                print("  ✓ Compatible")
+            return True
+        else:
+            raise VersionError(
+                f"Script version {script_version} is not compatible with "
+                f"{template_path.name} (requires {compatibility_spec}). "
+                f"Please upgrade octopize-avatar-deploy: "
+                f"pip install --upgrade octopize-avatar-deploy"
+            )
+
+    except ValueError as e:
+        if verbose:
+            print(f"  ⚠ Warning: Invalid version spec: {e}")
+        # If version spec is invalid, assume compatible to avoid breaking
+        return True
+
+
+def validate_all_templates(
+    templates_dir: Path, script_version: str = SCRIPT_VERSION, verbose: bool = False
+) -> bool:
+    """
+    Validate all templates in directory.
+
+    Args:
+        templates_dir: Directory containing templates
+        script_version: Script version to check
+        verbose: Print validation details
+
+    Returns:
+        True if all templates are compatible
+
+    Raises:
+        VersionError: If any template is incompatible
+    """
+    if verbose:
+        print("\nValidating template compatibility...")
+        print("=" * 60)
+
+    templates = list(templates_dir.glob("*.template"))
+
+    if not templates:
+        if verbose:
+            print("No templates found")
+        return True
+
+    for template in templates:
+        validate_template_compatibility(template, script_version, verbose)
+
+    if verbose:
+        print(f"\n✓ All {len(templates)} templates are compatible")
+
+    return True
+
+
+def validate_template_version(
+    version_file: Path, script_version: str = SCRIPT_VERSION, verbose: bool = False
+) -> None:
+    """
+    Validate that the template version is compatible with the script version.
+
+    This reads the .template-version file which should contain:
+    - First line: template version (e.g., "0.1.0")
+    - Optional second line: compatibility constraint (e.g., ">=1.0.0,<2.0.0")
+
+    Args:
+        version_file: Path to .template-version file
+        script_version: Script version to check against
+        verbose: Print validation details
+
+    Raises:
+        VersionError: If template version is incompatible with script version
+    """
+    try:
+        content = version_file.read_text().strip().split("\n")
+
+        if not content or not content[0].strip():
+            raise VersionError(
+                f"Invalid .template-version file: {version_file} (empty or missing version)"
+            )
+
+        template_version = content[0].strip()
+
+        # Parse template version to validate format
+        try:
+            parse_version(template_version)
+        except ValueError as e:
+            raise VersionError(
+                f"Invalid template version format in {version_file}: {template_version}"
+            ) from e
+
+        # Check for compatibility constraint (optional second line)
+        compatibility_spec = None
+        if len(content) > 1 and content[1].strip():
+            compatibility_spec = content[1].strip()
+
+        if verbose:
+            print(f"\nValidating template version from {version_file.name}:")
+            print(f"  Template version: {template_version}")
+            print(f"  Compatibility spec: {compatibility_spec or 'not specified'}")
+            print(f"  Script version: {script_version}")
+
+        # If no compatibility spec, accept any script version
+        if not compatibility_spec:
+            if verbose:
+                print("  ✓ No version constraints (compatible)")
+            return
+
+        # Check compatibility
+        try:
+            compatible = check_version_compatibility(script_version, compatibility_spec)
+
+            if compatible:
+                if verbose:
+                    print("  ✓ Compatible")
+            else:
+                raise VersionError(
+                    f"Script version {script_version} is not compatible with "
+                    f"template version {template_version} (requires {compatibility_spec}). "
+                    f"Please upgrade octopize-avatar-deploy: "
+                    f"pip install --upgrade octopize-avatar-deploy"
+                )
+
+        except ValueError as e:
+            # Invalid constraint format - log warning but don't fail
+            if verbose:
+                print(f"  ⚠ Warning: Invalid compatibility spec: {e}")
+
+    except FileNotFoundError:
+        raise VersionError(f"Template version file not found: {version_file}") from None
+    except Exception as e:
+        if isinstance(e, VersionError):
+            raise
+        raise VersionError(f"Failed to validate template version: {e}") from e

octopize_deploy_tool-0.1.0.dist-info/METADATA

@@ -0,0 +1,346 @@
+Metadata-Version: 2.4
+Name: octopize.deploy_tool
+Version: 0.1.0
+Summary: Deployment configuration tool for Octopize Avatar platform
+Project-URL: Homepage, https://octopize.io
+Project-URL: Documentation, https://docs.octopize.io/docs/deploying/self-hosted
+Project-URL: Repository, https://github.com/octopize/avatar-deployment
+Project-URL: Issues, https://github.com/octopize/avatar-deployment/issues
+Author-email: Octopize <contact@octopize.io>
+License: MIT
+Keywords: avatar,configuration,deployment,octopize
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: System :: Installation/Setup
+Classifier: Topic :: System :: Systems Administration
+Requires-Python: >=3.13
+Requires-Dist: jinja2>=3.1.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rich>=13.0.0
+Provides-Extra: dev
+Requires-Dist: mypy; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Octopize Avatar Deployment Tool
+
+Automated configuration tool for deploying Octopize Avatar platform using Docker Compose.
+
+## Overview
+
+This tool simplifies Avatar deployment by:
+- **📦 Standalone package** - No need to clone the entire repository
+- **⬇️ Downloads templates** automatically from GitHub
+- **🎯 Deployment presets** - dev-mode, production, airgapped configurations
+- **🔐 Secure secrets generation** - Automatic creation of encryption keys
+- **✅ Stateless by design** - Minimal bundled dependencies
+- **🔄 Resumable configuration** - State management for interrupted setups
+
+## Architecture
+
+### What's Bundled vs Downloaded
+
+**Bundled in PyPI Package:**
+- `configure.py` - Main configuration logic
+- `state_manager.py` - State management for resuming
+- `download_templates.py` - Template downloader
+- `defaults.yaml` - Default values and presets
+
+**Downloaded from GitHub (on-demand):**
+- `.env.template` - Environment configuration template
+- `nginx.conf.template` - Nginx configuration template
+- `docker-compose.yml` - Docker services definition
+- `.template-version` - Template version information
+- Other deployment files
+
+These templates are located in `docker/templates/` in the avatar-deployment repository.
+
+This design means you can install and run the tool without cloning the repository!
+
+## Quick Start
+
+### Option 1: Using uvx (Recommended - After PyPI Publication)
+
+```bash
+uvx octopize-avatar-deploy --output-dir /app/avatar
+```
+
+### Option 2: Using pip
+
+```bash
+pip install octopize-avatar-deploy
+octopize-avatar-deploy --output-dir /app/avatar
+```
+
+### Option 3: From Source with uv
+
+```bash
+# Sparse clone (only deployment-tool directory)
+git clone --depth 1 --filter=blob:none --sparse https://github.com/octopize/avatar-deployment
+cd avatar-deployment
+git sparse-checkout set deployment-tool
+
+# Run with uv
+cd deployment-tool
+uv run configure.py --output-dir /app/avatar
+```
+
+## Deployment Presets
+
+Choose a preset to quickly configure for your environment:
+
+### `default` - Production Configuration
+- Console logging: **disabled** (use structured logs)
+- Sentry monitoring: **enabled**
+- Telemetry: **enabled**
+- Best for: Production deployments with monitoring
+
+### `dev-mode` - Development Configuration  
+- Console logging: **enabled** (see logs in terminal)
+- Sentry monitoring: **disabled**
+- Telemetry: **disabled**
+- Best for: Local development and testing
+
+### `airgapped` - Air-Gapped Deployment
+- Console logging: **disabled**
+- Sentry monitoring: **disabled** (no external connections)
+- Telemetry: **disabled** (no external connections)
+- Best for: Secure, isolated environments
+
+### `custom` - Manual Configuration
+- Configure all options interactively
+- Best for: Specific requirements
+
+## Usage
+
+### Interactive Mode with Preset
+
+```bash
+octopize-avatar-deploy --output-dir /app/avatar --preset dev-mode
+```
+
+The tool will:
+1. Download latest templates from GitHub
+2. Apply preset configuration
+3. Prompt for required values (PUBLIC_URL, ENV_NAME)
+4. Generate configuration files
+
+### Non-Interactive Mode
+
+```bash
+# Create config file
+cat > my-config.yaml << EOF
+PUBLIC_URL: avatar.mycompany.com
+ENV_NAME: mycompany-prod
+AVATAR_API_VERSION: 2.20.1
+AVATAR_WEB_VERSION: 0.40.0
+MAIL_PROVIDER: smtp
+SMTP_HOST: mail.mycompany.com
+EOF
+
+# Run with config
+octopize-avatar-deploy \
+  --config my-config.yaml \
+  --preset default \
+  --non-interactive \
+  --output-dir /app/avatar
+```
+
+### Advanced Options
+
+```bash
+octopize-avatar-deploy \
+  --output-dir /app/avatar \
+  --preset dev-mode \
+  --download-branch main \          # Git branch to download from
+  --skip-download \                 # Use cached templates
+  --save-config \                   # Save config to deployment-config.yaml
+  --verbose                         # Show detailed progress
+```
+
+## Command Line Options
+
+```
+--output-dir DIR           Output directory (default: current directory)
+--preset NAME              Use preset: default, dev-mode, airgapped
+--config FILE              YAML configuration file
+--non-interactive          Non-interactive mode (use config/defaults)
+--auth-type TYPE           Authentication: email or username (default: email)
+--save-config              Save config to deployment-config.yaml
+--download-branch BRANCH   Git branch for templates (default: main)
+--skip-download            Use cached templates
+--verbose                  Detailed output
+```
+
+## What Gets Generated
+
+After running the tool, you'll have:
+
+```
+/app/avatar/
+├── .env                      # Environment configuration
+├── nginx.conf                # Nginx reverse proxy config
+├── .secrets/                 # Generated secrets (gitignored)
+│   ├── db_password
+│   ├── authentik_secret_key
+│   ├── avatar_api_encryption_key
+│   └── ...
+├── docker-compose.yml        # Downloaded from GitHub
+└── .avatar-templates/        # Cached templates (auto-downloaded)
+    ├── .env.template
+    ├── nginx.conf.template
+    ├── docker-compose.yml
+    └── .template-version
+```
+
+## Configuration Presets in Detail
+
+Presets are defined in `defaults.yaml`:
+
+```yaml
+presets:
+  default:
+    description: "Production-ready with telemetry and monitoring"
+    application:
+      use_console_logging: "false"
+      sentry_enabled: "true"
+    telemetry:
+      enabled: true
+  
+  dev-mode:
+    description: "Development with console logging"
+    application:
+      use_console_logging: "true"
+      sentry_enabled: "false"
+    telemetry:
+      enabled: false
+  
+  airgapped:
+    description: "No external monitoring/telemetry"
+    application:
+      use_console_logging: "false"
+      sentry_enabled: "false"
+    telemetry:
+      enabled: false
+```
+
+You can override preset values during interactive configuration.
+
+## Template Download Mechanism
+
+Templates are downloaded from GitHub on first run:
+
+1. **Check cache** - `.avatar-templates/` directory
+2. **Download if needed** - From `github.com/octopize/avatar-deployment`
+3. **Use cached** - On subsequent runs (unless `--skip-download` is used)
+
+This ensures:
+- ✅ Always get latest templates (from specified branch)
+- ✅ Offline support (once cached)
+- ✅ No repository cloning required
+- ✅ Minimal package size
+
+## State Management
+
+The tool saves progress to `.deployment-state.yaml` allowing you to:
+
+- **Resume interrupted configurations**
+- **Track which steps completed**
+- **Avoid re-entering values**
+
+Steps:
+1. Collect required config
+2. Collect optional config
+3. Generate .env file
+4. Generate nginx.conf
+5. Generate secrets
+6. Prompt for user secrets (optional)
+7. Finalize
+
+```bash
+# If interrupted, just run again:
+octopize-avatar-deploy --output-dir /app/avatar
+
+# Tool will ask: "Continue from where you left off? [Y/n]"
+```
+
+## Troubleshooting
+
+### Templates not downloading
+
+```bash
+# Force re-download
+rm -rf .avatar-templates/
+octopize-avatar-deploy --output-dir /app/avatar --verbose
+```
+
+### Use specific Git branch
+
+```bash
+# Download from development branch
+octopize-avatar-deploy \
+  --output-dir /app/avatar \
+  --download-branch develop \
+  --verbose
+```
+
+### Offline mode
+
+```bash
+# Download templates once
+octopize-avatar-deploy --output-dir /app/avatar
+
+# Then use cached versions
+octopize-avatar-deploy --output-dir /app/avatar --skip-download
+```
+
+## Development
+
+### Project Structure
+
+```
+deployment-tool/
+├── configure.py           # Main script (bundled)
+├── state_manager.py       # State management (bundled)
+├── download_templates.py  # Template downloader (bundled)
+├── defaults.yaml          # Defaults and presets (bundled)
+├── tests/                 # Test suite
+├── README.md             
+└── pyproject.toml         # Package configuration
+```
+
+### Running Tests
+
+```bash
+cd deployment-tool
+pytest tests/
+```
+
+### Building Package
+
+```bash
+pip install build
+python -m build
+```
+
+## Related Documentation
+
+- [Deployment Guide](../deploying-on-single-instance.md)
+- [Docker Compose Configuration](../docker-compose.yml)
+- [Migration Guide](../MIGRATION_GUIDE.md)
+
+## Support
+
+For issues and questions:
+- Email: help@octopize.io
+- Documentation: https://docs.octopize.io
+- Repository: https://github.com/octopize/avatar-deployment
+
+## License
+
+Apache License v2.0

octopize_deploy_tool-0.1.0.dist-info/RECORD

@@ -0,0 +1,24 @@
+octopize_avatar_deploy/__init__.py,sha256=5RK4GI9PpEGMfABm3nZ2rEDyohQ0W_Hvn_cHQBBnAsw,651
+octopize_avatar_deploy/cli_test_harness.py,sha256=wIMKQ3VPuJDg6LVQcJVQA8WYbKOEwNwUPBD2swl5WkU,6703
+octopize_avatar_deploy/configure.py,sha256=BTyX0gzp-L3XpCR81VsCS5oubv6m57ltwqf7pUFVyks,24657
+octopize_avatar_deploy/defaults.yaml,sha256=-64srbym-Ex_kPCFq6DkZet8icBCkjadOrycEDAQUas,1649
+octopize_avatar_deploy/download_templates.py,sha256=x5ylpv1TfgbHga2AM1qZpJYrT8PxNlL2bLMj9tCsxJA,7152
+octopize_avatar_deploy/input_gatherer.py,sha256=HztvV1_nK2ZWjtZWVoQcwQNjAtJbPJT0dDQ5l_GpSWU,11287
+octopize_avatar_deploy/printer.py,sha256=3MdaL_eXk283z7BmZM94buvYeGfEvE9hAgaBgq0MoNs,6659
+octopize_avatar_deploy/state_manager.py,sha256=dEZF8pSifHdlyF8_YNQLzXPpFFSx5fDk4hhUcKJHuxA,4893
+octopize_avatar_deploy/version_compat.py,sha256=0TlsBr7zWUD9TsTuNpLkKmshrbWpyPb1pL1Z0MKtqlc,10559
+octopize_avatar_deploy/steps/__init__.py,sha256=bITxXeDG9bvAyJ4EGUESb_uX0UTLHou98Jd8TjBrO_o,626
+octopize_avatar_deploy/steps/authentik.py,sha256=6iSJUb18GRmz0SRYR0VzZGqPmhFRV1YZb1M9kS5XUUk,1460
+octopize_avatar_deploy/steps/authentik_blueprint.py,sha256=fWM7F9V2gCv7Lq9vRE4YKdOfD4Bw7PTn8Iakc8FkMpw,2786
+octopize_avatar_deploy/steps/base.py,sha256=91Ph8bGJRFa2ceKrpXlN3IOsFEX2F7hR3p6ttnR3tn0,6086
+octopize_avatar_deploy/steps/database.py,sha256=9-RKxz0h2HdTSJyPdoW3iQ6veHVLH8aSfKxiAGUsqU4,1182
+octopize_avatar_deploy/steps/email.py,sha256=9yz9qx7vBSt8Dfg-7CZ3yM2kfIoWimyyUyiGmAUP7LQ,3139
+octopize_avatar_deploy/steps/logging.py,sha256=ks10nx0Mf0ZX9lygdIG4zoWFmAupJ528DbDRGM-PQnU,856
+octopize_avatar_deploy/steps/required.py,sha256=cKAZsgmtNJ7xQ9txza3TaJ1e562iTJpg5MsjK7US9Kk,3103
+octopize_avatar_deploy/steps/storage.py,sha256=4-GVz8cMFY_fP4m1XR0yakGXfqpAGT3ZCY-lGB2uBG4,972
+octopize_avatar_deploy/steps/telemetry.py,sha256=Xo5sNDROBJGeZyLzum6aYCCYovebbNQvxeQVmILp54A,1878
+octopize_avatar_deploy/steps/user.py,sha256=3FSeEVjTHFieLGN2PqUwKzwIqe4vcx5eTw651Vg66ug,2825
+octopize_deploy_tool-0.1.0.dist-info/METADATA,sha256=C3w4-GaxFR59B7VGxnaTcLsnfLA_jR57fc89Yq4GVK0,9502
+octopize_deploy_tool-0.1.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+octopize_deploy_tool-0.1.0.dist-info/entry_points.txt,sha256=owTMr4VgBceyp-KPS3f4CEsiKkVQJAx84PRpjS8G5cw,81
+octopize_deploy_tool-0.1.0.dist-info/RECORD,,