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.
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.
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 lib/python2.7
subdirectory.
In bin/
you will find several scripts:
activate
: The script is not executed, it is sourced using the built-in source
shell. This will activate the environment by adjusting the PATH
environment 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 virtualenv
is currently activated
pip
: This is a special version of the pip
command which acts inside the virtualenv
only.
python
: This is a wrapper around your system Python interpreter which uses the packages installed in the virtualenv
.
Tip
The built-in 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.
You may have executable Python scripts with the first line looking like the following:
These will be easier to use with an activated virtualenv
. This is the case with the odoo.py
script, which you can therefore call in the following way:
On a GNU/Linux system, Odoo works very well with the default values of psycopg2
, the Python module used to access a PostgreSQL database:
Passwordless authentication if the database user has the same name as the current user on local connections
Local connection uses Unix domain sockets
The database server listens on port 5432
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 psql
command.
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:
Note
If this command fails with an error message saying that the database does not exist, it is because you did not create a database named after your login name in step 3. That's fine; just add the --dbname
option with an existing database name such as --dbname template1
.
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.
Note
This is also something to keep in mind if you are using a service such as Travis for continuous integration, and your test scripts need to perform some git merges: you have to provide a dummy name and e-mail for the merging to succeed.
Downloading the Odoo source code
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.
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.py
script with the following command-line arguments:
-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.
If you are using a database user with a database login 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
: 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.