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 setup:

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.

HOST: Hostname of the Odoo pruction instance
SERVER: SSH url to access the pruction server
PORT: SSH port of server
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
TARGET_HOST: Hostname of the Odoo upgrade instance.
TARGET_SERVER: SSH url to access the upgrade server
TARGET_PORT: SSH port of server
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 dotfile.

There is also JUMP_HOST and TARGET_JUMP_HOST to define the SSH jump host.

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 thats project and the upgrade process uses scripts and containers from different projects. Here is a list of projects involved to run the upgrade:

https://taskfile.build provides the basic commands to manage the dotfiles
https://odoo.build which is this project, provides the commands to run the upgrade steps
https://ansible.build as mentioned 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

All the steps required to provide an upgraded database can be run with: task upgrade-odoo acme all-test

This command executes several steps. List the steps with task upgrade-odoo acme list. Here are the details of 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.

task upgrade-odoo acme test

clear-assets

Clear Odoo assets.

task upgrade-odoo acme clear-assets

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

init

Init modules on the upgraded database.

This step requires an env var: ODOO_ADDONS_INIT=web_environment_ribbon

task upgrade-odoo acme init

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

For production use ODOO_CONFIGURE_PRODUCTION.

restart

Restart target Odoo and Postgres container.

task upgrade-odoo acme restart

Troubleshooting

There are additional commands for troubleshooting:

logs

Show log of target Odoo container.

task upgrade-odoo acme logs

shell

Start shell in target Odoo container.

task upgrade-odoo acme shell

Configure

With heavily customized Odoo databases and new features you have to make configurations that cannot be automated for an upgrade project. These configurations need to be done manually.

Once the test enviroment is ready, log in and execute the manual configuration.

Testing

The testing of an upgraded Odoo database is done in collaboration between the Odoo partner and customer. Define test cases that verify the customer's workflows. Collect feedback and establish a feedback loop of testing, documenting issues, bugfixing and redo the upgrade process.

Repeat this 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, run the upgrade in production mode.

In this scenario we ensure that the url https://odoo.example.com points to the new container after the upgrade.

Execute

In order to run the production upgrade execute task upgrade-odoo acme all-production.

Similar to all-test this command runs all comands, but instead of test it runs production.

Run the Odoo upgrade scripts in test mode

task upgrade-odoo acme production

And instead of configure-test the command runs configure-production.

Configure

Once the production enviroment is ready, execute the the manual configuration steps as you did in 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 databse:

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 envirment. 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.