Zodoo overview

Zodoo (formerly Wodoo) is a developer-centric Docker framework for Odoo, built and maintained by Zebroo. It bundles Odoo, Postgres and the surrounding tooling into a reproducible, container-based workflow so you can spin up, debug and update Odoo projects with a handful of CLI commands — instead of wrestling with manual virtualenvs, system Python versions and ad-hoc Docker configurations.

In short: Zodoo is the productivity layer between you and Odoo.

When to use Zodoo

Zodoo is the right choice when you need to:

Run an Odoo instance locally (development, testing, or demoing) without polluting your host system.
Reproduce production environments consistently across Mac, Windows (WSL2) and Linux dev machines.
Iterate quickly on custom modules with built-in support for code reload, demo data and database resets.
Wire Odoo into CI/CD pipelines (with zCICD and zSYNC) for automated tests, builds and deployments.
Manage multiple Odoo projects on the same machine, each with its own version, port and Postgres database.

💡 If your goal is to simply call an Odoo API from a Python script, you don't need Zodoo — use Odoo's native XML-RPC / JSON-RPC or a thin client library. Zodoo's value lies in running and managing the Odoo instance itself.

📘 Technical overview

🧠 Core concept

Zodoo wraps a standard Odoo deployment in a Docker Compose stack and exposes a single CLI (odoo) that orchestrates:

The Odoo server container (with the Python version your project requires).
A Postgres container with sane defaults for development.
Auxiliary services (cron, queue jobs, asset compilation, etc.) configured automatically from your project's manifest.

All project state — selected Odoo version, port, demo flag, Python version, etc. — lives under ~/.odoo/settings.<project-name>, so each project on your machine is independent and reproducible.

🧱 Architecture at a glance

┌────────────────────────────────────────────────────────┐
│                    Your project repo                   │
│        (custom modules + MANIFEST + addons)            │
└──────────────────────────┬─────────────────────────────┘
                           │ odoo reload
                           ▼
┌────────────────────────────────────────────────────────┐
│      Generated docker-compose + ~/.odoo/settings.*     │
└──────────────────────────┬─────────────────────────────┘
                           │ odoo build / up -d
                           ▼
┌──────────────┐     ┌──────────────┐     ┌────────────┐
│  Odoo (web)  │ ◀─▶ │  Postgres    │ ◀─▶ │ Side svcs  │
│  container   │     │  container   │     │ (cron, …)  │
└──────────────┘     └──────────────┘     └────────────┘

🛠 Installation & quick start

The full step-by-step setup lives in the OS-specific guides — pick the one that matches your machine:

🍎 Local Odoo Development Setup on Mac
🪟 Local Odoo Development Setup on Windows (via WSL2)
🐧 Linux: follow the Windows/WSL guide from step 4 onward (the WSL environment is plain Ubuntu)

The high-level workflow is always the same:

Install Zodoo from the official installer:

   bash <(curl -fsSL https://raw.githubusercontent.com/Odoo-Ninjas/zodoo/refs/heads/main/install.sh)
   # Registers the global `odoo` CLI on your machine via pipx.

Initialise a project in your Odoo repo:

   odoo init .
   # Prompts you to pick an Odoo version (e.g. 16.0, 17.0, 18.0)
   # and clones the matching Odoo source into the project workspace.

Bootstrap & run:

   odoo reload    # generate docker-compose from your manifest
   odoo build     # build the Docker images
   odoo up -d     # start Odoo + Postgres in the background
   odoo -f db reset  # initialise the database (with demo data if ODOO_DEMO=1)
   odoo update    # install/upgrade modules listed in MANIFEST

Open Odoo at the URL shown by odoo status (default credentials: admin / admin).

📡 Common operations

The odoo CLI is the single entry point for everything. The most-used commands:

Project lifecycle

odoo init .
# Initialises a new Zodoo project in the current directory.
# Prompts for the Odoo version to clone.

bash

odoo reload
# Regenerates docker-compose and ~/.odoo/settings.<project> by parsing
# your modules' manifests and resolving their dependencies.
# Run this any time settings or module dependencies change.
# Safe to call during build.

odoo reload --demo
# Same as above, but enables Odoo's demo data for every module.
# Must be set BEFORE the database is initialised.

odoo build
# Builds the Docker images defined by docker-compose
# (Odoo image, Postgres, side services). Equivalent to `docker compose build`.

bash

odoo next
# Picks the next available host port and stores it in the project settings.
# Useful when running multiple Zodoo projects in parallel.
# Requires `odoo reload` afterwards to apply.

Running & debugging

odoo up -d
# Starts all containers in detached (background) mode.

odoo status
# Prints the project's URL, DB info, default credentials and feature flags.

odoo dev
# Recreates the containers in dev mode (the equivalent of `odoo debug odoo`),
# enabling interactive debugging of the Python code.

Database management

odoo -f db reset
# Drops the Postgres DB, recreates it and (if ODOO_DEMO=1) loads demo data.
# -f = force, skip the interactive confirmation. Great for a clean dev slate.

odoo -f restore odoo-db <dump-path>
# Example: odoo -f restore odoo-db ~/odoo_dumps/customer.dump.gz
# Restores a database dump into the project's Postgres container.

odoo restore-web-icons
# Repairs broken ir.attachments links after a restore by deleting the
# ir.attachments table and recreating its entries.

Modules & code

odoo update
# Installs/upgrades every module listed in your project's MANIFEST.
# Run this after pulling new code, after `db reset`, or after editing
# models, views, security or data files.

odoo update <module_name>
# Faster targeted update of a single module.

Configuration

odoo config --full
# Prints the full effective configuration for the current project.

odoo setting POSTGRES_VERSION 17
# Pins the Postgres major version.

odoo setting ODOO_PYTHON_VERSION 3.12
# Pins the Python interpreter used inside the Odoo container.
# Requires `odoo reload` + `odoo build` afterwards.

odoo setting DEVMODE=1 -s
# Enables development mode globally (-s = system-wide for all projects).

odoo setting ODOO_DEMO=1
# Tells the next `db reset` to load demo data.

📋 For the full command reference, run odoo --help or odoo <command> --help.

🧪 Developer tips & best practices

Learn Odoo's APIs first. Zodoo orchestrates Odoo — it doesn't replace it. The ORM, security model and view system you debug inside the container are vanilla Odoo.
Pin your versions. Always set ODOO_PYTHON_VERSION and POSTGRES_VERSION explicitly so your team and CI run the exact same stack you do.
Use one project per repo. Don't share ~/.odoo/settings.* between projects — let odoo init and odoo next keep them isolated.
Run heavy operations in the background. odoo up -d + odoo logs is friendlier than blocking your terminal.
Wrap Zodoo in CI. The same commands you use locally (odoo reload, odoo build, odoo update) are the building blocks of zCICD pipelines — keep your local and CI workflows symmetrical.
Reset early, reset often. odoo -f db reset is fast and gives you a clean state — much better than chasing migration bugs in a stale local DB.