Upgrade

The Odoo Build project assists you in running upgrades for any Odoo project. This document provides a highly opinionated way to connect Odoo Build with an existing Odoo enviroment and execute the upgrade.

Setup

Odoo Build provies task file commands that take env as an argument. The env is reference to the name of a dotfile (vault/.env.$NAME). These files are managed with with the *-env commands.

Setting up a Odoo upgrade project requires the creation of a dotenv file. This guide assumes that we have the following case:

Our customer is Acme Corporation
The production server is host1.example.com and the upgrade server is host2.example.com
Odoo 16.0 production instance is running at https://odoo.example.com
Odoo 18.0 upgrade environment is running at https://upgrade.odoo.example.com
The Odoo setup is docker based. The Postgres containers have a different version
Name of Odoo databases depends on the subdomain of the url

Get started by creating the vault folder.

task init-dotenv-dir

Then create a dotenv file for the upgrade project.

task create-env acme upgrade

This will create the file with the upgrade template. Edit the file.

task edit-env acme

Update the configs with the definition of your enviroment.

First we have the source environment:

HOST: Hostname of the Odoo pruction instance
SERVER: SSH url to access the pruction server
PORT: SSH port of server
JUMP_HOST: SSH jump host
ODOO_CONTAINER: Name of production Odoo Docker container
ODOO_VERSION: Version of Odoo production
POSTGRES_CONTAINER: Name of production Postgres Docker container
DATABASE: Name of production database

Then we have the target enviroment:

TARGET_HOST: Hostname of the Odoo upgrade instance.
TARGET_SERVER: SSH url to access the upgrade server
TARGET_PORT: SSH port of server
TARGET_JUMP_HOST: SSH jump host
TARGET_ODOO_CONTAINER: Name of upgrade Odoo Docker container
TARGET_ODOO_VERSION: Version of Odoo upgrade
TARGET_POSTGRES_CONTAINER: Name of upgrade Postgres Docker container
TARGET_DATABASE: Name of upgrade database

In our case the definition is:

HOST='odoo.example.com'
SERVER='host1.example.com'
PORT=22
ODOO_CONTAINER='odoo01'
ODOO_VERSION='16.0'
POSTGRES_CONTAINER='postgres01'
DATABASE='odoo'

TARGET_HOST='upgrade.odoo.example.com'
TARGET_SERVER='host2.example.com'
TARGET_PORT=22
TARGET_ODOO_CONTAINER='odoo02'
TARGET_ODOO_VERSION='18.0'
TARGET_POSTGRES_CONTAINER='postgres02'
TARGET_DATABASE='upgrade'

Note that the HOST and TARGET_HOST is a reference to another dotenv file.

You can show the upgrade information with task upgrade-odoo amce info.

Helper Scripts

Running the upgrade requires scripts on the servers. Ensure that the following scripts are installed on the server:

https://ansible.build/scripts.html#docker provides generic Docker container commands
https://ansible.build/scripts.html#odoo helps managing the Odoo container
https://ansible.build/scripts.html#postgres supports managing the Postgres container

You probably have become aware that this project and especially the upgrade process uses scripts from different projects. Here is a list of the projects involved:

https://taskfile.build provides the basic commands to manage dotfiles
https://odoo.build is this project and provides the commands to run the upgrade steps
https://ansible.build this repo has the scripts to manage containers on the server

Test Run

Before going live with an upgraded Odoo database, the new enviroments needs to be tested thoroughly . An upgrade run copies the production database and runs the Odoo Enterprise upgrade script in test mode. On sucess a neutralized and upgraded database will be ready for testing.

Execute

You can run the entire test upgrade process with task upgrade-odoo acme all-test. This command executes all steps required to get the test enviroment. List the steps with task upgrade-odoo list. Here are the details for each step:

dump

Dump and restore the production database on the Postgres container.

task upgrade-odoo acme dump

filestore

Export and import the Odoo filestore.

task upgrade-odoo acme filestore

drop

Drop the existing upgrade database.

task upgrade-odoo acme drop

test

Run the Odoo upgrade scripts in test mode. This will neutralize the database after an upgrade.

task upgrade-odoo acme test

clear-assets

Clear Odoo assets.

task upgrade-odoo acme clear-assets

init

Init modules on the upgraded database.

This step requires an env var: ODOO_ADDONS_INIT=web_environment_ribbon

task upgrade-odoo acme init

uninstall

Uninstall modules on the upgraded database.

This step requires an env var: ODOO_ADDONS_UNINSTALL=board_user_acl,l10n_din5008_expense

task upgrade-odoo acme uninstall

auto-update

Calls the upgrade_changed_checksum method.

task upgrade-odoo acme auto-update

update

Update all modules and clear assets.

task upgrade-odoo acme update

configure-test

Run custom Python code in Odoo shell.

This step requires an env var: ODOO_CONFIGURE_TEST="env.ref('mail.ir_cron_module_update_notification').write({'active': False})"

task upgrade-odoo acme configure-test

restart

Restart target Odoo and Postgres container.

task upgrade-odoo acme restart

Troubleshooting

At any point the upgrade process can fail and requires investigating. There are additional commands that help troubleshooting the issues:

logs

Show log of target Odoo container.

task upgrade-odoo acme logs

shell

Start Odoo shell in target container.

task upgrade-odoo acme shell

psql

Start psql shell in target Postgres container.

task upgrade-odoo acme psql

Configure

With every Odoo release Odoo introduces new features and enhancements, but also deprecates features and ways of doing. If you have a heavily customized Odoo database and many features enabled, more things are bound to break in the upgrade process.

In the configuration of the upgrade process you are fixing Odoo features that cannot be automated with code. Create a list of steps to make configurations in Odoo.

Testing

The testing of an upgraded Odoo database is done in collaboration of the Odoo partner and the customer. The partner defines test cases that verify the customer's workflows. Feedback is collected and feedback loop for testing, documenting, bugfixing and restarting the upgrade process is established.

Repeat the feedback loop until you are confident that the upgraded works well. Do not aim for 100% test coverage. Minor issues can be resolved in the post-production-upgrade-phase.

Production Run

Once the testing phase of the upgrade project has finished and a date for the go-live has been chosen, you are reay for the production upgrade. This basically mans to execute the upgrade in production mode on the date of the go-live.

The goals is that production url https://odoo.example.com points to the container with upgraded Odoo database.

Execute

In order to run the production upgrade execute task upgrade-odoo acme all-production. Similar to all-test this command runs all comands to get an upgraded Odoo enviroment. Only difference is that it runs in production mode.

production

Run the Odoo upgrade scripts in production mode. This will not neutralize the database after an upgrade.

task upgrade-odoo acme production

configure-production

Run custom Python code in Odoo shell.

This step requires an env var: ODOO_CONFIGURE_PRODUCTION="env.ref('mail.ir_cron_module_update_notification').write({'active': True})"

task upgrade-odoo acme configure-production

Configure

Once the production enviroment is ready, execute the the manual configuration steps as you did for the test enviroment.

Testing

Run simple smoke tests. Ensure that the upgrade wenn well. There is no need to execute the test cases.

Rename

Until here it is still possible to abort the go-live. To go-live means to rename the target database to the original database name and ensure that https://odoo.example.com points to the target environment. Use this command to rename the database:

rename-production

Rename target database to source database.

task upgrade-odoo acme rename-production

As the final step, update DNS records and/or proxy configuration so that https://odoo.example.com points to host2.example.com.

Recovery

If something goes wrong after the go-live, fallback to the old environment. Simply revert the DNS update and/or the proxy configuration.

Cleanup

After a week of working successfully with the upgraded database, it is safe to sunset the original server and/or Odoo enviroment.

In our example this means shutting down the odoo01 container and the host1.example.com server.

Ensure that https://upgrade.odoo.example.com no longer resolves.