Odoo 13 to 14 Upgrade Guide

odoo-13-to-14-upgrade

Odoo 13 to 14 Upgrade Guide

Preamble

A long time ago for our small online shop we needed a invoicing solution and we have chosen Odoo. I think, back then, we have started with Odoo 10, but in time I have upgrade it to Odoo 13. This was done over a long period of time, and I think it happened that I have even updated at once 2 versions (jumping to Odoo 12 I think in order to ensure that we reach Python 3... if I remember correctly). Well now it is again the time: Odoo 16 is out and I am still on Odoo 13... The docker image for Odoo 13 is not even mentioned on the official page and, when I try to setup a playing ground I land in a pip requirements nightmare which is pulling my hair.

On the other hand the process was never a easy one. OpenUpgrade is the way to do it, but the instructions are somehow cryptic and there are no good end-2-end articles or tutorials. Here and there one can find some bits in articles or on the Odoo forums but most of the indications are given without context or orientation. That is why I have decided to document upgrade process this time. For me (as there are always some details that I forget) and for others.

It is not an exhaustive guide but I hope to be as universal as possible. Please note that in my installation of Odoo I am using only a few modules. Sales and Invoicing are right now in use, but in the past I have used also Inventory and Purchase, which I intend to reactivate. There is the story of another upgrade which ran smoother without them and due to time restrictions I decided back then to go without them. :-)

Please check here the OpenUpgrade Module Coverage 13.0 -> 14.0.

Structure

One of the things that is very important to understand is that the upgrade consists of 2 things:

The Odoo Code update
The Database update

The Odoo Code update is the basis: the source code of Odoo that will "play" with your data. Old Odoo in this case is using Odoo 13, the new one will use Odoo 14. This part is easy and should be done for a productive system at the end.

The Database update is the update your data, well, of the structure of your data. Right now it is in the "Odoo 13 format" and in order to be used with Odoo 14 code it needs to be adapted. Say hello to OpenUpgrade which is helping with this. Database update should always run on copies of the your data. Leave the running Odoo 13 system untouched until you can confirm that you have a "converted to Odoo 14" database copy. Backup your database from yourodoo.url/web/database/manager using the zip Backup Format (it will take the file store like for example product pictures). If you do not have yet any other backup of your data it is a very very good idea to make a copy of the actual backup and to store it to a safe location. Myself I wrote a script that is auto downloading daily my Odoo DB but this is another story.

Let's say that your backup is named odoo-13-to-14-yyyy-mm-dd.zip. Or use your own naming convention as long as it makes sense to you and you can remember what is about in a month or two or in a year or two. And of course hope that you will never come to this.

Well if we have the zip we can move to the next big chunk: THE DATABASE UPDATE

THE Database Upgrade

The infrastructure

For this I like to use VMs: they are short lived, serve their purpose and than can be killed. You can also make backups in various states of the process (just copy the VM virtual disk...) and they are also not messing with your main OS: what is in a VM remains in a VM, a kind of "Vegas of Computing". :-)

I use a spin of Debian with QEMU KVM but there are a lot of options out there (VMWare or VirtualBox for example). The below is tried by me on Debian 11 (bullseye) with a Linux 5.10.0-20-amd64 kernel. The version of python and of the odoo 14 requirements seem also to function very good with Debian 11. Newer versions of Debian or of Ubuntu have newer packages which do not satisfy the odoo 14 requirements. More details you can find below.

Another option is to run Odoo 14 in docker and then one can avoid this dependencies nightmare. Process would be slightly different and since this involves using the command line (a lot...) it seems to be easier in a full Linux version. Me personally I prefer to run bash commands within docker only when I really have to...

Debian and sudo

If during Debian installation you have chosen a password for the root then your default user will not be (in) sudo by default. The following is to be done in order to add him to sudo:

su -
apt install sudo
usermod -aG sudo <username>
exit

After su - you should give your root password. Make sure that username is your replaced with your actual username. logout in order to apply the changes.

System upgrade

Let's update the system:

sudo apt update && sudo apt upgrade -y

A first test of infrastructure

If during the installation of Debian you have chosen the web server option you can make a first test of the VM. Find your VM IP, for example using the ip a. Use this in the browser of the host machine to check if the default web server is reachable.

Installing Odoo from Source

For this upgrade I will use the installation of Odoo from source. There are more alternatives available, but this was the easiest way that I found so far: it is a bit more complicated, but it offers the best flexibility, control and "tweakability". In order to separate possible Odoo instances I will use a Python functionality called Virtual Environment (VENV).

The Virtual Environment - VENV

Since I have discovered it, I am a big fan of it. Basically is like a primitive version of a container: it allows you to run a project with all its dependencies without affecting the overall settings of the host computer.

Why is this helpful? Well, because for example you can run on a single machine multiple versions of Odoo each of them with its own dependencies.

Why is this important? Well, because different versions of Odoo can have different dependencies or they require different versions of these dependencies. Odoo as an app uses a series of standard function libraries which are documented in the requirements.txt file found inside of your odoo folder and are generally installed using the pip Python utility. And for example Odoo 13 can require the version 1.20 of a certain library, while for Odoo 14 you might need the version 3.9. Virtual Environment allows you to have them both installed, each of them in its own environment. And this without affecting the general settings of the underlying Operating System.

Further on, the Odoos (notice the plural) will be installed in Virtual Environments. We will have at least one, but the process is repeatable for another instance(s).

System dependencies

We will need the following:

sudo apt install -y git # install git
sudo apt install -y python3-dev python3-pip python3-wheel python3-venv # install Python3 Dev
sudo apt install -y build-essential libpq-dev libxslt-dev libzip-dev libldap2-dev libsasl2-dev libssl-dev # install build dependencies

Also npm is required:

sudo apt install npm # install Node.js and its package manager
sudo npm install -g less less-plugin-clean-css # install less

Installing Odoo from Source into VENV

To keep things organized we will create a directory for our Odoo installation. A bit of a back story related to OpenUpgrade: as mentioned in the documentation since Odoo 14.0 the odoo-bin executable for the OpenUpdatere was deprecated and the actual executable of Odoo installation should be used.

What does this mean? Well, it means that in order to upgrade our database from Odoo 13 to Odoo 14 we need a Odoo 14 installation with OpenUpgrade as a module of it. Let's go ahead and to this:

mkdir ~/odoo14 # create a directory for our Odoo 14 installation
cd ~/odoo14 # go into odoo14 directory
git clone https://github.com/odoo/odoo.git -b 14.0 --depth=1 # get odoo source

Odoo source should be now available in the ~/odoo14/odoo folder and you can check this by running:

ls -la ~/odoo14/odoo

In the listing you should see for example the requirements.txt file and if you are curious you can open it with your favourite text editor.

Creating the Virtual Environment

Use following command to create the Virtual Environment:

python3 -m venv ~/odoo14/env14

You can check the Python version of this Virtual Environment as follows:

~/odoo14/env14/bin/python -V

You can activate the Virtual Environment as follows:

source ~/odoo14/env14/bin/activate

You will notice that the prompt will change to something like this: (env14) user@odoo-13-14-upgrade:~/odoo14$ telling you that you are right now it the virtual environment. All the Python commands written while the virtual environment is activated will not be saved only inside of the environment and will not affect the other settings of Python. We have now our playground. Venv can be deactivated using the deactivate command. More about python virtual environments can be found on the internet. Moving on!

We need to make sure some Python utilities are up to date. Pip is the most important but we will check that also setuptools and wheel are up to date:

pip install --upgrade pip setuptools wheel

Then we can make a try to install Odoo dependencies. As mentioned they are available in the requirements.txt inside the odoo folder. Right now this is not anymore an abstract term and you can see them for example using the cat command:

cat ~/odoo14/odoo/requirements.txt

Let's install them:

pip install -r ~/odoo14/odoo/requirements.txt

Side Note 1: Personally I found this one of the biggest challenge while working with odoo, not because of odoo itself but because of what I like to call "dependencies madness". What I mean is that, for example, at the moment of writing this the above command for Odoo 14 is working in Debian 11 flawlessly. But a similar attempt for Odoo 13 is already generating some errors when installing this dependencies. This is mainly because of older versions, which are not anymore maintained and curated. In such cases, what I found to help was to look at each error and search it on the internet. Relay mostly on answers from stackoverflow or similar sites and do not move on until the requirements are installed.

Side Note 2: Some of the Python libraries require that also the system binaries are installed. If some libraries refuse to install, confirm that the respective system dependencies are installed. For example right now for Odoo 13 in order to make the installation of the pip packages possible I needed to install additional binaries like libxml2-dev or libxslt1-dev. This can be done with sudo apt install libxslt1-dev libxml2-dev for example. Read the errors, try to find what is missing and install it.

Side Note 3: If you cannot find a solution to install a deprecated dependency, one solution is to install the last version of the respective package and pray that the retro-compatibility will do the trick. To do this edit the ~/odoo14/odoo/requirements.txt and remove the version requirement of the package. For example instead of docutils==0.16 leave only docutils and rerun the above command. Cross your fingers that retro-compatibility works...

Do not move forward until the above command runs without errors.

When this is so you will have all the Odoo requirements installed inside the Virtual Environment. We need to install Odoo itself:

pip install -e ~/odoo14/odoo

If you get an error during the above command read it. For me adding a compatibility option solved the problem. The updated command is:

pip install -e ~/odoo14/odoo --config-settings editable_mode=compat

Check it running the following command:

odoo --version

If the above is returning the Odoo Server 14.0 this is a very big milestone: it means that we have a functional version of Odoo 14 available at our disposal. Another powerful thing that I think is important for newcomers is the above command: this shows how Odoo functions under the hood. With this command you can call your Odoo server and you can give it parameters in order to influence how it will run. This will be further detailed below.

Installing OpenUpgrade

Next we will need to get the OpenUpgrade:

cd ~/odoo14
git clone https://github.com/OCA/openupgrade.git -b 14.0 --depth=1

OpenUpgrade should now be available in ~/odoo14/openupgrade. You can check this with ls -la ~/odoo14/openupgrade.

Let's install OpenUpgrade requirements:

pip install -r ~/odoo14/openupgrade/requirements.txt

and make sure that the latest version of openupgradelib is installed:

pip install git+https://github.com/OCA/openupgradelib.git@master#egg=openupgradelib

PostgresSQL installation

Not to forget: we need to updated the database, so we need the database server. Let's proceed:

sudo apt install postgresql -y
sudo su -c "createuser -s $USER" postgres
sudo service postgresql start

The above commands are doing the following:

installing postgresql
creating db superuser. (in this case $USER refers to your actual user)
starting the database service

For the future one can check the status of the database server with the following command sudo service postgresql status. On systemd machines also the corresponding systemd commands can be used:

sudo systemctl start postgresql #to start the database server
sudo systemctl status postgresql #to check the database server

Uploading the database

Now its time to connect our Odoo 13 database with our Odoo 14 installation! Start odoo!

odoo

This should result in a bunch of lines with green info like this:

2023-01-06 11:56:44,035 10696 INFO ? odoo: Odoo version 14.0 
2023-01-06 11:56:44,036 10696 INFO ? odoo: addons paths: ['/home/user/odoo14/odoo/odoo/addons', '/home/user/.local/share/Odoo/addons/14.0', '/home/user/odoo14/odoo/addons'] 
2023-01-06 11:56:44,036 10696 INFO ? odoo: database: default@default:default 
2023-01-06 11:56:44,173 10696 INFO ? odoo.addons.base.models.ir_actions_report: You need Wkhtmltopdf to print a pdf version of the reports. 
2023-01-06 11:56:44,283 10696 INFO ? odoo.service.server: HTTP service (werkzeug) running on odoo-13-14-upgrade.local:8069

This window you need to let now untouched. Until CTRL+C is pressed here will run our odoo server. Not only that will run, it will also spit out info about what is going on. The good thing is that we can move now to the browser as we have a functional odoo installation. Once again: ip a will show you the IP that you need to put in browser. Odoo uses as usual port 8069. So going to your.vm.ip.here:8069 you should be welcomed by the odoo Database Selector.

Master Password: odoo will generate for you a database master password. Here and now you can change it or you can copy the one generated by default. Please do so, this will be important for the future.

Choose "restore a database" from the bottom of the page. Then give the master password mentioned above, browse for the backup of your database and select it and give to the database a name. A good practice would be yyyy-mm-dd-odoo-13-to14, this way you can recall later about what is going on here. Select "this database is a copy" and hit the "continue" button. It might take a while, but the database will be uploaded. When successful you will be redirected to the odoo database manager page where the uploaded database will be listed. Please note the exclamation mark (!) next to your database. This is the sign that the version of the database is not matching the version of the odoo server.

Now we can select the command prompt in the virtual machine (where the odoo is started and displaying log info) and press CTRL+C. This will stop the (normal) odoo instance.

The Upgrade

It is time to run the (upgrade) odoo instance, in fact is running odoo with the openupgrade as addon. We achieve this by running odoo with the following parameters:

clear #let's get a fresh terminal - this will help with the output of the next command
odoo --database <your_database_name> --addons-path=~/odoo14/odoo/addons,~/odoo14/openupgrade/ --upgrade-path ~/odoo14/openupgrade/openupgrade_scripts/scripts --update all --stop-after-init --load=base,web,openupgrade_framework

Do not forget to change with your actual database name. This should be the name that you chose for the database when you have uploaded into odoo above... Remember: "...A good practice would be yyyy-mm-dd-odoo-13-to14..."? That name! :-)

If everything went ok the upgrade should start and a lot of text will be generated in the terminal. Scroll-read through and as log and there are "green and yellow highlights" here and there everything should be ok.

"Red" is bad... Red means that the openupgrade could not handle something and failed to upgrade it. :-( In such cases my recommendation would be to read through the screen and to try to understand what did not went ok. It can be that a module that is not so important can be deactivated and to run the upgrade without it, it can be that google is your friend, it can be that the programmer that you hired a while ago did not done the best job and you shouldn't of fire him or it can be that you need more serious help (like contact an Odoo Partner...). But read through: if you get a breakthrough good, if not look for support. Btw. copy the output of the above command and save it somewhere: it is a good starting point for troubleshooting!

Otherwise, by green and yellow, this should be it: after the upgrade ran, it should stop and you should be able to start odoo normally, without any additional parameters. After you have done this open your.vm.ip.here:8069 (remember ip a in the terminal of the VM should give you the IP of the VM) and you should be greeted by your new (14) version of odoo. Congratulations!

Post Scriptum

P.S. 1: Disclaimer: the journey of this post was done in several legs. Somewhere along the way the below commands came into my notes. These are packages that can be installed in the VM and cannot hurt. It can also be very well that everything functions without them:
sudo apt install libxml2-dev libxslt1-dev
sudo apt install python3-lxml
sudo apt install python3-ldap libsasl2-dev

P.S. 2: ~ is a Linux placeholder for /home/$USER. If at anytime required replace it accordingly.