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 Odoo developers use GNU/Linux, and you are much more likely to get support from the community for OS-level issues that occur on GNU/Linux than on Windows.

It is also recommended to develop using the same environment (the same distribution and the same version) as the one that will be used in production. This will avoid nasty surprises, such as discovering on the day of deployment that a library has a different version than expected with slightly different and incompatible behavior. If your workstation is using a different OS, a good approach is to set up a Virtual Machine (VM) on your workstation and install a GNU/Linux distribution in the VM.

This book assumes that you are running Debian GNU/Linux as its stable version (this is version 9, code name Stretch, 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 without needing to be changed. Whatever Linux distribution you choose, you should have some notion of how to use it from the command line, and having knowledge about system administration will certainly not cause any harm.

We are assuming that you have Linux 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 sections, we will use $(whoami) whenever the login of your work user is required in a command line. This is a shell command that will substitute your login in the command you are typing.

Some operations will definitely be easier if you have a GitHub account. If you don't have one already, go to https://github.com and create one.

To install Odoo from a source, you need to follow these steps:

1. Run the following commands to install the main dependencies:

$ sudo apt-get update
$ sudo apt-get install -y git python3.5 postgresql nano virtualenv xz-utils wget fontconfig libfreetype6 libx11-6 libxext6 libxrender1 xfonts-75dpi

2. Download and install wkhtmltopdf:

$ wget -O wkhtmltox.tar.xz \ https://github.com/wkhtmltopdf/wkhtmltopdf/releases/download/0.12.4/wkhtmltox-0.12.4_linux-generic-amd64.tar.xz 
$ tar xvf wkhtmltox.tar.xz
$ sudo mv wkhtmltox/lib/* /usr/local/lib/
$ sudo mv wkhtmltox/bin/* /usr/local/bin/
$ sudo mv wkhtmltox/share/man/man1 /usr/local/share/man/

3. Now, use the following code to install the build dependencies:

$ sudo apt-get install -y gcc python3.5-dev libxml2-dev \
libxslt1-dev libevent-dev libsasl2-dev libssl1.0-dev libldap2-dev \
libpq-dev libpng-dev libjpeg-dev

4. Configure PostgreSQL:

$ sudo -u postgres createuser --createdb $(whoami)
$ createdb $(whoami)

5. Configure git:

$ git config --global user.name "Your Name"
$ git config --global user.email [email protected]

6. Clone the Odoo code base:

$ mkdir ~/odoo-dev
$ cd ~/odoo-dev
$ git clone -b 12.0 --single-branch\ https://github.com/odoo/odoo.git
$ cd odoo

7. Create an odoo-12.0 virtual environment and activate it:

$ virtualenv -p python3 ~/odoo-12.0
$ source ~/odoo-12.0/bin/activate

8. Install the Python dependencies of Odoo in virtualenv:

$ pip3 install -r requirements.txt

9. Create and start your first Odoo instances:

$ createdb odoo-test
$ python3 odoo-bin -d odoo-test --addons-path=addons \ 
--db-filter=odoo-test$

10. Point your browser to http://localhost:8069 and authenticate it by using the admin account and using admin as the password.

Dependencies come from various sources. First, you have the core dependencies of Odoo, the Python interpreter, which is used to run the source code, and the PostgreSQL database server, which is 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 for this as it is very simple to use, but feel free to choose any editor that you feel at ease with, as long as it works on the Console. For example, you can use vim, e3, or emacs-nox.

Wkhtmltopdf is a runtime dependency of Odoo that's used to produce PDF reports. The version that's required by Odoo 12.0 is 0.12.4, which is not included in the current GNU/Linux distributions. Fortunately for us, the maintainers of wkhtmltopdf provide pre-built packages for various distributions at http://wkhtmltopdf.org/downloads.html.

There are lots of other runtime dependencies that are Python modules, which we can install using pip3 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. Consequently, we 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 pip3 install -r requirements.txt (a file that 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. These are very useful to Python developers because they allow different workspaces with different versions of various Python libraries to be installed, possibly on different Python interpreter versions.

You can create as many environments as you wish using the virtualenv -p python3 path/to/newenv command. This will create a newenv directory in the specified location, containing a bin/ subdirectory and a lib/python3.5 subdirectory. Don't forget -p python3, or you are likely to get a Python 2.7 virtual environment that won't be able to run Odoo 12.0.

In bin/, you will find several scripts:

• activate: This script is not executed and is sourced using the shell's built-in source command. This will activate the environment by adjusting the PATH environment variable to include the bin/ directory of virtualenv. It also installs a shell function called deactivate, which you can run in order to exit virtualenv, and changes the shell prompt to let you know which virtualenv is currently activated.
• pip3: This is a special version of the pip3 command that acts inside virtualenv only.
• python3: This is a wrapper around your system's Python interpreter, which uses the packages that have been installed in virtualenv.

There are two main ways of using a virtualenv. You may activate it, as shown in this 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 script. This is mainly a matter of taste, so you should experiment and find out which style suits you better.

You may have executable Python scripts within the first line. This should look as follows:

#! /usr/bin/env python3

These will be easier to use with an activated virtualenv script.

This is the case with the odoo-bin script, which you can call in the following way:

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

On a GNU/Linux system, Odoo uses the psycopg2 Python library to connect with a PostgreSQL database. Odoo works very well with the default values, which are used to access a PostgreSQL database with psycopg2. It uses the following default values:

• By default, psycopg2 tries to connect to a database with the same username as the current user on local connections, which enables password-less authentication
• The local connection uses Unix domain sockets
• The database server listens on port 5432

There is nothing special to do here, so we simply use the postgres administrative user to create a database user who shares our login name and gives it the right to create new databases. We then create a new database with the same name as the new user. This will be used as a default database when we use the psql command.

When on a development server, it is okay to give the PostgreSQL user more rights and 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 that --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 will give additional leverage to an attacker exploiting a vulnerability in some part of the deployed code (refer to Chapter 3, 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 this book, you will need to use git commit. This will fail unless some basic configuration is performed; therefore, 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 --branch 12.0 --single-branch options 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.

Odoo developers also propose nightly builds, which are available as tarballs and distribution packages. The main advantage of using 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 that you can make your bug reports more precise and helpful for developers.

Now comes the moment you've been waiting for. To start our first instance, we first create a new empty database and then use the odoo-bin script with the following command-line arguments:

• -d database_name: Use this database by default.
• --db-filter=database_name$: Only try to connect to databases that match the supplied regular expression. One Odoo installation can serve multiple instances that live in separate databases, and this argument limits the available databases. The trailing $ is important as the regular expression is used in match mode; this allows to to avoid 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 add-ons. This list is scanned at instance creation time to populate the list of available add-on modules in the instance.

If you are using a database user with a database login that is different from your Linux login, you need to pass the following additional arguments:

• --db_host=localhost: Use a TCP connection to the database server
• --db_user=database_username: Use the specified database login
• --db_password=database_password: This is the password for authenticating against the PostgreSQL server

To get an overview of all available options, use the --help argument. We will see more of the odoo-bin script later 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 that's needed to support its operations. It will also scan the add-ons path to find the available add-on modules and insert some into the initial records in the database. This includes the admin user with the default admin password, which you will use for authentication.

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.