py-docker-admin 0.6.0__tar.gz → 0.6.2__tar.gz

{py_docker_admin-0.6.0 → py_docker_admin-0.6.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: py-docker-admin
-Version: 0.6.0
+Version: 0.6.2
 Summary: A Python package for automating Docker and Portainer installation
 Project-URL: Repository, https://gitlab.com/grenzfall/py-docker-admin
 Project-URL: Issues, https://gitlab.com/grenzfall/py-docker-admin/-/issues
@@ -134,6 +134,80 @@ portainer:
 
 The `base_url` must start with a forward slash (e.g., `/portainer`, `/docker-admin`). When configured, Portainer container will be started with the `--base-url` parameter, ensuring proper path handling behind reverse proxies.
 
+## Persistent Folder Configuration
+
+The `persistent_folder` feature allows you to automatically set up and manage persistent storage for Docker containers. This is particularly useful for databases, application data, or any service that requires data persistence across container restarts and updates.
+
+### How It Works
+
+1. **Creates host directory** - Ensures the specified host directory exists (creates it if it doesn't)
+2. **Copies initial content** - Optionally copies files or directories to the host directory before deployment
+3. **Mounts to container** - The directory is mounted as a volume in the Docker container
+
+### Configuration
+
+Add `persistent_folder` to your stack configuration in `config.yaml`:
+
+```yaml
+stacks:
+  - name: myapp
+    compose_file: ./docker-compose.yml
+    env_file: ./docker-compose.env
+    persistent_folder:
+      mount_name: app_data          # Must match volume name in docker-compose.yml
+      host_directory: /var/app_data  # Absolute path on host system
+      contents: ./initial_data      # Optional: file/dir to copy to host_directory
+```
+
+### Docker Compose Integration
+
+The `mount_name` must match a volume name defined in your `docker-compose.yml`:
+
+```yaml
+version: '3.8'
+
+services:
+  myapp:
+    image: myapp:latest
+    volumes:
+      - app_data:/app/data  # This matches the mount_name in config
+
+volumes:
+  app_data:  # Volume name that matches mount_name
+    driver: local
+```
+
+### Configuration Options
+
+- **`mount_name`** (required): Name of the volume in your docker-compose.yml file
+- **`host_directory`** (required): Absolute path on the host system where data will be stored
+- **`contents`** (optional): Path to files or directories to copy to the host_directory before deployment
+
+### Example Use Cases
+
+**Database persistence:**
+```yaml
+stacks:
+  - name: postgres-db
+    compose_file: ./postgres-compose.yml
+    persistent_folder:
+      mount_name: pg_data
+      host_directory: /var/persistent/postgres
+      contents: ./initial_db_setup
+```
+
+**Application data:**
+```yaml
+stacks:
+  - name: web-app
+    compose_file: ./webapp-compose.yml
+    persistent_folder:
+      mount_name: app_storage
+      host_directory: /var/www/app_data
+```
+
+This ensures your container data persists even when containers are recreated or updated, providing reliable data storage across deployments.
+
 ## Requirements
 
 - Python 3.12+
@@ -199,4 +273,4 @@ Contributions are welcome! Please open an issue or submit a merge request on our
 
 ## Support
 
-For issues and questions, please use the [GitLab issue tracker](https://gitlab.com/grenzfall/py-docker-admin/-/issues).
+For issues and questions, please use the [GitLab issue tracker](https://gitlab.com/grenzfall/py-docker-admin/-/issues).

{py_docker_admin-0.6.0 → py_docker_admin-0.6.2}/README.md

@@ -101,6 +101,80 @@ portainer:
 
 The `base_url` must start with a forward slash (e.g., `/portainer`, `/docker-admin`). When configured, Portainer container will be started with the `--base-url` parameter, ensuring proper path handling behind reverse proxies.
 
+## Persistent Folder Configuration
+
+The `persistent_folder` feature allows you to automatically set up and manage persistent storage for Docker containers. This is particularly useful for databases, application data, or any service that requires data persistence across container restarts and updates.
+
+### How It Works
+
+1. **Creates host directory** - Ensures the specified host directory exists (creates it if it doesn't)
+2. **Copies initial content** - Optionally copies files or directories to the host directory before deployment
+3. **Mounts to container** - The directory is mounted as a volume in the Docker container
+
+### Configuration
+
+Add `persistent_folder` to your stack configuration in `config.yaml`:
+
+```yaml
+stacks:
+  - name: myapp
+    compose_file: ./docker-compose.yml
+    env_file: ./docker-compose.env
+    persistent_folder:
+      mount_name: app_data          # Must match volume name in docker-compose.yml
+      host_directory: /var/app_data  # Absolute path on host system
+      contents: ./initial_data      # Optional: file/dir to copy to host_directory
+```
+
+### Docker Compose Integration
+
+The `mount_name` must match a volume name defined in your `docker-compose.yml`:
+
+```yaml
+version: '3.8'
+
+services:
+  myapp:
+    image: myapp:latest
+    volumes:
+      - app_data:/app/data  # This matches the mount_name in config
+
+volumes:
+  app_data:  # Volume name that matches mount_name
+    driver: local
+```
+
+### Configuration Options
+
+- **`mount_name`** (required): Name of the volume in your docker-compose.yml file
+- **`host_directory`** (required): Absolute path on the host system where data will be stored
+- **`contents`** (optional): Path to files or directories to copy to the host_directory before deployment
+
+### Example Use Cases
+
+**Database persistence:**
+```yaml
+stacks:
+  - name: postgres-db
+    compose_file: ./postgres-compose.yml
+    persistent_folder:
+      mount_name: pg_data
+      host_directory: /var/persistent/postgres
+      contents: ./initial_db_setup
+```
+
+**Application data:**
+```yaml
+stacks:
+  - name: web-app
+    compose_file: ./webapp-compose.yml
+    persistent_folder:
+      mount_name: app_storage
+      host_directory: /var/www/app_data
+```
+
+This ensures your container data persists even when containers are recreated or updated, providing reliable data storage across deployments.
+
 ## Requirements
 
 - Python 3.12+
@@ -166,4 +240,4 @@ Contributions are welcome! Please open an issue or submit a merge request on our
 
 ## Support
 
-For issues and questions, please use the [GitLab issue tracker](https://gitlab.com/grenzfall/py-docker-admin/-/issues).
+For issues and questions, please use the [GitLab issue tracker](https://gitlab.com/grenzfall/py-docker-admin/-/issues).

{py_docker_admin-0.6.0 → py_docker_admin-0.6.2}/py_docker_admin/__init__.py

@@ -33,7 +33,7 @@ from .models import (
     StackConfig,
 )
 
-__version__ = "0.6.0"
+__version__ = "0.6.2"
 __all__ = [
     "app",
     "MainConfig",

{py_docker_admin-0.6.0 → py_docker_admin-0.6.2}/py_docker_admin/models.py

@@ -16,6 +16,7 @@
 
 """Pydantic models for py-docker-admin configuration."""
 
+import os
 from typing import Literal
 
 from pydantic import BaseModel, Field, field_validator
@@ -94,6 +95,42 @@ class PortainerConfig(BaseModel):
         return v
 
 
+class PersistentFolderConfig(BaseModel):
+    """Configuration for persistent folder mounting and content copying."""
+
+    mount_name: str = Field(
+        description="Name of the mount in docker-compose (must match volume name in compose file)"
+    )
+    host_directory: str = Field(
+        description="Host directory to mount (will be created if it doesn't exist)"
+    )
+    contents: str | None = Field(
+        default=None,
+        description="Path to file or directory to copy to host_directory before deployment. "
+        "If pointing to a file, copies the file. If pointing to a directory, copies the directory contents.",
+    )
+
+    @field_validator("mount_name")
+    def validate_mount_name(cls, v: str) -> str:
+        """Validate mount_name format."""
+        if not v:
+            raise ValueError("mount_name cannot be empty")
+        if not v.isidentifier():
+            raise ValueError(
+                "mount_name must be a valid identifier (letters, numbers, underscores)"
+            )
+        return v
+
+    @field_validator("host_directory")
+    def validate_host_directory(cls, v: str) -> str:
+        """Validate host_directory format."""
+        if not v:
+            raise ValueError("host_directory cannot be empty")
+        if not os.path.isabs(v):
+            raise ValueError("host_directory must be an absolute path")
+        return v
+
+
 class StackConfig(BaseModel):
     """Configuration for a single stack to be deployed.
 
@@ -114,6 +151,10 @@ class StackConfig(BaseModel):
         description="Path to environment file (optional, can be relative to CWD or absolute). "
         "This file takes precedence over any env_file in docker-compose.yml",
     )
+    persistent_folder: PersistentFolderConfig | None = Field(
+        default=None,
+        description="Configuration for persistent folder mounting and content copying",
+    )
     endpoint_id: int | None = Field(
         default=None, description="Portainer endpoint ID (optional)"
     )

{py_docker_admin-0.6.0 → py_docker_admin-0.6.2}/py_docker_admin/stack.py

@@ -350,6 +350,7 @@ class StackManager:
 
         for stack_config in stack_configs:
             try:
+                self._setup_persistent_folder(stack_config)
                 self.deploy_stack(stack_config)
             except StackCreationError as e:
                 self.logger.error(f"Failed to deploy stack {stack_config.name}: {e}")
@@ -363,3 +364,25 @@ class StackManager:
                 ) from e
 
         self.logger.info("All stacks deployed successfully")
+
+    def _setup_persistent_folder(self, stack_config: "StackConfig") -> None:
+        """Set up persistent folder for a stack if configured.
+
+        Args:
+            stack_config: Stack configuration to check for persistent folder
+
+        Raises:
+            StackCreationError: If persistent folder setup fails
+        """
+        from .utils import setup_persistent_folder
+
+        if stack_config.persistent_folder:
+            try:
+                self.logger.info(
+                    f"Setting up persistent folder for stack: {stack_config.name}"
+                )
+                setup_persistent_folder(stack_config.persistent_folder)
+            except Exception as e:
+                raise StackCreationError(
+                    f"Failed to set up persistent folder for stack {stack_config.name}: {e}"
+                )

{py_docker_admin-0.6.0 → py_docker_admin-0.6.2}/py_docker_admin/templates/nginx_config.j2

@@ -93,6 +93,13 @@ http {
     {% for site in sites %}
         {% if not site.server_site.startswith('/') %}
 
+        # HTTP to HTTPS redirect for {{ site.site_name }} on port {{ site.server_site }}
+        server {
+            listen {{ site.server_site }};
+            server_name {{ server_name }};
+            return 301 https://$host:$server_port$request_uri;
+        }
+
         # New server block for {{ site.site_name }} on port {{ site.server_site }}
         server {
             listen {{ site.server_site }} ssl;
@@ -116,9 +123,16 @@ http {
                 proxy_set_header X-Real-IP $remote_addr;
                 proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
                 proxy_set_header X-Forwarded-Proto $scheme;
+                proxy_set_header X-Forwarded-Port $server_port;
+                proxy_set_header X-Forwarded-Host $host;
+                proxy_set_header X-Script-Name /;
                 proxy_set_header Upgrade $http_upgrade;
                 proxy_set_header Connection "upgrade";
                 proxy_http_version 1.1;
+
+                # Rewrite redirects to use correct protocol and port
+                proxy_redirect http:// https://;
+                proxy_redirect http://$host/ https://$host:{{ site.server_site }}/;
             }
         }
         {% endif %}

{py_docker_admin-0.6.0 → py_docker_admin-0.6.2}/py_docker_admin/utils.py

@@ -16,6 +16,113 @@
 
 """Utility functions for py-docker-admin."""
 
+from .models import PersistentFolderConfig
+import os
+import shutil
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+import yaml
+
+from .exceptions import DockerAdminError
+
+
+def check_port_in_use(port: int) -> Optional[Dict[str, Any]]:
+    """Check if a port is currently in use.
+
+    Args:
+        port: Port number to check
+
+    Returns:
+        Dictionary with process information if port is in use, None otherwise
+    """
+    import subprocess
+    import re
+
+    try:
+        # Check TCP ports
+        result = subprocess.run(
+            ["lsof", "-i", f":{port}"],
+            capture_output=True,
+            text=True,
+            check=True,
+        )
+        lines = result.stdout.strip().split("\n")
+        if len(lines) > 1:
+            # Parse the process information from the lsof output
+            header = lines[0]
+            process_info = lines[1]
+
+            # Extract relevant fields
+            pid_match = re.search(r"\s(\d+)\s", process_info)
+            command_match = re.search(r"(\S+)\s+\d+", process_info)
+
+            if pid_match and command_match:
+                return {
+                    "port": port,
+                    "pid": pid_match.group(1),
+                    "process": command_match.group(1),
+                }
+
+    except subprocess.CalledProcessError:
+        # Port not in use
+        pass
+    except Exception as e:
+        # Log any unexpected errors
+        logger = logging.getLogger(__name__)
+        logger.warning(f"Error checking port {port}: {e}")
+
+    return None
+
+
+def extract_ports_from_compose(compose_path: str) -> List[int]:
+    """Extract port numbers from a docker-compose file.
+
+    Args:
+        compose_path: Path to docker-compose file
+
+    Returns:
+        List of port numbers found in the compose file
+    """
+    try:
+        with open(compose_path) as f:
+            compose_content = f.read()
+
+        # Parse YAML content
+        compose_data = yaml.safe_load(compose_content) or {}
+
+        ports = []
+        services = compose_data.get("services", {})
+        for service_name, service_config in services.items():
+            # Check port mappings in service configuration
+            ports_config = service_config.get("ports", [])
+            for port_mapping in ports_config:
+                if isinstance(port_mapping, str):
+                    # Port mapping format: "HOST_PORT:CONTAINER_PORT"
+                    port_parts = port_mapping.split(":")
+                    if len(port_parts) > 0:
+                        host_port = port_parts[0]
+                        # Handle port ranges and individual ports
+                        if "-" in host_port:
+                            port_range = host_port.split("-")
+                            if len(port_range) == 2:
+                                start_port = int(port_range[0])
+                                end_port = int(port_range[1])
+                                ports.extend(range(start_port, end_port + 1))
+                        else:
+                            try:
+                                ports.append(int(host_port))
+                            except ValueError:
+                                pass
+
+        return ports
+
+    except Exception as e:
+        logger = logging.getLogger(__name__)
+        logger.debug(f"Error extracting ports from compose file: {e}")
+        return []
+
+
 import logging
 import shlex
 import subprocess
@@ -221,6 +328,132 @@ def check_port_in_use(port: int) -> dict[str, str] | None:
         return None
 
 
+def create_directory_if_not_exists(path: str) -> None:
+    """Create a directory if it doesn't exist.
+
+    Args:
+        path: Path to directory to create
+
+    Raises:
+        DockerAdminError: If directory cannot be created
+    """
+    logger = logging.getLogger(__name__)
+
+    try:
+        Path(path).mkdir(parents=True, exist_ok=True)
+        logger.debug(f"Directory created or already exists: {path}")
+    except Exception as e:
+        raise DockerAdminError(f"Failed to create directory {path}: {e}")
+
+
+def copy_file_or_directory(src: str, dest: str) -> None:
+    """Copy a file or directory to a destination.
+
+    Args:
+        src: Source file or directory path
+        dest: Destination path
+
+    Raises:
+        DockerAdminError: If copy operation fails
+    """
+    logger = logging.getLogger(__name__)
+
+    try:
+        if os.path.isfile(src):
+            # Copy file
+            shutil.copy2(src, dest)
+            logger.debug(f"Copied file from {src} to {dest}")
+        elif os.path.isdir(src):
+            # Copy directory contents
+            if os.path.exists(dest):
+                if not os.path.isdir(dest):
+                    raise DockerAdminError(
+                        f"Destination {dest} exists but is not a directory"
+                    )
+            else:
+                os.makedirs(dest, exist_ok=True)
+
+            for item in os.listdir(src):
+                s = os.path.join(src, item)
+                d = os.path.join(dest, item)
+                if os.path.isdir(s):
+                    shutil.copytree(s, d, dirs_exist_ok=True)
+                else:
+                    shutil.copy2(s, d)
+
+            logger.debug(f"Copied directory contents from {src} to {dest}")
+        else:
+            raise DockerAdminError(
+                f"Source {src} does not exist or is not a file/directory"
+            )
+    except Exception as e:
+        raise DockerAdminError(f"Failed to copy {src} to {dest}: {e}")
+
+
+def validate_persistent_folder_config(config: PersistentFolderConfig) -> None:
+    """Validate persistent folder configuration.
+
+    Args:
+        config: PersistentFolderConfig to validate
+
+    Raises:
+        DockerAdminError: If configuration is invalid
+    """
+    logger = logging.getLogger(__name__)
+
+    # Validate mount_name exists in docker-compose
+    if config.mount_name:
+        try:
+            compose_path = (
+                config.compose_file if hasattr(config, "compose_file") else None
+            )
+            if compose_path:
+                with open(compose_path) as f:
+                    compose_content = f.read()
+                if config.mount_name not in compose_content:
+                    raise DockerAdminError(
+                        f"Mount name '{config.mount_name}' not found in docker-compose file"
+                    )
+        except Exception as e:
+            logger.warning(f"Could not validate mount name in compose file: {e}")
+
+    # Validate contents path if specified
+    if config.contents:
+        if not os.path.exists(config.contents):
+            raise DockerAdminError(f"Contents path '{config.contents}' does not exist")
+        if os.path.isdir(config.contents) and not os.listdir(config.contents):
+            logger.warning(f"Contents directory '{config.contents}' is empty")
+
+
+def setup_persistent_folder(config: PersistentFolderConfig) -> None:
+    """Set up persistent folder according to configuration.
+
+    Args:
+        config: PersistentFolderConfig to apply
+
+    Raises:
+        DockerAdminError: If setup fails
+    """
+    logger = logging.getLogger(__name__)
+
+    # Create host directory
+    create_directory_if_not_exists(config.host_directory)
+
+    # Copy contents if specified
+    if config.contents:
+        if os.path.isfile(config.contents):
+            # Copy file to host directory
+            dest_file = os.path.join(
+                config.host_directory, os.path.basename(config.contents)
+            )
+            copy_file_or_directory(config.contents, dest_file)
+        elif os.path.isdir(config.contents):
+            # Copy directory contents to host directory
+            copy_file_or_directory(config.contents, config.host_directory)
+
+    logger.info(f"Persistent folder setup complete: {config.host_directory}")
+
+
 def extract_ports_from_compose(compose_file_path: str) -> set[int]:
     """Extract all host ports from a docker-compose.yml file.
 

{py_docker_admin-0.6.0 → py_docker_admin-0.6.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "py-docker-admin"
-version = "0.6.0"
+version = "0.6.2"
 description = "A Python package for automating Docker and Portainer installation"
 readme = "README.md"
 requires-python = ">=3.12"

{py_docker_admin-0.6.0 → py_docker_admin-0.6.2}/templates/nginx_config.j2

@@ -93,6 +93,13 @@ http {
     {% for site in sites %}
         {% if not site.server_site.startswith('/') %}
 
+        # HTTP to HTTPS redirect for {{ site.site_name }} on port {{ site.server_site }}
+        server {
+            listen {{ site.server_site }};
+            server_name {{ server_name }};
+            return 301 https://$host:$server_port$request_uri;
+        }
+
         # New server block for {{ site.site_name }} on port {{ site.server_site }}
         server {
             listen {{ site.server_site }} ssl;
@@ -116,9 +123,16 @@ http {
                 proxy_set_header X-Real-IP $remote_addr;
                 proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
                 proxy_set_header X-Forwarded-Proto $scheme;
+                proxy_set_header X-Forwarded-Port $server_port;
+                proxy_set_header X-Forwarded-Host $host;
+                proxy_set_header X-Script-Name /;
                 proxy_set_header Upgrade $http_upgrade;
                 proxy_set_header Connection "upgrade";
                 proxy_http_version 1.1;
+
+                # Rewrite redirects to use correct protocol and port
+                proxy_redirect http:// https://;
+                proxy_redirect http://$host/ https://$host:{{ site.server_site }}/;
             }
         }
         {% endif %}