Odoo Docker

Odoo Docker Infrastructure Skill

1. Overview

Docker infrastructure and deployment expert for multi-version Odoo Enterprise environments. Handles production deployment, nginx configuration, CI/CD pipelines, performance tuning, security hardening, and container troubleshooting.

v2.1: Nginx config, debugging, and performance tuning are handled via natural language. For project init, compose generation, deployment, and builds, use /odoo-docker sub-commands.

What This Skill Does

• Production Deployment: docker-compose with nginx, SSL, PostgreSQL tuning, resource limits, warm-up
• CI/CD Pipelines: Build and push multi-version Docker images via GitHub Actions
• Performance Tuning: Data-driven recommendations from real stress tests
• Nginx Configuration: Optimized configs with gzip (90% CSS reduction), WebSocket, asset caching
• Container Debugging: Systematic troubleshooting using known issue patterns
• Project Setup: Auto-detect Odoo version, scan modules, generate all configs + IDE integration
• Compose Generation: Smart compose for dev/staging/production scenarios
• Image Management: Build, tag, push images for Odoo 14-19 (amd64 + arm64)

When to Use This Skill vs odoo-service

Natural Language Triggers

• "deploy to production", "production docker setup", "deploy odoo with nginx"
• "configure nginx for odoo", "add reverse proxy", "enable gzip"
• "optimize docker performance", "slow containers", "tune workers"
• "build docker image", "push to docker hub", "ci/cd pipeline"
• "container won't start", "500 errors in docker", "debug container"
• "set up docker for this project", "initialize docker environment"
• "generate docker-compose", "create compose file"

2. User Configuration

Users can customize this plugin by creating ~/.claude/odoo-docker.local.md with YAML frontmatter. See odoo-docker.local.md.example in the plugin root for the full template.

Key settings:

• image_prefix: Docker Hub org/image prefix (default: myorg/odoo)
• default_version: Default Odoo version when not auto-detected (default: 17)
• git_org: GitHub organization for source clone suggestions

When generating configs, check for user overrides in .local.md first. If not found, use template defaults and prompt the user for their image prefix on first use.

3. Architecture

Core Principle: Source Mounted, Not Baked

Copy code
Docker Hub:  {image_prefix}:19.0-enterprise   (pre-built base image)

Workspace:
  sources/odoo-19/          <-- Odoo Enterprise source (git clone, mounted read-only)
  projects/relief_center/   <-- Custom modules (git clone, mounted)
  compose/relief_center.yml <-- Per-project Docker Compose
  conf/relief_center.conf   <-- Per-project Odoo config

One image --> Many containers. No rebuilding per project.

Key Design Decisions

1. Source code is NOT baked into the image — mounted at runtime via Docker volumes (read-only)
2. Two deployment models: Standalone workspaces (per-version Dockerfile) and centralized workspace (pre-built images from Docker Hub)
3. Container isolation: Each project gets its own Docker network, named volumes, port mappings

Container Directory Structure

Copy code
/opt/odoo/source/           <-- Odoo source (mounted, read-only)
/opt/odoo/custom-addons/    <-- Custom modules (mounted)
/etc/odoo/odoo.conf         <-- Configuration (mounted, read-only)
/var/log/odoo/              <-- Log files (mounted)
/var/lib/odoo/              <-- Filestore + compiled assets (named volume)

Exposed Ports

4. Template Files

All templates are in ${CLAUDE_PLUGIN_ROOT}/templates/. Read them with the Read tool when generating configs.

Placeholder Convention

• {placeholder} — Must be replaced by the user/skill before use
• ${ENV_VAR:-default} — Resolved automatically by Docker Compose at runtime

5. Version Matrix

Full version matrix is in ${CLAUDE_PLUGIN_ROOT}/reference/version-matrix.md. Key lookup table:

Build Workarounds (Applied Automatically)

6. Critical Configuration Notes

These are the most important settings. Getting any of them wrong causes hard-to-diagnose failures.

7. Environment Variables

Entrypoint Variables

Port Allocation Convention

8. Performance Tuning

Workers Configuration

Formula: workers = (CPU cores * 2) + 1 (capped at available RAM / 512MB per worker)

PostgreSQL Tuning

Gzip Compression (Nginx)

Asset Warm-Up

First request after restart compiles all assets (25-120s). The production compose template includes a warm-up service that pre-loads /web/login and /shop.

9. Security Hardening

High-Risk Issues (Fix Before Production)

Volume Security

• Odoo source: Always mount :ro (read-only)
• Config files: Always mount :ro
• Filestore and logs: Read-write (necessary for operation)

Network Isolation

• Each project gets its own Docker network
• Database containers are NOT exposed to host in production
• Only nginx exposes ports to the outside

10. SSL/TLS Configuration

For production HTTPS, the nginx template (${CLAUDE_PLUGIN_ROOT}/templates/nginx.conf) has commented SSL blocks. Uncomment and configure:

nginxCopy code
server {
    listen 80;
    server_name yourdomain.com;
    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl http2;
    server_name yourdomain.com;
    ssl_certificate /etc/letsencrypt/live/yourdomain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/yourdomain.com/privkey.pem;
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers HIGH:!aNULL:!MD5;
    ssl_prefer_server_ciphers on;
    # ... (same location blocks as HTTP config)
}

Add Let's Encrypt volume to production compose:

yamlCopy code
nginx:
  volumes:
    - /etc/letsencrypt:/etc/letsencrypt:ro
  ports:
    - "443:443"

11. CI/CD Pipeline

GitHub Actions Overview

• Triggers: Push to main (Dockerfile/entrypoint/requirements changes) or manual dispatch
• Matrix: Builds all 6 versions in parallel
• Multi-platform: linux/amd64 + linux/arm64
• Cache: GitHub Actions layer cache per version
• Tags: {image_prefix}:{version}.0-enterprise + SHA suffix

Required Secrets

The full GitHub Actions workflow template is generated by /odoo-docker build --generate-ci.

12. Centralized Multi-Project Workspace

Layout

Copy code
~/odoo-docker/
├── sources/         <-- Git clones of Odoo Enterprise (per version)
├── projects/        <-- Git clones of custom modules (per project)
├── conf/            <-- Generated Odoo configs
├── compose/         <-- Generated Docker Compose files
├── logs/            <-- Runtime logs
├── scripts/         <-- start.sh, stop.sh, logs.sh, shell.sh
├── .env             <-- Global config
└── .env.local       <-- Machine-specific overrides

Daily Commands

bashCopy code
./scripts/start.sh <project>            # Start containers
./scripts/start.sh <project> --dev      # Start with auto-reload
./scripts/stop.sh <project>             # Stop containers
./scripts/logs.sh <project>             # Odoo logs
./scripts/shell.sh <project> 19         # Bash into container

Running Multiple Projects

Assign unique ports per project in .env:

envCopy code
RELIEF_CENTER_HTTP_PORT=8069
SOQYA_HTTP_PORT=8169
TAQAT_HTTP_PORT=8269

13. Database Management in Docker

Create Database via API

bashCopy code
curl -s -X POST http://localhost:8069/web/database/create \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"call","params":{"master_pwd":"changeme","name":"my_db","lang":"en_US","password":"admin","login":"admin"}}'

Access from Host

bashCopy code
psql -h localhost -p 5433 -U odoo -d my_database

Backup and Restore

bashCopy code
docker exec {db_container} pg_dump -U odoo my_database > backup.sql
docker exec -i {db_container} psql -U odoo -d my_database < backup.sql

14. Debugging & Development

Dev Mode

bashCopy code
DEV_MODE=1 docker compose up -d

Remote Debugger (debugpy)

1. Set ENABLE_DEBUGGER=1 in .env
2. Expose port 5678:5678 in docker-compose
3. Container waits for IDE attach
4. VS Code config:

jsonCopy code
{
  "name": "Attach to Odoo Docker",
  "type": "debugpy",
  "request": "attach",
  "connect": { "host": "localhost", "port": 5678 },
  "pathMappings": [
    { "localRoot": "${workspaceFolder}", "remoteRoot": "/opt/odoo/source" }
  ]
}

Module Management Inside Container

bashCopy code
python -m odoo -c /etc/odoo/odoo.conf -d {db} -u {module} --stop-after-init
python -m odoo -c /etc/odoo/odoo.conf -d {db} -i {module} --stop-after-init

15. Troubleshooting

For the full troubleshooting reference with all known issue patterns and diagnostic commands, read ${CLAUDE_PLUGIN_ROOT}/reference/troubleshooting.md.

For performance-related patterns and lessons learned from stress tests, read ${CLAUDE_PLUGIN_ROOT}/reference/docker-patterns.md.

For the production deployment checklist, read ${CLAUDE_PLUGIN_ROOT}/reference/production-checklist.md.

16. Quick Command Reference

bashCopy code
# Build local image
docker compose build

# Pull pre-built image
docker pull {image_prefix}:19.0-enterprise

# Start / Stop
docker compose up -d
docker compose down

# Logs / Shell
docker compose logs -f odoo
docker compose exec odoo bash

# Module update inside container
python -m odoo -c /etc/odoo/odoo.conf -d {db} -u {module} --stop-after-init