odoo-devops-tools

A small set of DevOps utilities for local Odoo development and simple Odoo deployments.

The main entry point is odt-env, a CLI that provisions an Odoo workspace from a single project file.

Main features

• Clone and update Odoo and addon repositories
• Provision a Python virtual environment and automatically install Python dependencies from addons
• Generate helper scripts for running, testing, updating, shell access, database initialization, backup, and restore

---

Requirements

• git: https://git-scm.com/install/
• uv (Python package & project manager): https://docs.astral.sh/uv/getting-started/installation/

---

Installation

Using pip:

pip install odoo-devops-tools

Or using uv:

uv tool install --reinstall odoo-devops-tools

Verify:

odt-env --help

---

Usage

All examples assume that PostgreSQL is running on 127.0.0.1, listening on the default port 5432 and that PostgreSQL role odoo already exists.

If your setup is different, update the relevant db_* settings in the project file:

[config]
db_host = 127.0.0.1
db_port = 5432
db_user = odoo
db_password = odoo

1. Minimal example

This is the minimal example for provisioning a workspace with Odoo 18.

1.1. Create a project file

Create a file named odoo-project.ini.

Note odoo-project.ini is only an example filename used in this README. The project file can have a different name.

[virtualenv]
requirements =
  lxml>=6

[odoo]
version = 18.0

[config]
db_host = 127.0.0.1
db_name = odoo
db_user = odoo
db_password = odoo

1.2. Create the workspace from the project file

Run odt-env against the project file:

odt-env odoo-project.ini --sync-all --create-venv

After provisioning, the workspace has the following structure:

ROOT/
├── odoo-project.ini      # project definition
├── odoo/                 # Odoo source repository
├── odoo-addons/          # addon repositories from [addons.<name>] sections; unused in this minimal example
├── odoo-backups/         # backups created by helper scripts
├── odoo-configs/         # generated configuration, including odoo-server.conf
├── odoo-data/            # Odoo data directory
├── odoo-logs/            # runtime logs
├── odoo-scripts/         # generated helper scripts
│   ├── run.sh            # start Odoo in the foreground
│   ├── instance.sh       # manage Odoo as a background service (start|stop|restart|status)
│   ├── test.sh           # run Odoo tests
│   ├── shell.sh          # open an Odoo shell
│   ├── initdb.sh         # initialize the configured database
│   ├── backup.sh         # create a timestamped ZIP backup in ROOT/odoo-backups/
│   ├── restore.sh        # restore a backup into the configured database
│   ├── restore_force.sh  # restore a backup and overwrite an existing database
│   ├── update.sh         # update modules, auto-detecting addons to update using file-content hashes stored in the DB
│   └── update_all.sh     # force a full upgrade (-u base)
├── venv/                 # Python virtual environment
└── wheelhouse/           # wheelhouse for offline installs

1.3. Initialize database and start Odoo

When the workspace is ready, initialize Odoo database:

./odoo-scripts/initdb.sh

Then start Odoo:

./odoo-scripts/run.sh

On Windows, use the .bat variants instead:

odoo-scripts\initdb.bat
odoo-scripts\run.bat

The server starts with the generated configuration from ROOT/odoo-configs/odoo-server.conf.

After the server starts, Odoo is available at http://localhost:8069.

---

2. Adding extra addons from Git and local folders

To extend Odoo with additional functionality, you can add extra addons through [addons.<name>] sections.

In this example, we add two addon repositories, OCA/web and OCA/helpdesk, and one local folder, odoo-addons/my-custom-addons, containing custom Odoo addons.

2.1. Update the project file

Add the extra addons to the odoo-project.ini file.

[virtualenv]
requirements =
  lxml>=6

[odoo]
version = 18.0

[addons.oca-web]
repo = https://github.com/OCA/web.git
branch = ${odoo:version}

[addons.oca-helpdesk]
repo = https://github.com/OCA/helpdesk.git
branch = ${odoo:version}

[addons.my-custom-addons]
path = odoo-addons/my-custom-addons

[config]
db_host = 127.0.0.1
db_name = odoo
db_user = odoo
db_password = odoo

2.2. Update the workspace

After changing the project file, run odt-env again to update the workspace:

odt-env odoo-project.ini --sync-all --create-venv

This clones the Git-based addons into ROOT/odoo-addons/oca-web/ and ROOT/odoo-addons/oca-helpdesk/.

Both Git-based addon directories and the local folder ROOT/odoo-addons/my-custom-addons/ are then added to the generated addons_path.

If any of these addon sources contains a requirements.txt file, odt-env automatically installs the listed dependencies into the Python virtual environment.

2.3. Optional: Use full clones instead of shallow clones

By default, odt-env uses shallow, single-branch clones for Git repositories.

In most cases, shallow clones are the right choice, especially for third-party addons and for the main Odoo repository.

A full clone usually only makes sense for custom addons that are actively being developed, where access to the full Git history is useful.

If you need the full Git history, set shallow = false in the relevant section and run odt-env again with a sync option.

Example:

[addons.my-custom-addons]
repo = https://github.com/example/my-custom-addons.git
branch = 18.0
shallow = false

2.4. Update database and run Odoo

Once the workspace has been updated, refresh installed modules:

./odoo-scripts/update.sh

Then start Odoo:

./odoo-scripts/run.sh

---

3. Using system Python instead of managed Python

By default, odt-env uses uv to install and manage the requested Python version.

If you already have a suitable system Python installed, you can disable managed Python.

3.1. Update the project file

Disable managed Python by adding python_version = 3.11 and managed_python = false to the odoo-project.ini file.

Note Set python_version to the Python version you want to use from your local system. In the example below, 3.11 is only illustrative.

[virtualenv]
python_version = 3.11
managed_python = false
requirements =
  lxml>=6

3.2. Update the workspace

After changing the project file, run odt-env again to update the workspace:

odt-env odoo-project.ini --sync-all --create-venv

This recreates the virtual environment at ROOT/venv using the system Python.

---

4. Simple offline deployment using a prebuilt wheelhouse

This example shows a simple deployment workflow:

1. On an internet-connected build machine, prepare the workspace and build the wheelhouse.
2. Copy the prepared workspace to the target machine.
3. On the target machine, recreate the virtual environment strictly offline from the existing wheelhouse.

4.1. Prepare the workspace on the build machine

On the build machine, run odt-env normally:

odt-env odoo-project.ini --sync-all --create-venv

This syncs Odoo and addon repositories, resolves and locks Python dependencies, and builds ROOT/wheelhouse/ for offline installation.

After that, transfer the prepared workspace to the target machine. The simplest approach is to copy the entire ROOT/ directory.

4.2. Recreate the virtual environment on the target machine

On the target machine, run:

odt-env /path/to/odoo-project.ini --create-venv-from-wheelhouse

This recreates ROOT/venv, skips lock compilation and wheelhouse build, and performs a strict offline install from the existing ROOT/wheelhouse/.

This is useful for simple deployments where Python dependencies are prepared on a connected build machine, while the target machine creates the virtual environment without internet access.

---

Command-line reference

Paths and outputs

• --root — workspace root directory (default: the directory containing the INI file)
• -e KEY=VALUE, --extra-var KEY=VALUE — override or inject a value in the optional [vars] section; can be repeated
• --no-configs — do not generate config files
• --no-scripts — do not generate helper scripts under ROOT/odoo-scripts/
• --no-data-dir — do not create the Odoo data directory

Repository sync

• --sync-odoo — sync only ROOT/odoo
• --sync-addons — sync only ROOT/odoo-addons/*
• --sync-all — sync both Odoo and addons

Note If any target repository contains local uncommitted changes, odt-env aborts the sync operation. Commit, stash, or discard the changes before running a sync command.

Python, virtual environment, and wheelhouse

• --create-venv — recreate ROOT/venv and refresh the wheelhouse; if ROOT/venv already exists, it is deleted and created again
• --create-venv-from-wheelhouse — recreate ROOT/venv from an existing ROOT/wheelhouse/ and all-requirements.lock.txt, install strictly offline, and skip lock compilation and wheelhouse build
• --clear-pip-wheel-cache — remove all items from pip's wheel cache

---

Project file reference

The odt-env project file is an INI file that describes the Odoo workspace to create.

At minimum, the project file must contain these sections:

• [odoo]
• [config]

The following sections are supported:

• [vars] — optional reusable variables for INI interpolation
• [virtualenv] — optional Python and dependency settings
• [odoo] — required Odoo source settings
• [addons.<name>] — optional addon sources
• [config] — required Odoo server configuration values

General rules

• The project file can have any filename. In this README, odoo-project.ini is only an example.
• INI interpolation is supported, so values such as ${odoo:version} can be reused across sections.
• The optional [vars] section is useful for reusable values referenced as ${vars:name}.
• Values from [vars] can be overridden from the CLI with -e name=value / --extra-var name=value.
• Multi-line values are used for lists such as requirements, build_constraints, and requirements_ignore.

[vars]

This section is optional.

Use it for reusable values that you want to interpolate in other sections.

A major advantage of [vars] is that its values can also be overridden directly from the CLI with -e KEY=VALUE / --extra-var KEY=VALUE. This makes it easy to keep a single project file and adjust things like Odoo version, branch, or database name per run without editing the file.

Example:

[vars]
branch = 18.0
db = odoo

[odoo]
version = 18.0
branch = ${vars:branch}

[config]
db_name = ${vars:db}
db_user = odoo
db_password = odoo

CLI override example:

odt-env odoo-project.ini --sync-all --create-venv -e branch=dev -e db=odoo_dev

[virtualenv]

This section is optional.

• python_version — Python version for the virtual environment. If omitted, odt-env chooses a default version based on the selected Odoo version.
• managed_python — whether uv should install and manage Python automatically. Default: true.
• requirements — additional Python requirements to install. Multi-line list.
• build_constraints — additional build constraints used during dependency compilation. Multi-line list.
• requirements_ignore — package names to ignore when collecting requirements from addon repositories. Multi-line list.

Example:

[virtualenv]
python_version = 3.11
managed_python = false
build_constraints =
  setuptools<82
requirements =
  lxml>=6
  requests
requirements_ignore =
  babel

[odoo]

This section is required.

• version — Odoo version in X.0 format, for example 18.0. Required.
• repo — Git repository URL for Odoo. Default: the official Odoo repository.
• branch — Git branch to check out. Default: the same value as version.
• shallow — whether to use a shallow clone. Default: true.

Example:

[odoo]
version = 18.0
repo = https://github.com/odoo/odoo.git
branch = 18.0
shallow = true

[addons.<name>]

Addon sections are optional. You can define as many as needed.

Each addon must use exactly one of these source types:

• local addon path: path
• git repository: repo + branch (+ optional shallow)

Rules:

• For a local addon, use only path.
• For a git addon, repo and branch are required.
• shallow is optional for git addons and defaults to true.
• Relative local paths are resolved relative to ROOT/.
• Git-based addons are cloned into ROOT/odoo-addons/<name>/.
• All configured addon directories are automatically appended to the generated addons_path.

Examples:

[addons.my-custom-addons]
path = odoo-addons/my-custom-addons

[addons.oca-web]
repo = https://github.com/OCA/web.git
branch = ${odoo:version}
shallow = true

[config]

This section is required.

It contains Odoo server configuration values written into ROOT/odoo-configs/odoo-server.conf.

You can define standard Odoo configuration options here.

Special rules:

• addons_path must not be set in [config]. odt-env always generates it automatically.
• data_dir may be set in [config]. If provided, it overrides the default data directory location.

Example:

[config]
db_host = 127.0.0.1
db_port = 5432
db_name = odoo
db_user = odoo
db_password = odoo
http_port = 8069