Professional CLI tool for managing Odoo instances with declarative configuration, automated backups, snapshots, and GitHub integration.

These details have not been verified by PyPI

Project links

Project description

DooService CLI

Professional command-line tool for managing Odoo instances with Docker

DooService CLI provides a declarative, configuration-first approach to managing complex Odoo deployments. Define your entire infrastructure in YAML and manage everything from the command line.

🚀 Quick Start

# 1. Install
pipx install dooservice-cli

# 2. Check system dependencies
dooservice doctor

# 3. Initialize project
dooservice init

# 4. Edit configuration
nano dooservice.yml

# 5. Create and start instance
dooservice create production

✨ Key Features

🐳 Docker-native - Full Docker & Docker Compose integration
📝 Configuration-first - Define everything in YAML
🐍 Python dependencies - Auto-install packages in containers
🌐 Cloudflare tunnels - Automatic domain and DNS management
📦 Git repositories - Auto-sync custom addons
💾 Backup & snapshots - Database backup and restore
🔄 Smart workflows - Deploy, rebuild, destroy with data preservation
🪟 Cross-platform - Works on Windows, Linux, and macOS

📦 Installation

Using pipx (Recommended)

pipx install dooservice-cli

Using pip

pip install dooservice-cli

Using uv

uv tool install dooservice-cli

Development Installation

git clone https://github.com/apiservicesac/dooservice-cli-py.git
cd dooservice-cli-py
uv tool install --editable .

🎯 Commands Reference

System Commands

# Initialize configuration structure
dooservice init [-p|--path DIR] [--minimal] [-f|--force]

# Check system health and dependencies
dooservice doctor

Instance Lifecycle

# Create instance (NAME is required)
dooservice create NAME [-c|--config FILE]

# Start instance (NAME optional, interactive selection if omitted)
dooservice start [NAME] [-c|--config FILE]

# Stop instance (NAME optional, interactive selection if omitted)
dooservice stop [NAME] [-c|--config FILE]

# Delete instance (NAME optional, interactive selection if omitted)
dooservice delete [NAME] [-c|--config FILE] [--force] [--keep-data] [--keep-domain]

# Restart instance
dooservice restart [NAME] [-c|--config FILE]

# List all instances
dooservice list [-c|--config FILE]

# Show instance status
dooservice status [NAME] [-c|--config FILE]

# View logs
dooservice logs [NAME] [--service SERVICE] [--follow] [--tail N] [-c|--config FILE]

# Execute command in container
dooservice exec NAME COMMAND [--user USER] [--workdir DIR] [-c|--config FILE]

# Sync repositories and configuration
dooservice sync NAME [-c|--config FILE] [--no-restart]

# Update Odoo modules
dooservice update-modules NAME -d|--database DATABASE [-m|--modules MODULE]... [-a|--all] [-p|--http-port PORT] [-c|--config FILE]

Quick Aliases

# Shortcuts for common commands
dooservice ls [-c|--config FILE]        # Alias for 'list'
dooservice ps [-c|--config FILE]        # Alias for 'list'
dooservice up [NAME] [-c|--config FILE] # Alias for 'start'
dooservice down [NAME] [-c|--config FILE] # Alias for 'stop'
dooservice rm [NAME] [-c|--config FILE] [...] # Alias for 'delete'

Workflow Commands

# Deploy: create + start + domain setup
dooservice deploy [NAME] [-c|--config FILE]

# Rebuild: stop + delete (keep data/domain) + create + start + domain sync
dooservice rebuild [NAME] [-c|--config FILE]

# Destroy: stop + delete
dooservice destroy [NAME] [-c|--config FILE] [--force]

Repository Management

# List repositories for an instance
dooservice repo list INSTANCE_NAME [--repo-name NAME] [-c|--config FILE]

# Show detailed status of a repository
dooservice repo status INSTANCE_NAME REPO_NAME [-c|--config FILE]

# Synchronize repositories
dooservice repo sync INSTANCE_NAME [--repo-name NAME] [-q|--quiet] [--test] [-c|--config FILE]

Backup Management

# Create backup
dooservice backup create INSTANCE_NAME [-d|--database NAME] [--format zip|dump] [-o|--output DIR] [-c|--config FILE] [-v|--verbose]

# Test backup connection
dooservice backup test INSTANCE_NAME [-d|--database NAME] [-c|--config FILE]

# List available databases
dooservice backup databases INSTANCE_NAME [-c|--config FILE]

Tunnel Management

# Initialize Cloudflare tunnel from configuration
dooservice tunnel init [-c|--config FILE] [-v|--verbose] [--force]

# Delete tunnel and associated DNS records
dooservice tunnel delete [-c|--config FILE] [-v|--verbose]

# Check tunnel status
dooservice tunnel status [-c|--config FILE]

# Show tunnel logs
dooservice tunnel logs [-n|--tail N] [-f|--follow] [-c|--config FILE]

# Restart tunnel container
dooservice tunnel restart [-c|--config FILE]

# Stop tunnel container
dooservice tunnel stop [-c|--config FILE]

Domain Management

# Enable domain (create DNS records and tunnel config)
dooservice domain enable NAME [-c|--config FILE] [-v|--verbose]

# Disable domain (remove DNS and disconnect tunnel)
dooservice domain disable NAME [-c|--config FILE] [-v|--verbose]

# Sync domain with instance (connect to tunnel network)
dooservice domain sync NAME [-c|--config FILE] [-v|--verbose]

# List configured domains
dooservice domain list [-c|--config FILE]

# Check domain status
dooservice domain status NAME [-c|--config FILE]

# Test domain connectivity and response
dooservice domain test NAME [-c|--config FILE]

# Show logs for domain's associated instance
dooservice domain logs NAME [-n|--tail N] [-f|--follow] [-c|--config FILE]

Configuration Management

# Validate configuration file
dooservice config validate FILE

# Load and display configuration
dooservice config load FILE [--no-validate]

# Create new configuration
dooservice config create FILE [--no-validate]

# Convert configuration format
dooservice config convert INPUT [--output FILE]

⚙️ Configuration Guide

Basic Structure

version: '1.0'

# Optional: Import other configuration files
imports:
  - config/defaults.yml
  - config/domains.yml
  - config/repositories.yml

# Global defaults (optional)
defaults:
  instance:
    odoo_version: '19.0'
    db_version: '17'

# Cloudflare integration (optional)
domains:
  default_provider: 'cloudflare'
  providers:
    cloudflare:
      api_token: 'YOUR_TOKEN'
      account_id: 'YOUR_ACCOUNT_ID'
      tunnels:
        main-tunnel:
          zone_id: 'YOUR_ZONE_ID'
          domain: 'example.com'
  base_domains:
    app.example.com:
      instance: 'production'

# Backup configuration (optional)
backup:
  enabled: true
  output_dir: 'odoo-data/backups'
  format: 'zip'

# Snapshot configuration (optional)
snapshot:
  enabled: true
  default_storage_dir: 'odoo-data/snapshots'
  retention:
    days: 60
    max_snapshots: 100

# Repository definitions (optional)
repositories:
  custom-addons:
    source_type: 'git'
    type: 'github'
    url: 'https://github.com/your-org/odoo-addons.git'
    branch: 'main'

# Instance definitions (required)
instances:
  production:
    odoo_version: '19.0'
    data_dir: 'odoo-data/${name}'

    ports:
      http: 8069
      longpolling: 8072

    repositories:
      custom-addons: {}

    python_dependencies:
      - 'pandas>=1.5.0'
      - 'requests>=2.28.0'

    env_vars:
      DB_HOST: 'db_${name}'
      DB_USER: 'odoo'
      DB_PASSWORD: 'secure_password'
      ADMIN_PASSWORD: 'admin_password'
      WORKERS: 4

    deployment:
      type: 'docker'
      docker:
        web:
          image: 'odoo:${odoo_version}'
          container_name: 'web_${name}'
          restart_policy: 'unless-stopped'
        db:
          image: 'postgres:${db_version}'
          container_name: 'db_${name}'
          restart_policy: 'unless-stopped'

Configuration Sections

1. Global Defaults (`defaults`)

Define default values inherited by all instances:

defaults:
  instance:
    # Versions
    odoo_version: '19.0'              # Odoo version
    db_version: '17'                  # PostgreSQL version

    # Directories
    data_dir: 'odoo-data/${name}'     # Data directory (relative path)

    # Auto Backup
    auto_backup:
      enabled: false
      db_name: '${name}_db'

    # Paths (inside data_dir)
    paths:
      config: '${data_dir}/etc/odoo.conf'
      addons: '${data_dir}/addons'
      logs: '${data_dir}/logs'
      filestore: '${data_dir}/filestore'

    # Default ports
    ports:
      http: 8069
      longpolling: 8072
      expose: []                      # Options: [], ['web'], ['db'], ['web', 'db']

    # Default repositories
    repositories: {}

    # Environment variables
    env_vars:
      # Network
      ODOO_HTTP_PORT: 8069
      ODOO_LONGPOLLING_PORT: 8072

      # Database
      DB_HOST: 'db_${name}'
      DB_PORT: 5432
      DB_USER: 'odoo'
      DB_PASSWORD: 'odoo'
      ADMIN_PASSWORD: 'admin'

      # Performance
      WORKERS: 2
      LIMIT_MEMORY_SOFT: 2147483648   # 2GB
      LIMIT_MEMORY_HARD: 2684354560   # 2.5GB
      LIMIT_REQUEST: 8192
      LIMIT_TIME_CPU: 60
      LIMIT_TIME_REAL: 120
      MAX_CRON_THREADS: 2

      # General
      PROXY_MODE: true
      LIST_DB: false
      TIMEZONE: 'America/Lima'

    # Python packages to auto-install
    python_dependencies: []

    # Snapshot settings
    snapshot:
      enabled: true
      storage_dir: '${data_dir}/snapshots'
      include_backup_by_default: true
      retention:
        days: 60
        max_snapshots: 20

    # Deployment configuration
    deployment:
      type: 'docker'
      docker:
        web:
          image: 'odoo:${odoo_version}'
          container_name: 'web_${name}'
          restart_policy: 'unless-stopped'
          user: 'root'
          volumes:
            - '${paths.addons}:/mnt/extra-addons'
            - '${paths.config}:/etc/odoo/odoo.conf'
            - '${paths.logs}:/var/log/odoo'
            - '${paths.filestore}:/var/lib/odoo'
          networks:
            - 'net_${name}'
          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/web/health"]
            interval: "30s"
            timeout: "10s"
            retries: 3
            start_period: "40s"

        db:
          image: 'postgres:${db_version}'
          container_name: 'db_${name}'
          restart_policy: 'unless-stopped'
          user: 'root'
          volumes:
            - '${data_dir}/postgresql:/var/lib/postgresql/data'
          networks:
            - 'net_${name}'
          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
            start_period: "10s"

2. Domains Configuration (`domains`)

Configure Cloudflare tunnels and domain mappings:

domains:
  # Global domain settings
  default_provider: 'cloudflare'      # Only cloudflare supported
  default_ssl: true                   # Enable SSL by default
  default_force_ssl: true             # Force HTTPS redirect
  default_redirect_www: true          # Redirect www to non-www
  default_hsts: true                  # Enable HSTS header

  # Cloudflare provider configuration
  providers:
    cloudflare:
      api_token: 'YOUR_API_TOKEN'     # Cloudflare API token (required)
      account_id: 'YOUR_ACCOUNT_ID'   # Cloudflare account ID (required)

      # Tunnel definitions
      tunnels:
        main-tunnel:
          zone_id: 'YOUR_ZONE_ID'     # Cloudflare zone ID
          domain: 'example.com'       # Root domain
          enabled: true               # Enable tunnel

  # Domain to instance mappings
  base_domains:
    app.example.com:
      instance: 'production'          # Instance name (required)

    dev.example.com:
      instance: 'development'

    test.example.com:
      instance: 'testing'

Cloudflare Setup Requirements:

Create API token with permissions: Account:Cloudflare Tunnel:Edit, Zone:DNS:Edit
Get Account ID from Cloudflare Dashboard
Get Zone ID from domain's Overview page

3. Backup Configuration (`backup`)

Global backup settings:

backup:
  enabled: true                       # Enable backup system
  output_dir: 'odoo-data/backups'     # Backup storage directory
  format: 'zip'                       # Format: 'zip' or 'dump'

  # Retention policy
  retention:
    days: 30                          # Keep backups for N days (0=unlimited)
    max_backups: 10                   # Max backup files (0=unlimited)

  # Automatic backups
  auto_backup:
    enabled: false                    # Enable scheduled backups
    format: 'zip'                     # Backup format
    schedule:
      frequency: 'daily'              # Options: daily, weekly, monthly
      time: '02:00'                   # Time in HH:MM format (24h)

4. Snapshot Configuration (`snapshot`)

Global snapshot settings:

snapshot:
  enabled: true                                    # Enable snapshot system
  default_storage_dir: 'odoo-data/snapshots'       # Snapshot storage

  # Retention policy
  retention:
    days: 60                                       # Keep for N days
    max_snapshots: 100                             # Max total snapshots

5. Repositories (`repositories`)

Define Git repositories for Odoo addons:

repositories:
  # Basic repository
  custom-addons:
    source_type: 'git'                # Type: git, zip, local, tar.gz
    type: 'github'                    # Provider: github, gitlab, git
    url: 'https://github.com/org/repo.git'
    branch: 'main'                    # Branch or tag
    submodules: false                 # Clone submodules

  # Private repository (SSH)
  private-addons:
    source_type: 'git'
    type: 'git'
    url: 'git@github.com:org/private.git'
    branch: 'main'

  # Specific commit
  stable-addons:
    source_type: 'git'
    type: 'github'
    url: 'https://github.com/org/addons.git'
    commit: 'abc123def'               # Use commit hash instead of branch

6. Instances (`instances`)

Define Odoo instances (inherits from defaults):

instances:
  production:
    # Override Odoo version
    odoo_version: '19.0'

    # Override data directory
    data_dir: 'odoo-data/${name}'

    # Override ports
    ports:
      http: 8069
      longpolling: 8072
      expose: []                      # Expose ports: [], ['web'], ['db'], ['web', 'db']

    # Attach repositories (reference from global repositories)
    repositories:
      custom-addons: {}               # Use default config
      private-addons:
        path: '/mnt/custom-addons'    # Override mount path

    # Python packages to auto-install
    python_dependencies:
      - 'pandas>=1.5.0'
      - 'requests>=2.28.0'
      - 'pillow>=9.0.0'

    # Environment variables (merged with defaults)
    env_vars:
      DB_HOST: 'db_${name}'
      DB_USER: 'odoo'
      DB_PASSWORD: 'secure_password_here'
      ADMIN_PASSWORD: 'admin_password_here'
      WORKERS: 4
      TIMEZONE: 'America/Lima'

    # Override deployment (optional, uses defaults if not specified)
    deployment:
      type: 'docker'
      docker:
        web:
          image: 'odoo:${odoo_version}'
          container_name: 'web_${name}'
          # ... full docker config
        db:
          image: 'postgres:${db_version}'
          container_name: 'db_${name}'
          # ... full docker config

Variable Substitution

Variables are replaced automatically:

${name} - Instance name
${odoo_version} - Odoo version
${db_version} - PostgreSQL version
${data_dir} - Data directory
${paths.config} - Config file path
${paths.addons} - Addons directory path
${paths.logs} - Logs directory path
${paths.filestore} - Filestore directory path
${env_vars.VARIABLE} - Any environment variable

Modular Configuration

Split large configurations into multiple files:

# dooservice.yml (main file)
version: '1.0'

imports:
  - config/defaults.yml
  - config/domains.yml
  - config/repositories.yml
  - config/backups.yml

# config/defaults.yml
defaults:
  instance:
    odoo_version: '19.0'
    # ... other defaults

# config/domains.yml
domains:
  providers:
    cloudflare:
      api_token: '${CLOUDFLARE_API_TOKEN}'
      # ... domain config

🐍 Python Dependencies

Automatically install Python packages during instance creation:

instances:
  production:
    python_dependencies:
      - 'pandas>=1.5.0'
      - 'requests>=2.28.0'
      - 'pillow>=9.0.0'

How it works:

Create instance → containers created but stopped
Start web container temporarily
Install packages with pip3 (uses --break-system-packages for Odoo 18+)
Stop web container
Instance ready with dependencies installed

Features:

Auto-detects Odoo version for correct pip flags
Executes as root user in container
Progress tracking with spinners
Continues even if some packages fail

🪟 Cross-Platform Support

Works on Windows, Linux, and macOS:

# Configuration (same on all platforms)
data_dir: 'odoo-data/${name}'

# Windows result: odoo-data\production
# Linux/Mac result: odoo-data/production

Requirements:

Docker Desktop (Windows/Mac) or Docker Engine (Linux)
Python 3.11+
Git (for repository sync)

📚 Common Workflows

Initial Setup

# 1. Check system
dooservice doctor

# 2. Initialize configuration
dooservice init

# 3. Edit configuration
nano dooservice.yml

# 4. Validate
dooservice config validate dooservice.yml

# 5. Create instance
dooservice create production

Daily Operations

# Start instance
dooservice start production

# View logs
dooservice logs production --follow

# Check status
dooservice status production

# Stop instance
dooservice stop production

Maintenance

# Sync repositories (update code)
dooservice sync production

# Rebuild instance (recreate containers, keep data)
dooservice rebuild production

# Create backup
dooservice backup create production --database production_db

# Update Odoo modules
dooservice update-modules production -d production_db --all

Cloudflare Setup

# 1. Initialize tunnel from configuration
dooservice tunnel init

# 2. Enable a domain (connects to instance and creates DNS records)
dooservice domain enable app.example.com

# 3. Check domain status
dooservice domain status app.example.com

# 4. Test domain connectivity
dooservice domain test app.example.com

# 5. View instance logs for the domain
dooservice domain logs app.example.com --follow

🏗️ Architecture

Built with Clean Architecture principles:

dooservice/
├── core/              # Configuration management
├── instance/          # Instance lifecycle
├── backup/            # Backup operations
├── repository/        # Git repository management
├── domains/           # Cloudflare integration
└── shared/            # Common utilities

🤝 Contributing

Contributions welcome! Please see our contributing guidelines.

📄 License

MIT License - see LICENSE file for details.

🆘 Support

Documentation: GitHub Wiki
Issues: GitHub Issues
Discussions: GitHub Discussions

Made with ❤️ by API SERVICE SAC

Project details

These details have not been verified by PyPI

Project links

Release history Release notifications | RSS feed

0.13.0

Oct 18, 2025

0.11.9

Oct 17, 2025

0.11.8

Oct 15, 2025

0.11.7

Oct 15, 2025

This version

0.11.6

Oct 15, 2025

0.11.4

Oct 15, 2025

0.11.3

Oct 15, 2025

0.11.2

Oct 15, 2025

0.11.1

Oct 15, 2025

0.11.0

Oct 15, 2025

0.10.0

Oct 15, 2025

0.9.5

Oct 14, 2025

0.9.4

Oct 14, 2025

0.9.3

Oct 14, 2025

0.9.2

Oct 14, 2025

0.9.1

Oct 14, 2025

0.9.0

Oct 14, 2025

0.8.1

Oct 13, 2025

0.8.0

Oct 13, 2025

0.7.1

Oct 10, 2025

0.7.0

Oct 10, 2025

0.6.4

Oct 10, 2025

0.6.3

Oct 8, 2025

0.6.2

Oct 8, 2025

0.6.1

Sep 30, 2025

0.6.0

Sep 29, 2025

0.5.2

Sep 28, 2025

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distributions

No source distribution files available for this release.See tutorial on generating distribution archives.

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

dooservice_cli-0.11.6-py3-none-any.whl (161.6 kB view details)

Uploaded Oct 15, 2025 Python 3

File details

Details for the file dooservice_cli-0.11.6-py3-none-any.whl.

File metadata

Download URL: dooservice_cli-0.11.6-py3-none-any.whl
Upload date: Oct 15, 2025
Size: 161.6 kB
Tags: Python 3
Uploaded using Trusted Publishing? No
Uploaded via: uv/0.8.11

File hashes

Hashes for dooservice_cli-0.11.6-py3-none-any.whl
Algorithm	Hash digest
SHA256	`bc850882197379d9dc87a088d0521d6aede4116a8dda0093c940ebbac7b530cb`
MD5	`f6fae13e79dfb798870b033725710454`
BLAKE2b-256	`6251d0ac9d663a94ec4386da17d2820f3747c18fc1f6e56e1e01ba40c5ccbe09`

See more details on using hashes here.

dooservice-cli 0.11.6

Navigation

Verified details

Maintainers

Unverified details

Project links

Meta

Classifiers

Project description

DooService CLI

🚀 Quick Start

✨ Key Features

📦 Installation

Using pipx (Recommended)

Using pip

Using uv

Development Installation

🎯 Commands Reference

System Commands

Instance Lifecycle

Quick Aliases

Workflow Commands

Repository Management

Backup Management

Tunnel Management

Domain Management

Configuration Management

⚙️ Configuration Guide

Basic Structure

Configuration Sections

1. Global Defaults (defaults)

2. Domains Configuration (domains)

3. Backup Configuration (backup)

4. Snapshot Configuration (snapshot)

5. Repositories (repositories)

6. Instances (instances)

Variable Substitution

Modular Configuration

🐍 Python Dependencies

🪟 Cross-Platform Support

📚 Common Workflows

Initial Setup

Daily Operations

Maintenance

Cloudflare Setup

🏗️ Architecture

🤝 Contributing

📄 License

🆘 Support

Project details

Verified details

Maintainers

Unverified details

Project links

Meta

Classifiers

Release history Release notifications | RSS feed

Download files

Source Distributions

Built Distribution

File details

File metadata

File hashes

1. Global Defaults (`defaults`)

2. Domains Configuration (`domains`)

3. Backup Configuration (`backup`)

4. Snapshot Configuration (`snapshot`)

5. Repositories (`repositories`)

6. Instances (`instances`)