In this chapter, we will cover the following topics:
Easy installation of Odoo from source
Managing Odoo environments using the
Managing Odoo server databases
Storing the instance configuration in a file
Activating the Odoo developer tools
Updating Odoo from source
There are lots of ways to set up an Odoo development environment. This chapter proposes one of these, although you will certainly find a number of other tutorials on the web explaining other approaches. Keep in mind that this chapter is about a development environment, which has different requirements from a production environment, covered in Chapter 16, Server Deployment.
For Odoo deployment, it is recommended to use a GNU/Linux environment. You may be more at ease using Microsoft Windows or Mac OS X, but the fact is that most of the Odoo developers are using GNU/Linux and you are much more likely to get support from the community for OS-level issues happening on GNU/Linux than on Windows.
It is also recommended to develop using the same environment (same distribution, same version) as the one which will be used in production. This will avoid nasty surprises such as discovering on the day of deployment that some library has a different version than expected, with a slightly different and incompatible behavior. If your workstation is using a different OS, a good approach is to set up a virtual machine on your workstation and to install a GNU/Linux distribution in the VM.
To avoid copying files between your workstation where you are running your development environment and the virtual machine which runs Odoo, you can configure a SAMBA share inside the virtual machine and store the source code there. You can then mount the share on your workstation in order to edit the files easily.
This book assumes you are running Debian GNU/Linux as its stable version (Jessie at the time of writing). Ubuntu is another popular choice, and since it is built on top of Debian, most of the examples in this book should work unchanged. Whatever Linux distribution you choose, you should have some notion of how to use it from the command line, and having a few ideas about system administration will certainly not cause any harm.
We assume that Linux is up and running and that you have an account with root access, either because you know the root password or because
sudo has been configured. In the following pages, we will be using
$(whoami) whenever the login of your work user is required in a command line. This is a shell command which will substitute your login in the command you are typing.
Some operations will definitely be easier if you have a GitHub account. Go to https://github.com and create one if you don't have one already.
To install Odoo from source, you need to follow these steps:
Run the following commands to install the main dependencies:
$ sudo apt-get install git python2.7 postgresql nano \ python-virtualenv
Download and install
$ wget http://nightly.odoo.com/extra/wkhtmltox-0.12.1.2_linux-jessie-amd64.deb $ sudo dpkg -i wkhtmltox-0.12.1.2_linux-jessie-amd64.deb
This is a package provided by the Odoo maintainer for Debian Jessie. If you are using another distribution, browse to http://download.gna.org/wkhtmltopdf/0.12/0.12.1/ and download the package for your operating system.
$ sudo apt-get install gcc python2.7-dev libxml2-dev \ libxslt1-dev libevent-dev libsasl2-dev libldap2-dev libpq-dev \ libpng12-dev libjpeg-dev
$ sudo -u postgres createuser --createdb $(whoami) $ createdb $(whoami)
$ git config --global user.name "Your Name" $ git config --global user.email email@example.com
Clone the Odoo code base:
$ mkdir ~/odoo-dev $ cd ~/odoo-dev $ git clone -b 9.0 --single-branch https://github.com/odoo/odoo.git $ cd odoo
odoo-9.0virtual environment and activate it:
$ virtualenv ~/odoo-9.0 $ source ~/odoo-9.0/bin/activate
Install the Python dependencies of Odoo in
$ pip install -r requirements.txt
Create and start your first Odoo instances:
$ createdb odoo-test $ python odoo.py -d odoo-test --addons-path=addons \ --dbfilter=odoo-test$
You can download the example code files for this book from your account at http://www.packtpub.com. If you purchased this book elsewhere, you can visit http://www.packtpub.com/support and register to have the files e-mailed directly to you.
You can download the code files by following these steps:
Log in or register to our website using your e-mail address and password
Hover the mouse pointer on the SUPPORT tab at the top
Click on Code Downloads & Errata
Select the book for which you're looking to download the code files
Choose from the drop-down menu where you purchased this book from
Click on Code Download
You can also download the code files by clicking on the Code Files button on the book's webpage at the Packt Publishing website. This page can be accessed by entering the book's name in the Search box. Please note that you need to be logged in to your Packt account.
Once the file is downloaded, please make sure that you unzip or extract the folder using the latest version of:
WinRAR / 7-Zip for Windows
Zipeg / iZip / UnRarX for Mac
7-Zip / PeaZip for Linux
Dependencies come from various sources. First, you have the core dependencies of Odoo, the Python interpreter that is used to run the source code, and the PostgreSQL database server used to store the instance data. Git is used for source code versioning and getting the source code of Odoo itself.
Since we will need to edit some files as
root or as
postgres (the PostgreSQL administrative user) on our server, we need to install a console-based text editor. We suggest
nano as it is very simple to use, but feel free to choose any editor with which you feel at ease as long as it works on the console, such as
Wkhtmltopdf is a runtime dependency of Odoo used to produce PDF reports. The version required by Odoo 9.0 is 0.12.1, which is not included in current GNU/Linux distributions. Fortunately for us, the maintainers of wkhtmltopdf provide prebuilt packages for various distributions on http://wkhtmltopdf.org/downloads.html (in the archive section). However, Debian Jessie is not there, so the Odoo maintainers provide their own version of the package on http://nightly.odoo.com/extra/.
There are lots of other runtime dependencies that are Python modules, which we can install using
pip in a virtual environment. However, some of these Python modules can feature some dependencies on native C libraries for which the Python bindings need to be compiled. We therefore install the development packages for these C libraries as well as the Python development package and a C compiler. Once these build dependencies are installed, we can use
pip -r requirements.txt (a file which comes from the Odoo source code distribution) to download, compile, and install the Python modules.
Python virtual environments, or virtualenv for short, are isolated Python workspaces. They are very useful to Python developers because they allow different workspaces with different versions of various Python libraries installed, possibly on different Python interpreter versions.
You can create as many environments as you wish using the command
virtualenv path/to/newenv. This will create a
newenv directory in the specified location, containing a
bin/ subdirectory and a
bin/ you will find several scripts:
activate: The script is not executed, it is sourced using the built-in
sourceshell. This will activate the environment by adjusting the
PATHenvironment variable to include the
bin/directory of the
virtualenv. It also installs a shell function called
deactivate, which you can run to exit the
virtualenv, and changes the shell prompt to let you know which
virtualenvis currently activated
pip: This is a special version of the
pipcommand which acts inside the
python: This is a wrapper around your system Python interpreter which uses the packages installed in the
source shell is also available (as a single dot, followed by a space, and the path to the file to source). The shortcut form is perfectly fine, but we will stick to
source in this book for readability.
There are two main ways of using a
virtualenv. You may activate it as we show in the recipe (and call
deactivate when you're done) or you may use the scripts in the
bin/ directory of the environment explicitly by calling them with their full path, in which case you don't need to activate the
virtualenv. This is mainly a matter of taste, so you should experiment and find out which style suits you better for which case.
#! /usr/bin/env python
$ ./odoo.py -d odoo-test --addons-path=addons --db-filter=odoo-test$
In that case, there is nothing special to do: we use the
postgres administrative user to create a database user which shares our login name and give it the right to create new databases. We then create a new database with the same name as the new user, which will be used as a default database when using the
When on a development server, it is OK to give the PostgreSQL user more rights and to use the
--superuser command-line option rather than just
--createdb. The net effect is that this user can then also create other users and globally manage the database instance. If you feel
--superuser is too much, you may still want to use
--createrole in addition to
--createdb when creating your database user. Avoid doing this on production servers as it would give additional leverage to an attacker exploiting a vulnerability in some part of the deployed code (see Chapter 16, Server Deployment).
If you want to use a database user with a different login, you will need to provide a password for the user. This is done by passing the
--pwprompt flag on the command line when creating the user, in which case the command will prompt you for the password.
If the user has already been created and you want to set a password (or modify a forgotten password) you can use the following command:
$ psql -c "alter role $(whoami) with password 'newpassword'"
At some point in the book, you will need to use
git commit. This will fail unless some basic configuration is performed; you need to provide Git with your name and email address. Git will remind you to do this with a nice error message, but you may as well do it now.
Downloading the Odoo code base is done by performing a
git clone operation. Be patient as this will take some time. The options
--branch 9.0 --single-branch avoid downloading other branches and save a little time. The
--depth option can also be used to avoid downloading the whole repository history, but the downside of that option is that you will not be able to explore that history when looking for issues.
The Odoo developers also propose nightly builds, which are available as tarballs and distribution packages. The main advantage of using a git clone is that you will be able to update your repository when new bug fixes are committed in the source tree. You will also be able to easily test any proposed fixes and track regressions, so you can make your bug reports more precise and helpful for the developers.
-d database_name: Use that database by default.
--db-filter=database_name$: Only try to connect to databases matching the supplied regular expression. One Odoo installation can serve multiple instances living in separate databases and this argument limits the available databases. The trailing
$is important as the regular expression is used in match mode; this avoids selecting names starting with the specified string.
--addons-path=directory1,directory2,...: This is a comma separated list of directories in which Odoo will look for addons. This list is scanned at the instance creation time to populate the list of available add-on modules in the instance.
--db_host=localhost: use a TCP connection to the database server
--db_user=database_username: use the specified database login
--db_password=database_password: the password to use to authenticate against the PostgreSQL server
To get an overview of all the available options, use the
--help argument. We will see much more about the
odoo.py script in this chapter as well as in Chapter 2, Managing Odoo Server Instances.
When Odoo is started on an empty database, it will first create the database structure needed to support its operations. It will also scan the addons path to find the available addon modules, and insert some the initial records in the database. This includes the
admin user with the default password
admin which you will use to authenticate with.
Odoo includes an HTTP server. By default, it listens on all local network interfaces on TCP port
8069 so pointing your web browser to
http://localhost:8069/ leads you to your newly created instance.
In the recipe, we downloaded the latest stable version of Odoo using the following command:
$ git clone -b 9.0 --single-branch https://github.com/odoo/odoo.git
This uses the official branch maintained by Odoo. One issue with this branch is that bug fixes contributed by the community are not always merged in a timely fashion. The Odoo Community Association (OCA) maintains a parallel branch in which fixes and improvements are peer-reviewed by the community and tend to be merged faster than on the official branch. It is not a fork of Odoo, and the latest version of Odoo is merged back into that branch daily. You may want to use it for your developments and deployments, in which case you need to clone Odoo like this:
$ git clone -b 9.0 --single-branch https://github.com/OCA/OCB.git odoo
We will often want to use custom or community modules with our Odoo instance. Keeping them in a separate directory makes it easier to install upgrades to Odoo or troubleshoot issues from our custom modules. We just have to add that directory to the addons path and they will be available in our instance, just like the core modules are.
It is possible to think about this module directory as an Odoo environment. The Odoo
start command makes it easy to organize Odoo instances as directories, each with its own modules.
For this recipe we need to have already installed Odoo. We assume that it will be at
~/odoo-dev/odoo, and that the
virtualenv is activated.
This means that the following command should successfully start an Odoo server:
Change to the directory where Odoo is:
$ cd ~/odoo-dev
Choose a name for the environment and create a directory for it:
$ mkdir my-odoo
Change to that directory and start an Odoo server instance for that environment:
$ cd my-odoo/ $ ../odoo/odoo.py start
start command is a shortcut to start a server instance using the current directory. The directory name is automatically used as the database name (for the
-d option), and the current directory is automatically added to the addons path (the
--addons-path option) as long as it contains an Odoo addon module. In the preceding recipe you won't see the current directory in the addons path because it doesn't contain any modules yet.
By default the current directory is used, but the
--path option allows you to set a specific path to use instead. For example, this would work from any directory:
$ ~/odoo-dev/odoo/odoo.py start --path=~/odoo-dev/my-odoo
The database to use can also be overridden using the usual
-d option. In fact, all the other usual
odoo.py command-line arguments, except
--addons-path, will work. For example, to set the server listening port, use the following command:
$ ../odoo/odoo.py start --xmlrpc-port=8080
When working with Odoo, all the data of your instance is stored in a PostgreSQL database. All the standard database management tools you are used to are available, but Odoo also proposes a web interface for some common operations.
We assume that your work environment is set up and you have an instance running. Do not start it using the
odoo.py start command shown in the previous recipe, as it configures the server with some options which interfere with multi-database management.
The Odoo database management interface provides tools to create, duplicate, remove, back up, and restore a database. There is also a way to change the master password which is used to protect access to the database management interface.
Go to the login screen of your instance (if you are authenticated, log out).
Click on the Manage Databases link. This will navigate to
http://localhost:8069/web/database/manager(you can also point your browser directly to that URL.).
If you've set up your instance with default values, and not yet modified it as explained in the following section, the database management screen will display a warning telling you that the master password is not set, and advising you to set one, with a direct link:
To set the Master Password, you can click on that link. You will get a dialog box asking you to provide the new password:
Type in a non-trivial new password and click on Continue.
In the displayed dialog box, type the previous master password and the new one, and then click on Continue.
In the database management screen, click on the Create Database button at the bottom of the screen.
Fill the form in as follows:
Master password: The master password for this instance.
Database name: Input the name of the database you wish to create.
Language: Select the language you wish to be installed by default in the new database.
Password of admin user: Type the password you want to set for the admin user of the new instance.
Load demonstration data: Check this box to have demonstration data. This is useful to run tests or set up a demonstration for a customer, but should not be checked for a database meant to contain production data.
If you are redirected to a login screen, this is probably because the option
--db-filter was passed to Odoo and the new database name did not match the new database name. Note that the
odoo.py start command does this silently, making only the current database available. To work around this, simply restart Odoo without the
start command, as shown in the first recipe of this chapter. If you have a configuration file (see the Storing the instance configuration in a file recipe later in this chapter), then check that the
db_filter option is unset or set to a value matching the new database name.
Very often you will have an existing database and you want to experiment with it to try a procedure or run a test, but without modifying the existing data. The answer is simple: duplicate the database and run the tests on the copy. Repeat as many times as required:
In the database management screen, click on the Duplicate link next to the name of the database you wish to clone.
Fill in the form:
Master Password: the master password of the Odoo server
New Name: the name you want to give to the copy
Click on the Continue button.
In the database management screen, click on the Delete link next to the name of the database you want to remove.
Fill in the form; enter the Master Password, which is the master password of the Odoo server.
Click the Delete button.
In the database management screen, click the Backup link next to the database you want to back up.
Fill in the form:
Master Password: the master password of the Odoo server.
Backup Format: always use zip for a production database, as it is the only real full backup format. Only use the pg_dump format for a development database where you don't really care about the file store (
Click the Backup button. The backup file will be downloaded to your browser.
In the database management screen, click the Restore Database button at the bottom of the screen.
Fill in the form:
Master Password: the master password of the Odoo server.
File: a previously downloaded Odoo backup.
Database Name: provide the name of the database in which the backup will be restored. The database must not exist on the server.
Generate a new database uuid: leave unchecked if you are installing a database which has been deleted from the server; otherwise check the box. There is little difference between them, and if in doubt, leaving it unchecked is a safe choice.
Click the Continue button.
These features, apart from the Change master password screen, run
postgresql administration commands on the server and report back through the web interface.
The master password is a very important piece of information which only lives in the Odoo server configuration file and is never stored in the database. There used to be a default value of
admin, but using this value is a security liability as it is well known. In Odoo v9, this is identified as an "unset" master password and you get urged to change it when accessing the database administration interface. Even if it is stored in the configuration file under the
admin_passwd entry, this is not the same as the password of the
admin user; these are two independent passwords: the master password is set for an Odoo server process, which itself can handle multiple database instances, each of which has an independent
admin user with his own password.
Security considerations: Remember that we are considering a development environment in this chapter. The Odoo database management interface is something which needs to be secured when you are working on a production server as it gives access to a lot of sensitive information, especially if the server hosts Odoo instances for several different clients. This will be covered in Chapter 16, Server Deployment.
To create a new database, Odoo uses the PostgreSQL
createdb utility and calls the internal Odoo function to initialize the new database in the same way as when you start Odoo on an empty database.
To duplicate a database, Odoo uses the
--template option of
createdb passing the original database as an argument. This essentially duplicates the structure of the template database in the new database using internal and optimized PostgreSQL routines, which is much faster than creating a backup and restoring it (especially when using the web interface which requires downloading the backup file and uploading it again).
Backup and restore operations use the
pg_restore utilities respectively. When using the
.zip format, the backup will also include a copy of the file store which contains a copy of the documents when you configure Odoo to not keep these in the database, which is the default in 9.0. Unless you configure it otherwise, these files live in
If the backup gets large, downloading it may fail, either because the Odoo server itself is not able to handle the large file in memory or if the server runs behind a reverse proxy (see Chapter 16, Server Deployment) because there is a limit to the size of HTTP responses set in the proxy. Conversely, for the same reasons, you will likely experience issues with the database restore operation. When you start running into these issues, it is time to invest in a more robust external backup solution.
Experienced Odoo developers generally don't use the database management interface, and perform the operations from the command line. To initialize a new database with demo data for instance, the following one-liner can be used:
$ createdb testdb && odoo.py -d testdb
The additional bonus of this command line is that you can request installation of addons while you are at it using for instance
-i sale,purchase,stock (more on this in Chapter 2, Managing Odoo Server Instances).
To duplicate a database, stop the server, and run the following command:
$ createdb -T dbname newdbname $ cd ~/.local/share/Odoo/filestore # adapt if you have changed the data_dir $ cp -r dbname newdbname $ cd -
Note that in the context of development, the file store is often omitted.
The use of
createdb -T only works if there are no active sessions on the database, which means you have to shut down your Odoo server before duplicating the database from the command line.
To remove an instance, run the following command:
$ dropdb dbname $ rm -rf ~/.local/share/Odoo/filestore/dbname
To create a backup (assuming the PostgreSQL server is running locally), use the following command:
$ pg_dump -Fc -f dbname.dump dbname $ tar cjf dbname.tgz dbname.dump ~/.local/share/Odoo/filestore/dbname
$ tar xf dbname.tgz $ pg_restore -C -d dbname dbname.dump
odoo.py script has dozens of options, and it is tedious to remember them all and to remember to set them properly when starting the server. Fortunately, it is possible to store them all in a configuration file and to only specify by hand the ones you want to alter, for example, for development.
To generate a configuration file for your Odoo instance, run the following command:
$ odoo.py --save --config myodoo.cfg --stop-after-init
You can add additional options, and their values will be saved in the generated file. All the unset options will be saved with their default value set. To get a list of possible options, use:
$ odoo.py --help | less
This will provide you with some help about what the various options perform. To convert from the command line form to the configuration form, use the long option name, remove the leading dashes, and convert the dashes in the middle to underscores:
without_demo. This works for most options, but there are a few exceptions listed in the next section.
Edit the file
myodoo.cfg (use the table in the following section for some parameters you may want to change). Then to start the server with the saved options, run the following command:
$ odoo.py -c myodoo.cfg
At start up, Odoo loads its configuration in three passes. First a set of default values for all options is initialized from the source code. Then the configuration is parsed, and any value defined in the file overrides the defaults. Finally, the command-line options are analyzed and their values override the configuration obtained from the previous pass.
As mentioned earlier, the names of the configuration variables can be found from the names of the command-line options by removing the leading dashes and converting the middle dashes to underscores. There are a few exceptions, notably:
Here is a list of options commonly set through the configuration file:
Prevents module demo data from being loaded.
Comma separated list of paths
A list of directory names in which the server will look for addons (see Chapter 2, Managing Odoo Server instances).
The master password (see previous recipe).
Path to a directory
A directory in which the server will store session information, addons downloaded from the Internet, and documents if you enable the file store.
The name of the server running the PostgreSQL server. Use
Database user login
Database user password
This is generally empty if
Used to set the database name on which some commands operate by default). This does not limit the databases on which the server will act. See the following
A regular expression
The expression should match the name of the databases considered by the server. If you run the website, it should match a single database, so it will look like
IP address of a network interface
Path to a file
The file in which Odoo will write its logs.
Log verbosity level
Specify the level of logging. Accepted values (in increasing verbosity order):
The number of worker processes. See Chapter 16, Server Deployment, for more information.
True / False
The parsing of the configuration file by Odoo is done using the Python
ConfigParser module. This module supports defining values for variables from the values of other variables using the
%(section.variable)s notation. You can omit
section if the value comes from the same section or if it is defined in the special
For instance, if you want to define the database login to be the same as the database name, you can write the following in your Odoo configuration file:
[options] db_name = projectname db_user = %(options.db_name)s
[DEFAULT] project = /home/odoo/projects/project1 env = dev prefix = %(project)s/%(env)s [options] addons-path = %(prefix)s/odoo/addons,%(prefix)s/OCA/server-tools data_dir = %(prefix)s/data_dir
Connect to your instance and authenticate (not necessarily as
admin; this function is available to all users, but the Administrator has more tools available).
Click on the down arrow next to your user name in the top right corner of the page .
In the drop-down menu, click on About.
To exit developer mode, you can edit the URL and remove that string, close your browser tab and open a new one, or use the Leave Debug Mode option at the bottom of the debug drop-down menu next to the user menu in the top right of the screen.
When in developer mode, three things happen:
A drop-down menu with a Bug icon is displayed next to the user's menu in the top right corner giving access to technical information about the model being displayed, the various related view definitions, the workflow, custom filter management, and so on.
We saw in the first recipe how to install Odoo from source by using the git repository. The main benefit of this setting is being able to update the source code of Odoo using git to get the latest bug fixes.
Make a backup of all the databases you care about in case something goes bad. This is obviously something you need to do for production databases. See the Managing Odoo server databases recipe for instructions.
Then make a note of the current version of the source you are running. The best way is to create a lightweight tag using the following command:
$ cd ~/odoo-dev/odoo $ git checkout 9.0 $ git tag 9.0-before-update-$(date --iso)
To update the source code of Odoo, use the following command:
$ git pull –-ff-only
This will fetch the latest version of the source code committed to the current branch.
To update an instance running on this code, run the following command:
$ odoo.py -c myodoo.cfg --stop-after-init -u base
If you don't have a database set in the configuration file, you will have to add the
-d database_name option. That command is to be repeated for all the instances running with this version of the source code.
If the update fails, don't panic, you have backups.
Read the error message carefully. Save it to a file, as it will be useful to make a bug report later.
If you cannot figure out what the problem is, restore the service; restore the Odoo source code to the previous version, which is known to work using the tag you set before updating the source version:
$ git reset --hard 9.0-before-update-$(date --iso)
Drop the broken databases and restore them from the backups you made (see the Managing Odoo server databases recipe for instructions).
Note that in real life, this should never happen on a production database, because you would have tested the upgrade beforehand on a copy of the database, fixed the issues, and only done the upgrade on the production server after making sure that it runs flawlessly. But sometimes, you still get surprises, so even if you are really sure, make a backup.
Updating the source code is done by making sure we are on the correct branch using
git checkout, and then fetching the new revisions using
git pull. The
--ff-only option will cause a failure if you have local commits not present in the remote repository. If this happens and you want to keep your changes, you can use
git pull (without
--ff-only) to merge the remote changes with yours; otherwise, use
git reset --hard origin/9.0 to force the update, discarding your local modifications.
The update command uses the following options:
-c: specify the configuration file
--stop-after-init: stop the instance when the update is over
--update base: requests the update of the
When updating a module, Odoo does the following:
It updates the database structure for the models defined in the module for which the structure changes. For updates on the stable branch of Odoo, there should be no such changes, but this can happen for your own addons or third party addons.
It updates the database records stored in data files of the module, most notably the views. It then recursively updates the installed modules which have declared a dependency on the module.
base module is an implicit dependency of all Odoo modules, updating it will trigger an update of all the installed modules in your instance. To update all installed modules, the alias
all can be used instead of