Metadata-Version: 2.4
Name: dooservice-cli
Version: 0.11.3
Summary: Professional CLI tool for managing Odoo instances with declarative configuration, automated backups, snapshots, and GitHub integration.
Author-email: DooService Development Team <principal@apiservicesac.com>, API SERVICE SAC <principal@apiservicesac.com>
Maintainer-email: DooService Development Team <principal@apiservicesac.com>
License: MIT License
        
        Copyright (c) 2023 Your Name
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://apiservicesac.com
Project-URL: Documentation, https://github.com/apiservicesac/dooservice-cli-py#readme
Project-URL: Repository, https://github.com/apiservicesac/dooservice-cli-py
Project-URL: Issues, https://github.com/apiservicesac/dooservice-cli-py/issues
Project-URL: Changelog, https://github.com/apiservicesac/dooservice-cli-py/releases
Keywords: odoo,docker,cli,management,deployment,backup,snapshot,devops,automation,orchestration,containerization,enterprise,erp,github-integration,webhook,configuration-management
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: Intended Audience :: Information Technology
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Topic :: Software Development :: Build Tools
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Systems Administration
Classifier: Topic :: System :: Installation/Setup
Classifier: Topic :: System :: Software Distribution
Classifier: Topic :: Database
Classifier: Topic :: Internet :: WWW/HTTP :: WSGI :: Application
Classifier: Environment :: Console
Classifier: Framework :: Odoo
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click>=8.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: docker>=7.0.0
Requires-Dist: GitPython>=3.1
Requires-Dist: dacite>=1.6.0
Requires-Dist: toml>=0.10.2
Requires-Dist: requests>=2.25.0
Requires-Dist: cryptography>=3.0.0
Requires-Dist: psutil>=7.0.0
Requires-Dist: ruff>=0.11.13
Requires-Dist: httpx>=0.24.0
Requires-Dist: typer>=0.9.0
Requires-Dist: rich>=13.0.0
Requires-Dist: questionary>=2.1.1
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: flake8>=4.0; extra == "dev"
Requires-Dist: pytest-mock>=3.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: coverage>=7.0; extra == "dev"
Requires-Dist: ruff==0.11.13; extra == "dev"
Requires-Dist: build>=0.10.0; extra == "dev"
Requires-Dist: twine>=4.0.0; extra == "dev"
Dynamic: license-file

# DooService CLI

DooService CLI is a professional command-line tool for managing complex Odoo instances using a declarative approach. Define your entire infrastructure in a single `dooservice.yml` file and manage instances, repositories, and backups from the command line.

## ✨ Features

- **🔧 Declarative Configuration**: Define all Odoo instances and repositories in a single YAML file
- **📦 Modular Configuration**: Split large configs into multiple files using imports for better organization
- **🚀 Full Instance Lifecycle**: Create, start, stop, sync, and delete instances with simple commands
- **📁 Repository Management**: Automatically clone and update Odoo addon repositories from Git
- **🐳 Docker Integration**: Native Docker support for deploying Odoo and PostgreSQL containers
- **💾 Backup System**: Create, test, and manage instance backups with database support
- **🌐 Cloudflare Integration**: Complete Cloudflare tunnels and domain management with automated DNS
- **🔗 Tunnel Management**: Create, configure, and manage Cloudflare tunnels for secure external access
- **📋 Domain Operations**: Enable/disable domains with automatic DNS record management
- **⚡ Clean Architecture**: Built with Clean Architecture principles for maintainability and extensibility
- **🎯 Configuration-First**: No hardcoded values - all operations require explicit configuration
- **📝 Type Safety**: Strong typing throughout the application with comprehensive error handling

## 📦 Installation

### Production Installation

```bash
# Using pipx (recommended)
pipx install dooservice-cli

# Using pip
pip install dooservice-cli

# Using uv (modern Python package manager)
uv tool install dooservice-cli

# Verify installation
dooservice --help
```

### Development Installation

```bash
# Clone the repository
git clone https://github.com/apiservicesac/dooservice-cli-py.git
cd dooservice-cli-py

# Install uv (modern Python package manager)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Option 1: Install globally for development
uv tool install --editable .

# Option 2: Install dependencies only (requires uv run prefix)
uv sync --all-extras

# Verify installation
# For global install:
dooservice --help

# For local development:
uv run dooservice --help
```

## 🚀 Quick Start

1. **Initialize Configuration**
   ```bash
   # Copy example configuration
   cp dooservice.yml.example dooservice.yml

   # Edit the configuration to match your needs
   nano dooservice.yml
   ```

2. **Validate Configuration**
   ```bash
   dooservice config validate dooservice.yml
   ```

3. **Create Your First Instance**
   ```bash
   # Create instance
   dooservice instance create my-instance

   # Start instance
   dooservice instance start my-instance
   ```

4. **Access Your Instance**
   Your Odoo instance will be running at `http://localhost:8069` (or your configured port)

5. **Set Up Cloudflare (Optional)**
   ```bash
   # Initialize a Cloudflare tunnel for external access
   dooservice cloudflare tunnel init main-tunnel

   # Enable a domain to point to your instance
   dooservice cloudflare domain enable app.example.com

   # Check domain status
   dooservice cloudflare domain status app.example.com
   ```

6. **Manage Your Instance**
   ```bash
   # Check status
   dooservice instance status my-instance

   # View logs
   dooservice instance logs my-instance --follow

   # Create backup
   dooservice backup create my-instance
   ```

## 📖 Command Reference

### Configuration Management
```bash
# Load and validate configuration files
dooservice config load <file_path> [--no-validate]
dooservice config validate <file_path>
dooservice config create <file_path> [--no-validate]
dooservice config convert <input_file> [--output <file>]
```

### Instance Management
```bash
# Create and manage instances
dooservice instance create <name> [--config <file>]
dooservice instance delete <name> [--config <file>]
dooservice instance start <name> [--config <file>]
dooservice instance stop <name> [--config <file>]
dooservice instance restart <name> [--config <file>]
dooservice instance status <name> [--config <file>]
dooservice instance logs <name> [--service <service>] [--follow] [--tail <lines>]
dooservice instance exec <name> <command> [--user <user>] [--workdir <dir>]
dooservice instance sync <name> [--no-restart] [--config <file>]
```

### Repository Management
```bash
# Manage instance repositories
dooservice repository list <instance_name> [--repo <name>] [--config <file>]
dooservice repository status <instance_name> <repo_name> [--config <file>]
dooservice repository sync <instance_name> [--repo <name>] [--quiet] [--test]
```

### Backup Operations
```bash
# Create and manage backups
dooservice backup create <instance_name> [--database <name>] [--format <zip|dump>] [--output <dir>]
dooservice backup test <instance_name> [--database <name>]
dooservice backup databases <instance_name>
```

### Cloudflare Management
```bash
# Tunnel Management
dooservice cloudflare tunnel init <name> [--config <file>] [--verbose]
dooservice cloudflare tunnel list [--config <file>] [--verbose]
dooservice cloudflare tunnel delete <name> [--config <file>] [--verbose]

# Domain Management
dooservice cloudflare domain enable <name> [--config <file>] [--verbose]
dooservice cloudflare domain disable <name> [--config <file>] [--verbose]
dooservice cloudflare domain sync <name> [--config <file>] [--verbose]
dooservice cloudflare domain list [--config <file>] [--verbose]
dooservice cloudflare domain status <name> [--config <file>] [--verbose]
dooservice cloudflare domain test <name> [--config <file>] [--verbose]
dooservice cloudflare domain logs <name> [--tail <lines>] [--follow] [--config <file>] [--verbose]
```

## 🎯 Usage Examples

### 📄 Complete Configuration Example

Here's a complete `dooservice.yml` configuration file based on real-world usage:

```yaml
version: '1.0'

# =======================================
# Domains and Cloudflare Configuration
# =======================================
domains:
  default_provider: 'cloudflare'
  default_ssl: true
  default_force_ssl: true
  default_redirect_www: true
  default_hsts: true

  providers:
    cloudflare:
      api_token: 'your_cloudflare_api_token_here'
      account_id: 'your_cloudflare_account_id_here'
      tunnels:
        main_tunnel:
          zone_id: 'your_cloudflare_zone_id_here'
          domain: example.com
          enabled: true

  base_domains:
    app.example.com:
      instance: production_instance

# =======================================
# Backup Configuration
# =======================================
backup:
  enabled: true
  output_dir: '/opt/odoo-data/backups'
  format: 'zip'

# =======================================
# Repositories
# =======================================
repositories:
  custom_addons:
    source_type: 'git'
    type: 'github'
    url: 'https://github.com/your-org/odoo-addons.git'
    branch: '17.0'
    submodules: false

# =======================================
# Instances
# =======================================
instances:
  production_instance:
    odoo_version: '17.0'
    data_dir: '/opt/odoo-data/${name}'

    paths:
      config: '${data_dir}/etc/odoo.conf'
      addons: '${data_dir}/addons'
      logs: '${data_dir}/logs'
      filestore: '${data_dir}/filestore'

    ports:
      http: 8069
      longpolling: 8072

    repositories:
      custom_addons: {}

    env_vars:
      # -- Odoo Connection Settings (for odoo.conf)
      DB_VERSION: '15'
      DB_HOST: 'db_${name}'
      DB_PORT: '5432'
      DB_USER: '${name}_user_db'
      DB_PASSWORD: 'your_secure_db_password_here'
      ADMIN_PASSWORD: 'your_secure_admin_password_here'
      WORKERS: 4
      LIMIT_MEMORY_HARD: 2684354560
      LIMIT_MEMORY_SOFT: 2147483648
      TIMEZONE: 'America/Lima'

      # -- Host ports (can be overridden by environment)
      ODOO_HTTP_PORT: '8069'
      ODOO_LONGPOLLING_PORT: '8072'

    deployment:
      type: 'docker'
      docker:
        web:
          image: 'odoo:17.0'
          user: 'root'
          container_name: 'web_${name}'
          restart_policy: 'unless-stopped'
          volumes:
            - '${paths.addons}:/mnt/extra-addons'
            - '${paths.config}:/etc/odoo/odoo.conf'
            - '${paths.logs}:/var/log/odoo'
            - '${paths.filestore}:/root/.local/share/Odoo'
          networks:
            - 'net_${name}'
          # ports: # Used for HTTP mode - expose ports
          #   - '${env_vars.ODOO_HTTP_PORT}:8069'
          #   - '${env_vars.ODOO_LONGPOLLING_PORT}:8072'
          depends_on:
            - 'db_${name}'
          environment:
            TZ: '${env_vars.TIMEZONE}'
          healthcheck:
            test: ["CMD", "curl", "-f", "http://localhost:8069"]
            interval: "30s"
            timeout: "10s"
            retries: 3
            start_period: "30s"

        db:
          image: 'postgres:${env_vars.DB_VERSION}'
          container_name: 'db_${name}'
          restart_policy: 'unless-stopped'
          volumes:
            - '${data_dir}/postgresql:/var/lib/postgresql/data'
          networks:
            - 'net_${name}'
          # ports: # Used for HTTP mode - expose ports
          #   - '${env_vars.DB_PORT}:5432'
          environment:
            TZ: '${env_vars.TIMEZONE}'
            POSTGRES_USER: '${env_vars.DB_USER}'
            POSTGRES_PASSWORD: '${env_vars.DB_PASSWORD}'
            POSTGRES_DB: 'postgres'
          healthcheck:
            test: ["CMD-SHELL", "pg_isready -U ${env_vars.DB_USER}"]
            interval: "10s"
            timeout: "5s"
            retries: 5
```

### 🚀 Basic Workflow

#### 1. Setup and Validation
```bash
# Validate configuration
dooservice config validate dooservice.yml

# Create instance
dooservice instance create production_instance --verbose

# Start instance
dooservice instance start production_instance --verbose
```

#### 2. Cloudflare Setup
```bash
# Initialize tunnel
dooservice cloudflare tunnel init main_tunnel --verbose

# Enable domain
dooservice cloudflare domain enable app.example.com --verbose

# Check status
dooservice cloudflare domain status app.example.com --verbose
```

#### 3. Repository Management
```bash
# Sync repositories
dooservice repository sync production_instance --verbose

# Check repository status
dooservice repository status production_instance custom_addons
```

#### 4. Monitoring
```bash
# Check instance status
dooservice instance status production_instance

# View logs
dooservice instance logs production_instance --follow

# Test domain connectivity
dooservice cloudflare domain test app.example.com
```

### 🔧 Common Operations

#### Instance Management
```bash
# Execute commands in container
dooservice instance exec production_instance "odoo shell -d database_name"

# Stop/start/restart instance
dooservice instance stop production_instance
dooservice instance start production_instance
dooservice instance restart production_instance  # Stop + Start in one command

# Sync configuration changes
dooservice instance sync production_instance --verbose
```

#### Backup Operations
```bash
# List databases
dooservice backup databases production_instance

# Create backup
dooservice backup create production_instance --database production_db

# Test backup functionality
dooservice backup test production_instance --database production_db
```

#### Cloudflare Operations
```bash
# List all tunnels
dooservice cloudflare tunnel list --verbose

# List all domains
dooservice cloudflare domain list --verbose

# Disable/enable domain
dooservice cloudflare domain disable app.example.com
dooservice cloudflare domain enable app.example.com

# View domain logs
dooservice cloudflare domain logs app.example.com --tail 50 --follow
```

## 📚 Configuration

The `dooservice.yml` file is the heart of DooService CLI. It defines your entire Odoo infrastructure in a declarative way.

### 📦 Modular Configuration (New in v0.7.0)

Split large configuration files into smaller, focused modules for better organization and maintainability.

#### Basic Example

```yaml
# dooservice.yml (main file)
version: "1.0"

imports:
  - domains.yml
  - repositories.yml
  - instances/production.yml
  - instances/development.yml

# Global configuration
backup:
  enabled: true
  output_dir: /opt/dooservice/backups
```

```yaml
# domains.yml
domains:
  default_provider: cloudflare
  base_domains:
    app.example.com:
      name: app.example.com
      instance: production
```

```yaml
# repositories.yml
repositories:
  odoo:
    source_type: git
    url: https://github.com/odoo/odoo
    branch: "18.0"
```

```yaml
# instances/production.yml
instances:
  production:
    odoo_version: "18.0"
    data_dir: /opt/odoo/production
    # ... rest of configuration
```

#### Features

- **🔀 Import Multiple Files**: Load configuration from multiple YAML files
- **🔄 Deep Merge**: Configurations are automatically merged recursively
- **🛡️ Circular Detection**: Prevents infinite import loops
- **📁 Relative Paths**: Import paths are resolved relative to the importing file
- **🎯 Organized by Concern**: Separate domains, repositories, and instances into their own files

#### Usage

```bash
# All imports are processed automatically
dooservice cli config validate dooservice.yml
dooservice cli instance start production

# Configuration is merged transparently
dooservice cli config load dooservice.yml
```

See the complete example in [`examples/modular-config/`](examples/modular-config/) with detailed documentation.

### Basic Structure

```yaml
# Configuration version
version: "1.0"

# Global repositories that can be used by instances
repositories:
  my-addons:
    url: "https://github.com/your-org/odoo-addons.git"
    branch: "main"

# Instance definitions
instances:
  production:
    # Odoo configuration
    odoo_version: "17.0"
    data_dir: "/opt/odoo-data/production"

    # Port configuration
    ports:
      web: 8069
      db: 5432

    # Environment variables
    env_vars:
      ADMIN_PASSWORD: "admin123"
      DB_HOST: "db_production"
      DB_USER: "odoo"
      DB_PASSWORD: "odoo123"

    # Repository configuration
    repositories:
      - name: "my-addons"
        path: "/mnt/extra-addons"

    # Backup configuration (required for backup operations)
    backup:
      database: "production_db"
      output_path: "/opt/backups/production"
      format: "zip"
      container_name_pattern: "web_{instance_name}"
      xmlrpc_url: "http://localhost:8069"

  development:
    odoo_version: "17.0"
    data_dir: "/opt/odoo-data/dev"

    ports:
      web: 8070
      db: 5433

    env_vars:
      ADMIN_PASSWORD: "dev123"
      DB_HOST: "db_development"
      DB_USER: "odoo"
      DB_PASSWORD: "odoo123"

    repositories:
      - name: "my-addons"
        path: "/mnt/extra-addons"

    backup:
      database: "dev_db"
      output_path: "/opt/backups/dev"
      format: "zip"
```

### Repository Configuration

```yaml
repositories:
  # Public repository
  odoo-community:
    url: "https://github.com/OCA/server-tools.git"
    branch: "17.0"

  # Private repository (requires SSH key)
  custom-addons:
    url: "git@github.com:your-org/private-addons.git"
    branch: "main"

  # Specific commit/tag
  stable-addons:
    url: "https://github.com/your-org/addons.git"
    commit: "abc123def456"
```

### Backup Configuration

Backup operations require explicit configuration. No default values are assumed:

```yaml
instances:
  my-instance:
    # ... other configuration ...

    backup:
      # Required: Database name to backup
      database: "my_instance_db"

      # Required: Output path for backup files
      output_path: "/opt/backups/my-instance"

      # Optional: Backup format (default: zip)
      format: "zip"  # or "dump"

      # Optional: Container name pattern (default: web_{instance_name})
      container_name_pattern: "web_{instance_name}"

      # Optional: XML-RPC URL (default: http://localhost:8069)
      xmlrpc_url: "http://localhost:8069"
```

### Cloudflare Configuration

DooService CLI supports complete Cloudflare integration for tunnel and domain management:

```yaml
version: "1.0"

# Global domains configuration with Cloudflare
domains:
  # Optional: Global defaults
  default_provider: "cloudflare"
  default_ssl: true
  default_force_ssl: true

  # Cloudflare provider configuration
  providers:
    cloudflare:
      # Required: API token with Account:Tunnel:Edit and Zone:DNS:Edit permissions
      api_token: "your_cloudflare_api_token_here"

      # Required: Cloudflare account ID
      account_id: "your_account_id_here"

      # Tunnel configurations
      tunnels:
        main-tunnel:
          zone_id: "your_zone_id_here"
          domain: "example.com"
          enabled: true

  # Domain mappings (domain name as key)
  base_domains:
    app.example.com:
      instance: "production"        # Required: maps to instance name

    dev.example.com:
      instance: "development"

    api.example.com:
      instance: "api-service"

# Repository configurations
repositories:
  custom-addons:
    source_type: "git"
    type: "github"
    url: "https://github.com/your-org/odoo-addons.git"
    branch: "17.0"
    submodules: false

# Enhanced instance configuration with DB_VERSION support
instances:
  production:
    odoo_version: "17.0"
    data_dir: "/opt/odoo-data/${name}"

    ports:
      http: 8069
      longpolling: 8072

    repositories:
      custom-addons: {}

    env_vars:
      DB_VERSION: "15"                  # Database version environment variable
      DB_HOST: "db_${name}"
      DB_USER: "${name}_user_db"
      DB_PASSWORD: "secure_password_here"
      ADMIN_PASSWORD: "admin_password_here"
      WORKERS: 4
      TIMEZONE: "America/Lima"

    deployment:
      type: "docker"
      docker:
        web:
          image: "odoo:17.0"
          container_name: "web_${name}"
          restart_policy: "unless-stopped"
          # ... docker configuration ...
        db:
          image: "postgres:${env_vars.DB_VERSION}"
          container_name: "db_${name}"
          restart_policy: "unless-stopped"
          # ... postgres configuration ...
```

#### Cloudflare Setup Requirements

##### 1. Create an API Token

Create a Cloudflare API token with the following permissions:

| Type    | Item              | Permission |
|---------|-------------------|------------|
| Account | Cloudflare Tunnel | Edit       |
| Zone    | DNS               | Edit       |

**Steps to create API Token:**
1. Go to [Cloudflare Dashboard](https://dash.cloudflare.com/profile/api-tokens)
2. Click "Create Token"
3. Use "Custom token" template
4. Set the permissions as shown in the table above
5. Add zone resources for the zones you want to manage
6. Copy the generated token (keep it secure!)

##### 2. Get Required IDs

- **Account ID**: Found in Cloudflare Dashboard sidebar (right panel)
- **Zone ID**: Found in domain's Overview page under "API" section

##### 3. Domain Configuration Requirements

Each domain in `base_domains` must specify:
- `instance`: The instance name it maps to
- `zone_id`: The Cloudflare Zone ID for the domain

## 🌐 Cloudflare Usage Guide

### Complete Setup Walkthrough

This section provides a complete step-by-step guide for setting up Cloudflare integration with your Odoo instances.

#### Step 1: Configure Cloudflare in dooservice.yml

Based on your Cloudflare setup, configure your `dooservice.yml`:

```yaml
version: "1.0"

domains:
  default_provider: "cloudflare"
  default_ssl: true
  default_force_ssl: true

  providers:
    cloudflare:
      api_token: "your_api_token_here"
      account_id: "your_account_id_here"
      tunnels:
        main-tunnel:
          zone_id: "your_zone_id_here"
          domain: "example.com"
          enabled: true

  base_domains:
    app.example.com:
      instance: "production"
    dev.example.com:
      instance: "development"
    api.example.com:
      instance: "api-service"

instances:
  production:
    odoo_version: "17.0"
    data_dir: "/opt/odoo-data/production"
    ports:
      http: 8069
    env_vars:
      DB_VERSION: "15"
      DB_HOST: "db_production"
      # ... other configuration
```

#### Step 2: Initialize Cloudflare Tunnel

```bash
# Create and configure a tunnel
dooservice cloudflare tunnel init main-tunnel --verbose

# Check if tunnel was created successfully
dooservice cloudflare tunnel list --verbose
```

**What this does:**
- Creates a new Cloudflare tunnel with the specified name
- Configures the tunnel with your domain settings
- Sets up the tunnel token for authentication
- Creates Docker networks for tunnel connectivity

#### Step 3: Enable Domains

```bash
# Enable your production domain
dooservice cloudflare domain enable app.example.com --verbose

# Enable development domain
dooservice cloudflare domain enable dev.example.com --verbose

# Check all configured domains
dooservice cloudflare domain list --verbose
```

**What this does:**
- Creates DNS CNAME records pointing to your tunnel
- Connects your instance containers to the tunnel network
- Configures tunnel ingress rules for the domain
- Enables SSL/TLS encryption automatically

#### Step 4: Verify and Monitor

```bash
# Check domain status and connectivity
dooservice cloudflare domain status app.example.com --verbose

# Test domain connectivity
dooservice cloudflare domain test app.example.com --verbose

# Monitor domain logs
dooservice cloudflare domain logs app.example.com --follow --tail 50
```

### Common Workflows

#### Adding a New Domain

1. **Add to configuration:**
   ```yaml
   domains:
     base_domains:
       new.example.com:
         instance: "new-instance"
   ```

2. **Enable the domain:**
   ```bash
   dooservice cloudflare domain enable new.example.com --verbose
   ```

3. **Verify it's working:**
   ```bash
   dooservice cloudflare domain test new.example.com
   ```

#### Disabling a Domain Temporarily

```bash
# Disable domain (removes DNS and tunnel config)
dooservice cloudflare domain disable app.example.com --verbose

# Re-enable when ready
dooservice cloudflare domain enable app.example.com --verbose
```

#### Synchronizing Configuration Changes

When you modify your `dooservice.yml` configuration:

```bash
# Sync changes to Cloudflare
dooservice cloudflare domain sync app.example.com --verbose

# Or sync all domains
dooservice cloudflare domain list | grep -o '[a-zA-Z0-9.-]*\.' | while read domain; do
  dooservice cloudflare domain sync "$domain" --verbose
done
```

#### Troubleshooting

```bash
# Check overall tunnel status
dooservice cloudflare tunnel list --verbose

# Check specific domain status
dooservice cloudflare domain status problematic.example.com --verbose

# View detailed logs
dooservice cloudflare domain logs problematic.example.com --tail 100

# Test connectivity
dooservice cloudflare domain test problematic.example.com --verbose
```

### Advanced Configuration

#### Multiple Tunnels Setup

```yaml
domains:
  providers:
    cloudflare:
      tunnels:
        production-tunnel:
          zone_id: "zone_id_1"
          domain: "prod.example.com"
          enabled: true
        staging-tunnel:
          zone_id: "zone_id_2"
          domain: "staging.example.com"
          enabled: true
```

#### Environment-Specific Domains

```yaml
domains:
  base_domains:
    # Production domains
    app.example.com:
      instance: "production"
    api.example.com:
      instance: "production-api"

    # Development domains
    dev-app.example.com:
      instance: "development"
    dev-api.example.com:
      instance: "development-api"

    # Staging domains
    staging.example.com:
      instance: "staging"
```

### Security Best Practices

1. **API Token Security:**
   ```bash
   # Store API token in environment variable
   export CLOUDFLARE_API_TOKEN="your_token_here"

   # Reference in configuration
   api_token: "${CLOUDFLARE_API_TOKEN}"
   ```

2. **Minimal Permissions:**
   - Only grant necessary permissions to API tokens
   - Use zone-specific tokens when possible
   - Regularly rotate API tokens

3. **Network Security:**
   - Tunnel traffic is automatically encrypted
   - Use Cloudflare's security features (WAF, DDoS protection)
   - Monitor access logs through Cloudflare dashboard

### Real-World Example

Here's a complete real-world configuration pattern:

```yaml
version: "1.0"

domains:
  default_provider: "cloudflare"
  default_ssl: true
  default_force_ssl: true

  providers:
    cloudflare:
      api_token: "${CLOUDFLARE_API_TOKEN}"
      account_id: "${CLOUDFLARE_ACCOUNT_ID}"
      tunnels:
        company-tunnel:
          zone_id: "${CLOUDFLARE_ZONE_ID}"
          domain: "company.com"
          enabled: true

  base_domains:
    erp.company.com:
      instance: "production"
    test-erp.company.com:
      instance: "testing"
    dev-erp.company.com:
      instance: "development"

repositories:
  custom-addons:
    source_type: "git"
    url: "https://github.com/company/odoo-addons.git"
    branch: "17.0"

instances:
  production:
    odoo_version: "17.0"
    data_dir: "/opt/odoo-data/production"
    ports:
      http: 8069
    repositories:
      custom-addons: {}
    env_vars:
      DB_VERSION: "15"
      WORKERS: 4
      TIMEZONE: "America/New_York"
```

**Usage commands:**
```bash
# Setup everything
dooservice instance create production
dooservice cloudflare tunnel init company-tunnel
dooservice cloudflare domain enable erp.company.com

# Monitor
dooservice cloudflare domain status erp.company.com
dooservice instance logs production --follow
```

## 🏗️ Architecture

DooService CLI v0.5.0 implements **Clean Architecture** principles:

### Module Structure
```
dooservice/
├── core/                 # Configuration management
│   ├── application/      # Configuration use cases
│   ├── domain/          # Configuration entities and services
│   └── infrastructure/  # YAML parsing, CLI adapters
├── instance/            # Instance management
│   ├── application/     # Instance use cases
│   ├── domain/         # Instance entities and services
│   └── infrastructure/ # Docker adapters, CLI
├── backup/             # Backup operations
│   ├── application/    # Backup use cases
│   ├── domain/        # Backup entities and services
│   └── infrastructure/ # XML-RPC adapters, CLI
├── repository/         # Repository management
│   ├── application/    # Repository use cases
│   ├── domain/        # Repository entities and services
│   └── infrastructure/ # Git adapters, CLI
├── domains/            # Domain and tunnel management
│   └── cloudflare/     # Cloudflare integration
│       ├── application/ # Domain/tunnel use cases
│       ├── domain/     # Domain entities and services
│       └── infrastructure/ # Cloudflare API, Docker network adapters
└── shared/            # Cross-cutting concerns
    └── messaging/     # Unified messaging system
```

### Key Principles
- **Domain-Driven Design**: Each module represents a bounded context
- **Dependency Inversion**: All dependencies point inward to domain
- **Configuration-First**: No hardcoded values, explicit configuration required
- **Type Safety**: Comprehensive type hints and validation
- **Clean Separation**: Clear boundaries between layers

## 🛠️ Development

### Architecture Guidelines

- **Application Layer**: Use cases orchestrating business logic
- **Domain Layer**: Pure business logic with no external dependencies
- **Infrastructure Layer**: External adapters (CLI, Docker, Git, etc.)

### Adding New Features

1. Follow Clean Architecture patterns
2. Add domain entities and services first
3. Create use cases for business logic
4. Implement infrastructure adapters
5. Add CLI commands last

### Running Tests

```bash
# Run all tests
uv run pytest

# Run with coverage
uv run pytest --cov=dooservice

# Run specific module tests
uv run pytest tests/backup/
```

### Code Quality

```bash
# Format code
uv run ruff format

# Lint code
uv run ruff check

# Type checking
uv run mypy dooservice/
```

## 🤝 Contributing

We welcome contributions! Please see our contributing guidelines:

1. Fork the repository
2. Create a feature branch following Clean Architecture
3. Add tests for new functionality
4. Ensure all tests pass and code is properly formatted
5. Submit a pull request

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## 🆘 Support

- **Documentation**: [GitHub Wiki](https://github.com/apiservicesac/dooservice-cli-py/wiki)
- **Issues**: [GitHub Issues](https://github.com/apiservicesac/dooservice-cli-py/issues)
- **Discussions**: [GitHub Discussions](https://github.com/apiservicesac/dooservice-cli-py/discussions)

---

**Made with ❤️ by API SERVICE SAC**
