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:

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 vim, e3, or emacs-nox.

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.

#! /usr/bin/env python

$ ./odoo.py -d odoo-test --addons-path=addons --db-filter=odoo-test$

$ psql -c "alter role $(whoami) with password 'newpassword'"

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

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:

$ ~/odoo-dev/odoo/odoo.py

To create a work environment for your instance, you need to follow these steps:

The Odoo 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

As we can see, the Odoo start command can be a convenient way to quickstart Odoo instances with their own module directory.

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.

Set or change the master password

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:

1. To set the Master Password, you can click on that link. You will get a dialog box asking you to provide the new password:
   
2. Type in a non-trivial new password and click on Continue.
3. When the master password is already set, click the Set Master Password button at the bottom of the screen to change it
4. In the displayed dialog box, type the previous master password and the new one, and then click on Continue.

Note

The master password is in the server configuration file under the admin_password key. If the server was started without specifying a configuration file, a new one will be generated in ~/.openerp_serverrc. See the next recipe for more information about the configuration file.

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.

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_dump and 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 ~/.local/share/Odoo/filestore.

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.

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

To restore the backup, run the following command:

$ tar xf dbname.tgz
$ pg_restore -C -d dbname dbname.dump

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

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 [DEFAULT] section.

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

A very common use is to define a common prefix for the paths of the addons:

[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

To activate Developer Mode in the web interface:

When in developer mode, three things happen: