Preparing a basic work environment

The first thing we need is to have an Odoo instance that we can use for our learning project.

For the purpose of this chapter, we just need a running Odoo instance, and the particular installation method is not relevant. To quickly get up and running, we can use a prepackaged Odoo distribution, or even just use an Odoo SaaS trial database (https://www.odoo.com/).

Using an Odoo SaaS trial database

This can be the simplest way to get started. No need to actually install anything for now, just go to https://www.odoo.com/ and create a free trial database. The Odoo Cloud software as a service (SaaS) is based on the enterprise edition (EE), with additional, exclusive, intermediate version releases. Other than the trial, at the time of writing it also offers a free plan: databases with only one application installed are free to use. The SaaS service runs vanilla Odoo enterprise and custom modules are not allowed. For cases where customizations are needed, the Odoo.sh service can be used, providing a full-featured development platform to customize and host solutions based on Odoo enterprise. See https://www.odoo.sh/ for more information.

Changes in Odoo 12
In previous Odoo versions, the menu structure of the web client was significantly different between the CE and EE. In Odoo 12, the menus in both editions follow a similar structure.

To create a new database on the Odoo Cloud SaaS, you will probably be asked to select a starting application. No specific application is required to follow this chapter, but if you're unsure on what to pick, customer relationship management (CRM) would be fine.

Also worthy of note is that the EE, on the Odoo SaaS, has the Odoo Studio application builder available. We won't be using it, since it is not available for the CE, which is used as a reference in this book. Odoo Studio provides a user-friendly user interface for the developer features introduced in this chapter, along with a few extra features, such as the ability to export the customizations made in a convenient module package. But the main capabilities are similar to what we can get by using the basic developer mode.

Installing Odoo on Windows

Ready-to-install Odoo packages can be found at https://download.odoo.com, available for any of the currently supported Odoo versions, as well as for the master branch (the latest development version). You can find the Windows (.exe) installers, alongside the Debian (.deb) and CentOS (.rpm) packages.

To install on Windows, find the latest .exe build in the nightly directory and install it. The all-in-one installation is straightforward, as it provides all that you will need to run Odoo; Python 3, a PostgreSQL database server, the Odoo server, and all Odoo additional dependencies. A Windows service is also created to automatically start the Odoo and PostgreSQL services when your machine starts.

Installing Odoo using Docker containers

Docker provides a convenient multi-platform solution to run applications. It can be used to run applications on macOS, Linux, and Windows. The container technology is simple to use and resource-efficient when compared to classic virtual machines.

You must first have Docker installed in your system. The Docker CE is free of charge, and can be downloaded from https://www.docker.com. It's worth referring to Docker's website for the latest installation details.

In particular, keep in mind that virtualization must be enabled in your BIOS setup. Also, the Docker CE for Windows requires Hyper-V, only available in Windows 10 Enterprise or Education releases (see https://docs.docker.com/docker-for-windows/install), and Docker CE for mac requires OS X El Capitan 10.11 and newer macOS releases.

For other Windows and macOS versions, you should instead install Docker Toolbox, available at https://docs.docker.com/toolbox/overview. Docker Toolbox bundles VirtualBox and provides a preconfigured shell that should be used as the command-line environment to operate Docker containers.

The Odoo Docker images are available in the Docker store at https://store.docker.com/images/odoo. There, we can find the versions available, and the basic instructions to get started with them. To run Odoo, we will need two Docker containers, one for the PostgreSQL database, and another for the Odoo server.

The installation and operation is done from a command-line window. To install the PostgreSQL Docker container, run this:

$ docker run -d -e POSTGRES_USER=odoo -e POSTGRES_PASSWORD=odoo --name db postgres:10

It will download the latest PostgreSQL image from the internet, and start a container for it running as a background job.

Next, install and run the Odoo server container, linking it to the PostgreSQL container we just started, and exposing it on port 8069:

$ docker run -t -p 8069:8069 --name odoo --link db:db odoo:12.0 -d odoo12

With this, you will see the live Odoo server log in your terminal window, and can access the Odoo instance by opening http://localhost:8069 with your favorite web browser.

The Odoo server can fail to start if port 8069 is already in use, for example, by an already running Odoo server. In this case, you might look for and stop the running service (for example, by looking at the list of running services), or try to start this Odoo server on a different port by changing the -p option. For example, to use port 8070, use -p 8070:8069. In that case, you probably also want to change -d <dbname> to set the database name that instance should use.

There are a few basic commands you should know to help manage these Docker containers:

• docker stop <name> stops a container
• docker start <name> starts a container
• docker start -a <name> starts a container, and attaches the output, such as the server log, to the terminal window
• docker attach <name> reattaches a container's output to the current terminal window
• docker ps lists the current Docker containers

These are the basic commands needed to operate our Docker containers.

In case you get in trouble running the containers, here is a recipe to start over:

$ docker container stop db
$ docker container rm db
$ docker container stop odoo
$ docker container rm odoo

The Docker technology has more potential, and it might be interesting to learn more about it. The Docker website has good learning documentation. A good place to get started is https://www.docker.com/get-started.

Other installation options

It is worth noting that installation packages are also available for Debian-based (such as Ubuntu) and Red Hat-based (such as CentOS and Fedora) Linux systems.

We won't be able to go into much detail on how to install them, but if you are familiar with Debian or Red Hat, this is also an option to consider. The installation packages are available from https://download.odoo.com, and the official documentation provides a good explanation on how to install them at https://www.odoo.com/documentation/master/setup/install.html.

Regarding the source code installation, it is the most complex, but also the most versatile of the installation alternatives, and it will be explained in detail in Chapter 2, Preparing the Development Environment.

Creating a work database

By now, we should have a PostgreSQL database server and an Odoo server instance running. We now need to create an Odoo database before we can start working on our project.

If you installed Odoo locally, keeping the default configuration options, the server should be available at http://localhost:8069. When we access it for the first time, since there are no Odoo databases available yet, we should see an assistant to create a new database:

The information you need to provide is the following:

• The Database Name is the identifier name to use for this database. You can have several databases available on the same server.
• Email is the login username to use for the special Administrator super user. It doesn't have to be an actual email address.
• Password is your secret password to log in as the Administrator.
• Language is the default language to use for the database.
• Country is the country set in the database's company data. It is optional, and is relevant for localization features in some apps, such as Invoicing and Accounting.
• The load demonstration data checkbox allows you to create the database with demonstration data, instead of creating a clean database. This is usually desirable for development and test environments.

A master password field might also be asked for, if one was set in the Odoo server configuration. This allows you to prevent unauthorized people from performing these administrative tasks. But by default it is not set, so you probably won't be asked for it.

After pushing the create database button, the new database will be bootstrapped, a process that can take a couple of minutes, and once ready you are redirected to the login screen.

The login screen has a manage databases link at the bottom to access the database manager. There, you can see the list of available databases; back up, duplicate, or delete them; and also create new ones. It can also be directly accessed at http://localhost:8069/web/database/manager.

The database manager allows for privileged administration operations, and by default is enabled and unprotected. While it is a convenient feature for development, it can be a security risk for databases that have real data, even if they are test or development environments. Consider setting a strong master password, or even better, disabling it. This is done by setting list_db = False in the server configuration file.

Now that we have an Odoo instance and a database to work with, the next step is to enable the developer mode, providing the tools we need to implement our project.

Enabling the developer mode

To implement our project, we need the tools provided by the developer mode, which needs to be enabled.

The developer mode allows us to customize Odoo apps directly from the user interface. This has the advantage of being a rather quick way to make changes and add features. It can be used from small modifications, such as adding a field, to larger customizations, such as creating an application with several models, views, and menu items.

These customizations done directly from the user interface have some limitations, when compared to the customizations done with programming tools, covered throughout the rest of the book. For example, you can't add or extend the default ORM methods (although in some cases automated actions can be enough to provide an alternative to that). They also can't be easily integrated into a structured development workflow, which typically involves version control, automated tests, and deploying into several environments, such as quality assurance, pre-production, and production.

Here, we will be using the developer mode features mainly as a way to introduce how application configuration data is organized in the Odoo framework, and how the developer mode can be leveraged for simple customizations, or to quickly outline or prototype the solution to implement.

To enable the developer mode, go to Settings | Dashboard, and in the lower-right corner you should find the Activate the developer mode link. Clicking on it enables the developer mode features for this browser window. For Odoo 9.0 and before, the developer mode is activated in the About dialog window, available from the User menu, in the upper-right corner of the web client. 

We also have available an Activate the developer mode (with assets) option. What it does is prevent web client asset minification. It is useful to debug the web client itself, at the expense of making the navigation a little slower.

For faster load times, the web client minifies the JavaScript and CSS assets into compact files. Unfortunately, that makes web client debugging nearly impossible. The Activate the developer mode (with assets) option prevents this minification and loads the web assets in individual, non-minified files.

The developer mode can also be enabled by tinkering directly with the current URL, so that you don't have to leave your current screen to open settings. Edit the URL to change the .../web#... part to insert .../web?debug#... or .../web?debug=assets#.... For example, http://localhost:8069/web#home would be changed to http://localhost_8069/web?debug#home.

Although there is no link to enable it, the frontend framework also supports the debug flag. To disable asset minification in a frontend web page, add ?debug=assets to the corresponding URL. Take note that the option will probably not persist when navigating through links to other frontend pages.

There are browser extensions available for both Firefox and Chrome that provide a convenient button to enable and disable the developer mode. Look for "Odoo debug" in Firefox add-ons or the Chrome store.

Once the developer mode is enabled, we will see two additional menus available:

1. The Developer Tools menu, the bug icon on the right-hand side of the top menu bar, just before the username and avatar
2. The Technical menu item, in the Settings application

The following screenshot shows the two additional menus:

The developer mode also enables additional information on form fields; when pausing the mouse pointer over a field, a tooltip will display technical information on it.

We will be using the most relevant developer mode features in the next sections.