Introduction

Overview

This project aims to simplify the process of development and maintenance of addons developer for Odoo.

This project is successor of odoo-helper-scripts

Following features available:

• Super easy installation of Odoo for development
• Super easy installation of Odoo for production (see docs)
• Simple way to manage multiple development instances of Odoo on same developer's machine
• Everything (including nodejs) installed in virtualenv - no conflicts with system packages
• Best test runner for Odoo modules:
  • Easy run test for developed modules
  • Show errors in the end of the log, that is really useful feature for large (few megabytes size test logs)
  • Test module migrations with ease
• Super easy of third-party addons installation:
  • Install modules directly from Odoo Apps
  • Easily connect git repositories with Odoo modules to Odoo instance managed by Odood
  • Automatic resolution of addons dependencies:
    • Handle requirements.txt
    • Handle odoo_requirements.txt
• Simple database management via commandline: create, backup, drop, rename, copy database
• Simple installation via prebuilt debian package (see releases)
• Support for assemblies: single repo with all addons for project, populated in semi-automatic way.
• Build with docker-support in mind

The War in Ukraine

2022-02-24 Russia invaded Ukraine...

If you want to help or support Ukraine to stand against russian inavasion, please, visit the official site of Ukraine and find the best way to help.

Thanks.

Supported OS

Currently debian-based operation systems supported. Tested on Ubuntu and Debian. Theoretically if should work on MacOS also.

Supported Odoo versions

• Odoo 18.0 (experimental)
• Odoo 17.0 (tested)
• Odoo 16.0 (tested)
• Odoo 15.0 (tested)
• Odoo 14.0 (tested)
• Odoo 13.0 (tested)
• Odoo 12.0 (tested)
• Odoo 11.0 (best efforts)
• Odoo 10.0 (best efforts)
• Odoo 9.0 (best efforts)
• Odoo 8.0 (best efforts)
• Odoo 7.0 (partial)

Installation (as Debian Package)

To install Odood, just find debian package in releases and install it. Thats all.

Note, that usually you will need to manually install additional system packages, that include:

• postgresql - if you plan to use local instance of postgresql.
• wkhtmltopdf - Required to generate pdf reports. See Odoo docs for more info.

Installation (on MacOS)

There is experimental support for MacOS implemented as homebrew's tap. Just run:

brew tap katyukha/odood
brew install odood

It is recommented to use pyenv on MacOS to init Odood projects. For example, use option --pyenv when creating new odood project via odood init:

odood init -v 18 --pyenv

Also, take into account that you have to install missing dependencies on MacOS. If you know how to make MacOS support better, just create issue or pull request with your ideas or patches.

Docker images

Odood has pre-build docker images with already installed Odoo and Odood. These images could be useful as base to distribute products based on Odoo as docker images. Take a look for base images at github package registry.

License

Odood is distributed under MPL-2.0 license.

Quick start

Overview

Odood is Command Line Interface (CLI) tool. Odood and each subcommand of Odood has option --help, thus if you are interested what it can do, just type odood --help :)

Installation

In order to install Odood, you have to do following:

1. Visit releases page
2. Download .deb package for desired architecture
3. Install downloaded .deb package.

Usually you will need to manually install additional system packages, that include:

• postgresql - if you plan to use local instance of postgresql.
• wkhtmltopdf - Required to generate pdf reports. See Odoo docs for more info.

Odoo installation

There are two types of Odoo installation supported by Odood:

• Development
• Production

Development installation

Development installation is designed to be super easy for developer. Thus it just installs Odoo and everything needed into specified directory. No specific user for Odoo process, no access restrictions, etc. Instead, it is designed to be able to work with multiple Odoo instances installed on same system.

To install Odoo 18 for development, following command could be used:

odood init -i odoo-18 -v 18

But, usually it is used with other options, to use separate database user and separate port for each development Odoo instance. For example:

odood init -i odoo-18 -v 18 --db-user=odoo18 --http-port=18069

After this command, Odoo 18 will be installed in odoo-18 directory. Next, if current working directory is inside odoo-18, then odood command could be used to manage this instance.

Production installation

Production installation more focuses on security, and stabiltiy. Thus, it do following additional tasks:

• Creates separate user to run Odoo
• Creates systemd service or init script to run Odoo at startup
• Optionally configures:
  • logrotate
  • nginx
  • fail2ban

For more info take a look at Production Deployment article.

Server management

After installation following commands available to manage Odoo server:

• odood server start - start Odoo in background
• odood server stop - stop Odoo if running
• odood server restart - restart Odoo
• odood server browse - open Odoo in your browser
• odood server run - run odoo itself.
• odood server log - view server logs (automatically use less utility to view Odoo server log)
• odood server status - Check if Odoo server is running or not
• odood status - status of this Odoo instance.

Database management

Now we can create new Odoo database inside installed Odoo instance.

To do this we can use following command:

odood db create --demo --tdb --recreate

This command will create new test Odoo database on this Odoo instance. The name for test odoo database is generated automatically as <dbuser>-odood-test. Such test database is useful during development stage: you do not need to thing about name of database during frequent database creation/recreation.

Or, we can create demo database with specific name

odood db create --demo --recreate my-demo-db

Next we can view list of databases:

odood db list

Also, there is shortcut for this frequently used command:

odood lsd

Additionally following commands may be useful:

• odood db drop
• odood db copy
• odood db backup
• odood db restore
• odood db rename
• odood db stun - disable cron jobs and mail servers
• odood db list-installed-addons - show list of addons installed in specific DB

Addons management

One of the frequent usecases of Odood is management of third-party modules (or own addons).

Install third-party addon

Let's install for example module generic_location from generic-addons repository.

To do this, we can use following command:

odood repo add https://github.com/crnd-inc/generic-addons

Or we can use shortcut:

odood repo add --github crnd-inc/generic-addons

This command will fetch specified git repository, and store it at repositories/crnd-inc/generic-addons directory in project root, and all addons in that repo will be automatically symlinked to custom_addons directory inside project root, thus they will become visible for Odoo.

Next, we could use following command to install module generic_location into created database:

odood addons install -d my-demo-db generic_location

After this command, module generic_location will be installed in database my-demo-db

Update third-party modules

One of the most frequent tasks related to management of Odoo servers is update of third party modules. In our case, we have repository generic-addons, and we may need to update modules from this repo. To do this, we have to use following algorithm: 0. Take backup (use odood db backup -a for this)

1. Pull changes from repo (use git pull for this)
2. Stop Odoo server
3. Install / update all required dependencies
4. Run update for all modules from this repo for all databases.
5. Start Odoo server again

Using Odood for our example, it could be done in following way:

#  Change current working directory to repository that we want to update
cd repositories/crnd-inc/generic-addons

# Pull changes for the repository
git pull

# We have to relink addons in case when new addons were added
# or new python dependencies were added.
# With this command Odood will handle most of this cases automatically
odood addons link .

# Update all modules inside current directory for all databases
# Also, automatically update list of addons in each database.
# This command will automatically stop Odoo before update if needed
# and start again after update.
odood addons update -a --ual --dir .

Addons management commands

• add - Add addons to the project
• update-list -Update list of addons.
• link - Link addons in specified directory.
• generate-py-requirements - Generate python's requirements.txt from addon's manifests. By default, it prints requirements to stdout.
• update - Update specified addons.
• install - Install specified addons.
• is-installed - Print list of databases wehre specified addon is installed.
• uninstall - Uninstall specified addons.
• list - List addons in specified directory.
• find-installed - Find addons installed on specified database(s).

Running tests

During development, it is frequent case to run automated tests for modules being developed. So, Odood provides separate command odood test that runs tests for specified modules.

It is recommended to look at --help for this command (odood test -h) to get more info about what it can do.

In our case, let's run tests for module generic_location. to do this, we can run following command:

odood test -t generic_location

This command will create temporary database to run tests in, automatically find module generic_location and run tests for it with colored highlights for errors and warnings.

Also, it is possible to run test for whole repo. Assume, we are inside repositories/crnd-inc/generic-addons, then we can just run command:

odood test -t --dir .

It will automatically find all addons in this repo, and run tests for all of them on same temporary database.

Virtualenv managment

Additionally, sometimes it is useful to manage virtualenv of Odood project. For this reason, Odood has ododo venv subcommand, that contains various commands to manage virtual environment of this project:

• install-dev-tools - Install Dev Tools
• run - Run command in this virtual environment. The command and all arguments must be specified after '--'. For example: 'odood venv run -- ipython'
• reinstall-odoo - Reinstall Odoo to different Odoo version.
• npm - Run npm for this environment. All arguments after '--' will be forwarded directly to npm.
• ipython - Run ipython in this environment. All arguments after '--' will be forwarded directly to python.
• python - Run python for this environment. All arguments after '--' will be forwarded directly to python.
• update-odoo - Update Odoo itself.
• pip - Run pip for this environment. All arguments after '--' will be forwarded directly to pip.
• reinstall - Reinstall virtualenv.
• install-py-packages - Install Python packages

Production deployment

Production installation more focuses on security, and stabiltiy. Thus, it do following additional tasks:

• Creates separate user to run Odoo
• Creates systemd service or init script to run Odoo at startup
• Optionally configures:
  • logrotate
  • nginx
  • fail2ban

Also, production installation expectes that it is running on clean system, and no other Odoo installed on same system.

Note, that Odood will not automatically install indirect dependencies, thus you have to manually install following system packages (if needed):

• postgresql - it is required to install postgresql server manually, before running odood deploy command if you use --local-postgres option.
• wkhtmltopdf - Required to generate pdf reports. See Odoo docs for more info.
• nginx - if you want to exopose installed Odoo to external world via nginx. In this case, Odood will automatically generate template config for nginx.
• fail2ban - if you want to automatically block incorrect logins by IP. In this case Odood will automatically generate configs for fail2ban.

So, let's assume that all needed indirect system dependencises (in example it is only postgresql server) already installed. Then, use following command to install Odoo 18 for production with local postgres:

sudo odood deploy -v 18 --local-postgres --supervisor=systemd

After this command completed, there will be installed Odoo and it will be configured to use local postgresql. This Odoo instance will be managed by systemd service.

Note: on production installation each call to odood have to be run as sudo or from superuser. Odood will automatically handle switching access rights when needed.

Also, it is recommended to use assembly functionality to manage third-party addons on production instances.

Assembly

Assembly is a reposityry that contains all third-party odoo addons needed for certain server, that is populated with addons from various sources in semi-automatic way.

The main purpose of assembly is to simplify deployment process to production servers.

Assembly contains odood-assembly.yml file (that is also referenced as assembly-spec), that describes list of addons and list of git sources to populate this assembly with. All third-party addons will be placed into dist directory inside assembly during sync operation.

After spec is created/updated there is need to run sync operation as next step. The sync operation updates assembly with latest versions of addons according to the spec definition.

So, after sync is completed, and changes pushed to assembly git repo, the servers that use this assembly could be updated in single step, by calling command odood assembly upgrade that will do all the job.

Assembly Spec

Assembly spec is described in odood-assembly.yml file in root directory of assembly.

Assembly spec is YAML file that looks like:

spec:
  addons-list:
  - name: generic_m2o
  - name: generic_mixin
  - name: generic_tag
  sources-list:
  - url: https://github.com/crnd-inc/generic-addons
    ref: '17.0'

Assembly workflow

Typical assembly workflow could be splitted on two parts:

• Assembly maintenance
• Server operations

The first one includes such operations like:

• Initialization of new assembly
• Management of assembly spec, that describes what addons and from what sources have to be included in assembly.
• Assembly synchronization - just pull latest versions of addons defined in spec, and update the assembly repo.

The second one, includes operations to be performed on server side. These operations includes:

• Configure server to use assembly
• Upgrade server

At this moment, assembly spec have to be managed manually, by editing odood-assembly.yml file. In future, some automation may be added.

What assembly created, and server is configured to use assembly, the server management becomes pretty simple - all server updates could be done via single command:

odood assembly upgrade [--backup]

That will do all the job: pull assembly changes, relink modules, update addons on all databases, etc.

Assembly management

There is group of commands designed to deal with assemblies: odood assembly. Run odood assembly --help to get more info about available commands.

This group contains following commands:

• odood assembly init - allows to initalize assembly (new assembly or clone existing assembly from git)
• odood assembly status - show current status of assembly
• odood assembly sync - this command synchronizes assembly to actual state. This operation includes following steps done automatically:
  • Clone or update (pull) all git sources listed in spec
  • Remove all addons in dist folder of assembly
  • Copy latest versions of addons to dist folder
  • Add copied addons to git index of assembly repo
  • Optionally commit chages to assembly git repo
• odood assembly link - completely relink this assembly (remove all links to assembly from custom_addons, and create new links). This is needed to ensure that only actual assembly addons linked.
• odood assembly pull - pull changes for assembly repo. Useful during server update
• odood assembly upgrade - simple way to upgrade server that is configured to use assembly.
• odood addons update --assembly - this option could be used for odood addons install/update/uninstall commands to install/update/uninstall addons contained in assembly.

Also, command odood addons find-installed could be used to generate spec for assembly based on third-party addons installed in specified database(s). This is useful to migrate already existing Odood project to use assembly instead of multiple repositories.

Odood Directory Structure

Odood directory structure is similat to that one for odoo-helper-scripts, so most users of odoo-helper-scripts will not notice that changes.

Odood project root directory contains following folders:

• backups - directory for backups generated by odood db backup command
• conf - directory for configurations used by this odood project. Usualy contains two files: one for normal local config and one that is used to run tests
  • odoo.conf - main configuration used by default
  • odoo.test.conf - configuration used to run tests, usualy have different port then odoo.conf, and does not specify logfile, thus all log messages will be written to stderr and thus catched by odood test runner
• custom_addons - directory for all addons that are not part of Odoo. Usualy contains only symlinks to addons.
• data - Odoo data directory used to store files and sessions
• downloads - Directory contains addons downloaded directly from Odoo Market.
• odoo - Odoo source code downloaded from github.
• repositories - This directories is designed to store git repositories that contain additional (non-standard) odoo addons.
• venv - virtualenv directory
• odood.yml - configuration for this odood project.

Optional directories:

• assembly - if project is configured to use assembly, this directory will contain assembly repository.
• cache - this directory is designed to contain various caches. For example, git sources defined in assembly spec, will be clonned in cache, and reused for next sync operations.

Frequently used commands

Short list of frequently used Odood commands

Server management

• odood start - start odoo server
• odood restart - restart odoo server
• odood stop - stop odoo-helper server
• odood log - see odoo server logs
• odood browse - open running odoo installation in browser

Addons management

• odood addons list <path> - list odoo addons in specified directory
• odood addons update-list - update list of available addons in all databases available for this server
• odood addons install <addon1> [addonN] - install specified odoo addons for all databases available for this server
• odood addons update <addon1> [addonN] - update specified odoo addons for all databases available for this server
• odood addons uninstall <addon1> [addonN] - uninstall specified odoo addons for all databases available for this server
• odood addons update --dir <path> - find all installable addons in specified directory and update them
• odood addons install --dir <path> - find all installable addons in specified directory and install them
• odood addons link . - link all addons in current directory.
• odood addons add -h - add third-party addons from odoo-apps (free only) or from odoo-requirements.txt

Tests

• odoo-helper test -t <module> - test single module on temporary database
• odoo-helper test -t --dir . - test all installable addons in current directory
• odoo-helper test -t --migration --dir . - run migration test for all installable addons in current directory. This includes switching to stable branch, installing modules, optionally populating with extra data, switching back to test branch and running tests for migrated addons.
• odoo-helper test --coverage-html <module> - test single module and create html coverage report in current dir
• odoo-helper test --coverage-html --dir . - test all installable addons in current directory and create html coverage report in current dir

Pre-commit

Odood use pre-commit to run various linters, etc. Thus following commands are used to deal with it:

• odood pre-commit init - Initialize pre-commit for repository. Create default pre-commit configurations.
• odood pre-commit set-up - Install pre-commit and all necessary dependencies in virtualenv.
• odood pre-commit run - Run pre-commit hooks for this repo manually.

Repository management

• odood repo add <url> - fetch repository with third-party addons from git repo specified by url
• odood repo add --oca <name> - fetch OCA repository named name from OCA git repo. For example, --oca web means repo web from OCA.
• odood repo add --github <username/repository> - shortcut to easily fetch repo from github, by specifying only github username and repo name. For example: --github oca/web means repo web from OCA.
• odood repo bump-versions - increase versions of changed modules in git repo.

Database management

• odood db list - list all databases available for current odoo instance
• odood db create my_db - create database
• odood db backup -d my_db - backup my_db
• odood db backup -a - backup all databases on the server
• odood db drop my_db - drop database

Translation management

• odood tr regenerate --lang uk_UA <addon1> [addon2]... - regenerate translations for specified language for specified addons
• odood tr regenerate --lang uk_UA --addon-dir <path> - regenerate translations for specified language for all installable addon in specified path

Virtualenv management

• odood venv run -- <command and args> - Run some command inside virtualenv of this instance.
• odood venv install-py-packages - Install specified python packages in this virtualenv.
• odood venv install-dev-tools - Install development tools inside virtualenv of this instance.
• odood ipython - run ipython inside virtualenv of this instance.
• odood venv reinstall - resinstall virtual environment.
• odood venv update-odoo - update Odoo in this instance.

odoo_requirements.txt

odoo_requirements.txt file is a text file that describes what repositories have to be installed on Odoo instance. Originally, this format comes from odoo-helper. Odood supports it too.

This file is parsed line by line, and each line must be set of options for odoo-helper fetch command.

Format

Fetch addons form any git repository

-r|--repo <git repository>  [-b|--branch <git branch>]

Fetch addons from github repository

--github <github username/reponame> [-b|--branch <git branch>]

Fetch OCA addons from any OCA github repository

--oca <OCA reponame> [-b|--branch <git branch>]

Fetch addons direcly from Odoo Apps

--odoo-app <app name>

Notes

Note odoo_requirements.txt must end with newline symbol.

Examples

--github crnd-inc/generic-addon --module generic_tags -b 12.0
--oca project -m project_description
--odoo-app bureaucrat_helpdesk_lite