base-deployment-controller 0.1.0__tar.gz

base_deployment_controller-0.1.0/PKG-INFO

@@ -0,0 +1,184 @@
+Metadata-Version: 2.4
+Name: base-deployment-controller
+Version: 0.1.0
+Summary: REST API to control the basic operations of a deployment
+Author: Tknika
+License: Creative Commons Atribución-NoComercial (CC BY-NC)
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: fastapi>=0.128.0
+Requires-Dist: uvicorn[standard]>=0.40.0
+Requires-Dist: python-dotenv>=1.2.1
+Requires-Dist: pyyaml>=6.0.3
+Requires-Dist: websockets>=16.0
+Requires-Dist: python-on-whales>=0.80.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.4.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
+Requires-Dist: requests>=2.31.0; extra == "dev"
+
+# Base Deployment Controller
+
+REST API para la gestión básica de un deployment.
+
+## Características
+
+- **Gestión del deployment**: Inicia, detiene y borrar el deploy (`compose.yaml`)
+- **Gestión de variables de entorno**: Lee configuración de `x-env-vars` en `compose.yaml` y permite actualizar valores en `.env`
+- **Control de contenedores**: Inicia, detiene y reinicia contenedores del deploy
+- **Logs en tiempo real**: WebSocket para streaming de logs de contenedores
+- **Validación de tipos**: Valida automáticamente valores según schemas (regex, rangos, enums)
+
+## Requisitos
+
+- Python 3.8+
+- Docker y Docker Compose
+
+## Instalación
+
+```bash
+# Crear entorno virtual
+python3 -m venv .venv
+source .venv/bin/activate
+
+# Instalar como librería
+pip install base-deployment-controller
+```
+
+## Uso
+
+### Iniciar el servidor (demo)
+
+```bash
+# Ejecutar la app demo desde la raíz del repo
+python3 main.py
+```
+
+El servidor estará disponible en `http://localhost:8000`
+
+### Uso como librería
+
+#### Uso básico (factory)
+
+```python
+from base_deployment_controller import create_app
+
+app = create_app(
+  compose_file="compose.yaml",
+  env_file=".env",
+)
+```
+
+#### Uso avanzado (builder + routers personalizados)
+
+```python
+from fastapi import APIRouter
+from base_deployment_controller import AppBuilder
+
+custom_router = APIRouter(prefix="/custom")
+
+builder = AppBuilder("compose.yaml", ".env")
+app = builder.register_router(custom_router).build()
+```
+
+### API Endpoints
+
+#### GET /
+Obtiene información sobre el deploy:
+
+```bash
+curl http://localhost:8000/
+```
+
+#### POST /up|down|stop
+Controla el deploy:
+
+```bash
+# Levanta todos los servicio del deploy
+curl -X POST http://localhost:8000/up
+```
+
+#### GET /envs
+Obtiene todas las variables de entorno con sus valores actuales:
+
+```bash
+curl http://localhost:8000/envs
+```
+
+#### PUT /envs
+Actualiza variables de entorno. Usa `restart_services` (por defecto `true`) para controlar si se reinician los servicios afectados.
+
+```bash
+# Actualización múltiple
+curl -X PUT http://localhost:8000/envs \
+  -H "Content-Type: application/json" \
+  -d '{"variables": {"MCC": "214", "MNC": "07"}, "restart_services": false}'
+```
+
+#### GET /containers
+Lista el estado de todos los contenedores:
+
+```bash
+curl http://localhost:8000/containers
+```
+
+#### POST /containers/{name}/start|stop|restart
+Controla un contenedor específico:
+
+```bash
+# Reiniciar el MME
+curl -X POST http://localhost:8000/containers/mme/restart
+```
+
+#### WebSocket /containers/{container_name}/logs
+Logs en tiempo real via WebSocket:
+
+```javascript
+const ws = new WebSocket('ws://localhost:8000/containers/mme/logs');
+ws.onmessage = (event) => {
+  console.log(event.data);
+};
+```
+
+#### GET /ping
+Health check del servicio:
+
+```bash
+curl http://localhost:8000/ping
+```
+
+## Documentación Interactiva
+
+FastAPI genera automáticamente documentación interactiva:
+
+- **Swagger UI**: http://localhost:8000/docs
+- **ReDoc**: http://localhost:8000/redoc
+
+## Arquitectura
+
+### Configuración de Tres Niveles
+
+1. **compose.yaml**: Define servicios y dependencias
+2. **x-env-vars**: Schema maestro con validaciones
+3. **.env**: Valores en tiempo de ejecución
+
+## Validación de Tipos
+
+Las variables se validan según el schema de `x-env-vars`:
+
+- **String con regex**: `"string:0;^\d{3}$"` - MCC debe ser 3 dígitos
+- **Integer con rango**: `"integer:0;2048"` - MAX_NUM_UE entre 0-2048
+- **Enum**: `"enum:tun,tap"` - UPF_TUNTAP_MODE solo acepta tun o tap
+
+## Seguridad
+
+- Solo permite actualizar variables existentes en el schema
+- No permite agregar nuevas variables
+- No permite eliminar variables
+- Valida todos los valores antes de escribir en `.env`
+
+## Licencia
+
+Este proyecto es parte del controlador de despliegue 5G de Tknika.

base_deployment_controller-0.1.0/README.md

@@ -0,0 +1,163 @@
+# Base Deployment Controller
+
+REST API para la gestión básica de un deployment.
+
+## Características
+
+- **Gestión del deployment**: Inicia, detiene y borrar el deploy (`compose.yaml`)
+- **Gestión de variables de entorno**: Lee configuración de `x-env-vars` en `compose.yaml` y permite actualizar valores en `.env`
+- **Control de contenedores**: Inicia, detiene y reinicia contenedores del deploy
+- **Logs en tiempo real**: WebSocket para streaming de logs de contenedores
+- **Validación de tipos**: Valida automáticamente valores según schemas (regex, rangos, enums)
+
+## Requisitos
+
+- Python 3.8+
+- Docker y Docker Compose
+
+## Instalación
+
+```bash
+# Crear entorno virtual
+python3 -m venv .venv
+source .venv/bin/activate
+
+# Instalar como librería
+pip install base-deployment-controller
+```
+
+## Uso
+
+### Iniciar el servidor (demo)
+
+```bash
+# Ejecutar la app demo desde la raíz del repo
+python3 main.py
+```
+
+El servidor estará disponible en `http://localhost:8000`
+
+### Uso como librería
+
+#### Uso básico (factory)
+
+```python
+from base_deployment_controller import create_app
+
+app = create_app(
+  compose_file="compose.yaml",
+  env_file=".env",
+)
+```
+
+#### Uso avanzado (builder + routers personalizados)
+
+```python
+from fastapi import APIRouter
+from base_deployment_controller import AppBuilder
+
+custom_router = APIRouter(prefix="/custom")
+
+builder = AppBuilder("compose.yaml", ".env")
+app = builder.register_router(custom_router).build()
+```
+
+### API Endpoints
+
+#### GET /
+Obtiene información sobre el deploy:
+
+```bash
+curl http://localhost:8000/
+```
+
+#### POST /up|down|stop
+Controla el deploy:
+
+```bash
+# Levanta todos los servicio del deploy
+curl -X POST http://localhost:8000/up
+```
+
+#### GET /envs
+Obtiene todas las variables de entorno con sus valores actuales:
+
+```bash
+curl http://localhost:8000/envs
+```
+
+#### PUT /envs
+Actualiza variables de entorno. Usa `restart_services` (por defecto `true`) para controlar si se reinician los servicios afectados.
+
+```bash
+# Actualización múltiple
+curl -X PUT http://localhost:8000/envs \
+  -H "Content-Type: application/json" \
+  -d '{"variables": {"MCC": "214", "MNC": "07"}, "restart_services": false}'
+```
+
+#### GET /containers
+Lista el estado de todos los contenedores:
+
+```bash
+curl http://localhost:8000/containers
+```
+
+#### POST /containers/{name}/start|stop|restart
+Controla un contenedor específico:
+
+```bash
+# Reiniciar el MME
+curl -X POST http://localhost:8000/containers/mme/restart
+```
+
+#### WebSocket /containers/{container_name}/logs
+Logs en tiempo real via WebSocket:
+
+```javascript
+const ws = new WebSocket('ws://localhost:8000/containers/mme/logs');
+ws.onmessage = (event) => {
+  console.log(event.data);
+};
+```
+
+#### GET /ping
+Health check del servicio:
+
+```bash
+curl http://localhost:8000/ping
+```
+
+## Documentación Interactiva
+
+FastAPI genera automáticamente documentación interactiva:
+
+- **Swagger UI**: http://localhost:8000/docs
+- **ReDoc**: http://localhost:8000/redoc
+
+## Arquitectura
+
+### Configuración de Tres Niveles
+
+1. **compose.yaml**: Define servicios y dependencias
+2. **x-env-vars**: Schema maestro con validaciones
+3. **.env**: Valores en tiempo de ejecución
+
+## Validación de Tipos
+
+Las variables se validan según el schema de `x-env-vars`:
+
+- **String con regex**: `"string:0;^\d{3}$"` - MCC debe ser 3 dígitos
+- **Integer con rango**: `"integer:0;2048"` - MAX_NUM_UE entre 0-2048
+- **Enum**: `"enum:tun,tap"` - UPF_TUNTAP_MODE solo acepta tun o tap
+
+## Seguridad
+
+- Solo permite actualizar variables existentes en el schema
+- No permite agregar nuevas variables
+- No permite eliminar variables
+- Valida todos los valores antes de escribir en `.env`
+
+## Licencia
+
+Este proyecto es parte del controlador de despliegue 5G de Tknika.

base_deployment_controller-0.1.0/pyproject.toml

@@ -0,0 +1,49 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "base-deployment-controller"
+version = "0.1.0"
+description = "REST API to control the basic operations of a deployment"
+readme = "README.md"
+requires-python = ">=3.8"
+authors = [
+  { name = "Tknika" }
+]
+license = { text = "Creative Commons Atribución-NoComercial (CC BY-NC)" }
+dependencies = [
+  "fastapi>=0.128.0",
+  "uvicorn[standard]>=0.40.0",
+  "python-dotenv>=1.2.1",
+  "pyyaml>=6.0.3",
+  "websockets>=16.0",
+  "python-on-whales>=0.80.0",
+]
+
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+]
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=7.4.0",
+  "pytest-asyncio>=0.21.0",
+  "requests>=2.31.0",
+]
+
+[tool.setuptools]
+packages = { find = { where = ["src"] } }
+include-package-data = false
+
+[tool.setuptools.exclude-package-data]
+"*" = ["data/*", "data/**", "tests/*", "tests/**", "test_*", "*.md"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+python_classes = ["Test*"]
+python_functions = ["test_*"]
+addopts = "-v --tb=short"
+asyncio_mode = "auto"

base_deployment_controller-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

base_deployment_controller-0.1.0/src/base_deployment_controller/__init__.py

@@ -0,0 +1,59 @@
+"""Base Deployment Controller package entry point."""
+from fastapi import FastAPI
+
+from .services.config import ConfigService
+from .routers.environment import EnvRoutes
+from .routers.container import ContainerRoutes
+from .routers.deployment import DeploymentRoutes
+from .builder import AppBuilder
+
+
+def create_app(
+    compose_file: str = "compose.yaml",
+    env_file: str = ".env",
+    include_routers: bool = True,
+    title: str = "Base Deployment Controller",
+    description: str = "REST API to control the basic operations of a deployment",
+    version: str = "1.0.0",
+) -> FastAPI:
+    """
+    Factory function to create a preconfigured FastAPI application.
+
+    Args:
+        compose_file: Path to compose.yaml file.
+        env_file: Path to .env file.
+        include_routers: If True, registers base routers (envs, containers, deployment).
+        title: FastAPI application title.
+        description: FastAPI application description.
+        version: Application version string.
+
+    Returns:
+        FastAPI app ready to use or extend.
+    """
+    app = FastAPI(
+        title=title,
+        description=description,
+        version=version,
+    )
+
+    if include_routers:
+        config_service = ConfigService(compose_file, env_file)
+        env_routes = EnvRoutes(config_service)
+        container_routes = ContainerRoutes(config_service)
+        deployment_routes = DeploymentRoutes(config_service)
+
+        app.include_router(env_routes.router)
+        app.include_router(container_routes.router)
+        app.include_router(deployment_routes.router)
+
+    return app
+
+
+__all__ = [
+    "ConfigService",
+    "EnvRoutes",
+    "ContainerRoutes",
+    "DeploymentRoutes",
+    "AppBuilder",
+    "create_app",
+]

base_deployment_controller-0.1.0/src/base_deployment_controller/builder.py

@@ -0,0 +1,90 @@
+"""Application builder for composing the FastAPI app and custom routers."""
+from typing import List, Tuple
+
+from fastapi import APIRouter, FastAPI
+
+from .services.config import ConfigService
+from .routers.environment import EnvRoutes
+from .routers.container import ContainerRoutes
+from .routers.deployment import DeploymentRoutes
+
+
+class AppBuilder:
+    """
+    Builder for constructing a Base Deployment Controller FastAPI application.
+
+    Allows registration of custom routers before building the final app.
+
+    Args:
+        compose_file: Path to Docker Compose file.
+        env_file: Path to environment variables file.
+        title: FastAPI application title.
+        description: FastAPI application description.
+        version: Application version string.
+    """
+
+    def __init__(
+        self,
+        compose_file: str = "compose.yaml",
+        env_file: str = ".env",
+        title: str = "Base Deployment Controller",
+        description: str = "REST API for managing base deployment",
+        version: str = "1.0.0",
+    ) -> None:
+        """
+        Initialize the builder and register default routers.
+
+        Args:
+            compose_file: Path to Docker Compose file.
+            env_file: Path to environment variables file.
+            title: FastAPI application title.
+            description: FastAPI application description.
+            version: Application version string.
+        """
+        self.compose_file = compose_file
+        self.env_file = env_file
+        self.title = title
+        self.description = description
+        self.version = version
+        self._custom_routers: List[Tuple[APIRouter, str]] = []
+
+    def register_router(self, router: APIRouter, prefix: str = "") -> "AppBuilder":
+        """
+        Register a custom router to include when building the app.
+
+        Args:
+            router: Router instance to register.
+            prefix: Optional path prefix for the router.
+
+        Returns:
+            AppBuilder instance for fluent chaining.
+        """
+        self._custom_routers.append((router, prefix))
+        return self
+
+    def build(self) -> FastAPI:
+        """
+        Build and return a FastAPI app with base and custom routers.
+
+        Returns:
+            FastAPI application instance.
+        """
+        app = FastAPI(
+            title=self.title,
+            description=self.description,
+            version=self.version,
+        )
+
+        config_service = ConfigService(self.compose_file, self.env_file)
+        env_routes = EnvRoutes(config_service)
+        container_routes = ContainerRoutes(config_service)
+        deployment_routes = DeploymentRoutes(config_service)
+
+        app.include_router(env_routes.router)
+        app.include_router(container_routes.router)
+        app.include_router(deployment_routes.router)
+
+        for router, prefix in self._custom_routers:
+            app.include_router(router, prefix=prefix)
+
+        return app

base_deployment_controller-0.1.0/src/base_deployment_controller/models/__init__.py

@@ -0,0 +1,33 @@
+"""Pydantic models for the Base Deployment Controller."""
+
+from .environment import (
+    EnvVariable,
+    EnvVariablesResponse,
+    BulkEnvUpdateRequest,
+    EnvUpdateResponse,
+)
+from .container import ContainerInfo, ContainersInfoResponse, ContainerControlResponse
+from .deployment import (
+    DeploymentStatus,
+    DeploymentMetadata,
+    DeploymentInfoResponse,
+    DeploymentPingResponse,
+    DeploymentActionResponse,
+)
+from .compose import ComposeActionResponse
+
+__all__ = [
+    "EnvVariable",
+    "EnvVariablesResponse",
+    "BulkEnvUpdateRequest",
+    "EnvUpdateResponse",
+    "ContainerInfo",
+    "ContainersInfoResponse",
+    "ContainerControlResponse",
+    "DeploymentStatus",
+    "DeploymentMetadata",
+    "DeploymentInfoResponse",
+    "DeploymentPingResponse",
+    "DeploymentActionResponse",
+    "ComposeActionResponse",
+]

base_deployment_controller-0.1.0/src/base_deployment_controller/models/compose.py

@@ -0,0 +1,11 @@
+"""Docker Compose operation models."""
+from typing import List
+
+from pydantic import BaseModel, Field
+
+
+class ComposeActionResponse(BaseModel):
+    """Response after executing a docker-compose action (up/stop/restart)."""
+
+    success: bool = Field(..., description="Operation success status")
+    message: str = Field(..., description="Operation result message")

base_deployment_controller-0.1.0/src/base_deployment_controller/models/container.py

@@ -0,0 +1,31 @@
+"""Container models."""
+from datetime import datetime
+from typing import Optional
+
+from pydantic import BaseModel, Field, field_validator
+
+
+class ContainerInfo(BaseModel):
+    """Docker container information and service metadata."""
+
+    name: str = Field(..., description="Container name")
+    image: str = Field(..., description="Container image")
+    status: str = Field(..., description="Container status")
+    started_at: Optional[datetime] = Field(None, description="Container start time")
+    ports: list[str] = Field(..., description="Exposed ports")
+    depends_on: list[str] = Field(..., description="Service dependencies")
+
+
+class ContainersInfoResponse(BaseModel):
+    """Response with list of containers and their current status."""
+
+    containers: list[ContainerInfo] = Field(..., description="List of containers")
+
+
+class ContainerControlResponse(BaseModel):
+    """Response after executing a control action on a container."""
+
+    success: bool = Field(..., description="Action success status")
+    container: str = Field(..., description="Container name")
+    action: str = Field(..., description="Action performed")
+    message: str = Field(..., description="Status message")

base_deployment_controller-0.1.0/src/base_deployment_controller/models/deployment.py

@@ -0,0 +1,57 @@
+"""Deployment models."""
+from enum import Enum
+
+from .environment import EnvVariable
+from pydantic import BaseModel, Field
+
+
+class DeploymentStatus(str, Enum):
+    """
+    Deployment status enumeration.
+
+    Values:
+        running: All services running.
+        partially_running: Some services running.
+        stopped: No services running.
+        unknown: Status cannot be determined.
+    """
+
+    RUNNING = "running"
+    PARTIALLY_RUNNING = "partially_running"
+    STOPPED = "stopped"
+    UNKNOWN = "unknown"
+
+
+class DeploymentMetadata(BaseModel):
+    """Deployment metadata from x-metadata section in compose.yaml."""
+
+    id: str = Field(..., description="Deployment unique identifier")
+    name: str = Field(..., description="Deployment name")
+    description: str = Field(..., description="Deployment description")
+    version: str = Field(..., description="Deployment version")
+    author: str = Field(..., description="Deployment author")
+    changelog: str = Field(..., description="Deployment changelog")
+    documentation_url: str = Field(..., description="Documentation URL")
+
+
+class DeploymentInfoResponse(BaseModel):
+    """Response with basic deployment information."""
+
+    metadata: DeploymentMetadata = Field(..., description="Deployment metadata")
+    status: DeploymentStatus
+    env_vars: dict[str, EnvVariable] = Field(..., description="List of environment variables")
+
+
+class DeploymentPingResponse(BaseModel):
+    """Response for deployment ping endpoint."""
+
+    success: bool = Field(..., description="Ping success status")
+    message: str = Field(..., description="Ping message")
+
+
+class DeploymentActionResponse(BaseModel):
+    """Response after performing a deployment action."""
+
+    success: bool = Field(..., description="Action success status")
+    action: str = Field(..., description="Action performed")
+    message: str = Field(..., description="Status message")