Download code from GitHub
Before we dive into Odoo development, we need to set up our development environment and learn the basic administration tasks for it.
In this chapter, we will learn how to set up the work environment, where we will later build our Odoo applications. We will learn how to set up a Debian or Ubuntu system to host the development server instances and how to install Odoo from the GitHub source code. Then, we will learn how to set up file sharing with Samba, which will allow us to work on Odoo files from a workstation running Windows or any other operating system.
Odoo is built using the Python programming language, and it uses the PostgreSQL database for data storage; these are the two main requirements of an Odoo host. To run Odoo from the source, we will first need to install the Python libraries it depends on. The Odoo source code can then be downloaded from GitHub. While we can download a ZIP file or tarball, we will see that it's better if we get the sources using the Git version control application; it'll help us to have it installed on our Odoo host as well.
A Debian/Ubuntu system is recommended for the Odoo server. You will still be able to work from your favorite desktop system, be it Windows, Mac, or Linux.
Odoo can run on a variety of operating systems, so why pick Debian at the expense of other operating systems? Because Debian is considered the reference deployment platform by the Odoo team; it has the best support. It will be easier to find help and additional resources if we work with Debian/Ubuntu.
It's also the platform that the majority of developers work on and where most deployments are rolled out. So, inevitably, Odoo developers are expected to be comfortable with the Debian/Ubuntu platform. Even if you're from a Windows background, it will be important that you have some knowledge about it.
In this chapter, you will learn how to set up and work with Odoo hosted on a Debian-based system, using only the command line. For those at home with a Windows system, we will cover how to set up a virtual machine to host the Odoo server. As a bonus, the techniques you will learn here will also allow you to manage Odoo in cloud servers, where your only access will be through Secure Shell (SSH).
Note
Keep in mind that these instructions are intended to set up a new system for development. If you want to try some of them in an existing system, always take a backup ahead of time in order to be able to restore it in case something goes wrong.
As explained earlier, we will need a Debian-based host for our Odoo server. If these are your first steps with Linux, you may like to note that Ubuntu is a Debian-based Linux distribution, so they are very similar.
Odoo is guaranteed to work with the current stable version of Debian or Ubuntu. At the time of writing, these are Debian 8 "Jessie" and Ubuntu 16.04.1 LTS (Xenial Xerus). Both ship with Python 2.7, which is necessary to run Odoo. It is worth saying that Odoo does not support Python 3 yet, so Python 2 is required.
If you are already running Ubuntu or another Debian-based distribution, you're set; this can also be used as a host for Odoo.
For the Windows and Mac operating systems, install Python, PostgreSQL, and all the dependencies; next, run Odoo from the source natively. However, this could prove to be a challenge, so our advice is to use a virtual machine running Debian or Ubuntu Server. You're welcome to choose your preferred virtualization software to get a working Debian system in a virtual machine.
In case you need some guidance, here is some advice regarding the virtualization software. There are several options, such as Microsoft Hyper-V (available in some versions of recent Windows systems), Oracle VirtualBox, and VMWare Workstation Player (VMWare Fusion for Mac). The VMWare Workstation Player is probably easier to use, and free-to-use downloads can be found at https://my.vmware.com/web/vmware/downloads .
Regarding the Linux image to use, it will be more user-friendly to install Ubuntu Server than Debian. If you're beginning with Linux, I would recommend that you try a ready-to-use image. TurnKey Linux provides easy-to-use preinstalled images in several formats, including ISO. The ISO format will work with any virtualization software you choose, even on a bare-metal machine you might have. A good option might be the LAPP image, which includes Python and PostgreSQL, and can be found at http://www.turnkeylinux.org/lapp .
Once installed and booted, you should be able to log in to a command-line shell.
If you are logging in using the superuser root account, your first task should be to create a normal user account to use for your work, since it's considered bad practice to work as root. In particular, the Odoo server will refuse to run if you start it as the root.
If you are using Ubuntu, you probably won't need this since the installation process must have already guided you through the creation of a user.
First, make sure sudo is installed. Our work user will need it. If logged in as the root, execute the following commands:
# apt-get update && apt-get upgrade # Install system updates # apt-get install sudo # Make sure 'sudo' is installed
The next set of commands will create an odoo user:
# useradd -m -g sudo -s /bin/bash odoo # Create an 'odoo' user with sudo powers # passwd odoo # Ask and set a password for the new user
You can change odoo to whatever username you may want. The -m option ensures its home directory is created. The -g sudo option adds it to the sudoers list so it can run commands as the root. The -s /bin/bash option sets the default shell to bash, which is nicer to use than the default sh.
Now we can log in as the new user and set up Odoo.
Ready-to-install Odoo packages can be found at
nightly.odoo.com
, available as Windows (.exe), Debian (.deb), CentOS (.rpm), and source code tarballs (.tar.gz).
As developers, we will prefer installing them directly from the GitHub repository. This will end up giving us more control over versions and updates.
To keep things tidy, let's work in a /odoo-dev directory inside our home directory.
Note
Throughout the book, we will assume that /odoo-dev is the directory where your Odoo server is installed.
First, make sure you are logged in as the user we created now or during the installation process, not as the root. Assuming your user is odoo, confirm it with the following command:
$ whoami odoo $ echo $HOME /home/odoo
Now we can use this script. It shows us how to install Odoo from the source into a Debian/Ubuntu system.
First, install the basic dependencies to get us started:
$ sudo apt-get update && sudo apt-get upgrade #Install system updates $ sudo apt-get install git # Install Git $ sudo apt-get install npm # Install NodeJs and its package manager $ sudo ln -s /usr/bin/nodejs /usr/bin/node # call node runs nodejs $ sudo npm install -g less less-plugin-clean-css #Install less compiler
Starting from version 9.0, the Odoo web client requires the less CSS preprocessor to be installed in the system, in order for web pages to be rendered correctly. To install this, we need Node.js and npm.
Next, we need to get the Odoo source code and install all its dependencies. The Odoo source code includes an utility script, inside the odoo/setup/ directory, to help us install the required dependencies in a Debian/Ubuntu system:
$ mkdir ~/odoo-dev # Create a directory to work in $ cd ~/odoo-dev # Go into our work directory $ git clone https://github.com/odoo/odoo.git -b 10.0 --depth=1 # Get Odoo source code $ ./odoo/setup/setup_dev.py setup_deps # Installs Odoo system dependencies $ ./odoo/setup/setup_dev.py setup_pg # Installs PostgreSQL & db superuser for unix user
At the end, Odoo should be ready to use. The ~ symbol is a shortcut for our home directory (for example, /home/odoo). The git -b 10.0 option tells Git to explicitly download the 10.0 branch of Odoo. At the time of writing, this is redundant since 10.0 is the default branch; however, this may change, so it may make the script future-proof. The --depth=1 option tells Git to download only the last revision, instead of the full change history, making the download smaller and faster.
To start an Odoo server instance, just run:
$ ~/odoo-dev/odoo/odoo-bin
Tip
In Odoo 10, the odoo.py script, used in previous versions to start the server, was replaced with odoo-bin.
By default, Odoo instances listen on port 8069, so if we point a browser to http://<server-address>:8069, we will reach these instances. When we access it for the first time, it shows us an assistant to create a new database, as shown in the following screenshot:
As a developer, we will need to work with several databases, so it's more convenient to create them from the command line, so we will learn how to do this. Now press Ctrl + C in the terminal to stop the Odoo server and get back to the command prompt.
To be able to create a new database, your user must be a PostgreSQL superuser. The following command creates a PostgreSQL superuser for the current Unix user:
$ sudo createuser --superuser $(whoami)
To create a new database, use the createdb command. Let's create a demo database:
$ createdb demo
To initialize this database with the Odoo data schema, we should run Odoo on the empty database using the -d option:
$ ~/odoo-dev/odoo/odoo-bin -d demo
This will take a couple of minutes to initialize a demo database, and it will end with an INFO log message, Modules loaded.
Note
Note that it might not be the last log message, and it can be in the last three or four lines. With this, the server will be ready to listen to client requests.
By default, this will initialize the database with demonstration data, which is often useful for development databases. To initialize a database without demonstration data, add the
--without-demo-data=all option to the command.
Now open http://<server-name>:8069 with your browser to be presented with the login screen. If you don't know your server name, type the hostname command in the terminal in order to find it or the ifconfig command to find the IP address.
If you are hosting Odoo in a virtual machine, you might need to set some network configurations to be able to access it from your host system. The simplest solution is to change the virtual machine network type from NAT to Bridged. With this, instead of sharing the host IP address, the guest virtual machine will have its own IP address. It's also possible to use NAT, but that requires you to configure port forwarding so your system knows that some ports, such as 8069, should be handled by the virtual machine. In case you're having trouble, hopefully these details will help you find relevant information in the documentation for your chosen virtualization software.
The default administrator account is admin with its password admin. Upon login, you are presented with the Apps menu, displaying the available applications:
Whenever you want to stop the Odoo server instance and return to the command line, press Ctrl + C in the bash prompt. Pressing the up arrow key will bring you the previous shell command, so it's a quick way to start Odoo again with the same options. The Ctrl + C keys followed by the up arrow key and Enter is a frequently used combination to restart the Odoo server during development.
We've seen how to create and initialize new Odoo databases from the command line. There are more commands worth knowing for managing databases.
We already know how to use the createdb command to create empty databases, but it can also create a new database by copying an existing one, using the --template option.
Make sure your Odoo instance is stopped and you have no other connection open on the demo database we just created, then run this:
$ createdb --template=demo demo-test
In fact, every time we create a database, a template is used. If none is specified, a predefined one called template1 is used.
To list the existing databases in your system, use the PostgreSQL psql utility with the -l option:
$ psql -l
Running it will list the two databases we have created so far: demo and demo-test. The list will also display the encoding used in each database. The default is UTF-8, which is the encoding needed for Odoo databases.
To remove a database you no longer need (or want to recreate) to use the dropdb command:
$ dropdb demo-test
Now you know the basics to work with databases. To learn more about PostgreSQL, refer to the official documentation at http://www.postgresql.org/docs/ .
At the time of writing, Odoo's latest stable version is version 10, marked on GitHub as branch 10.0. This is the version we will work with throughout the book.
Note
It's important to note that Odoo databases are incompatible between Odoo major versions. This means that if you run an Odoo 10 server against a database created for a previous major version of Odoo, it won't work.
Non-trivial migration work is needed before a database can be used with a later version of the product.
The same is true for addon modules: as a general rule, an addon module developed for an Odoo major version will not work with other versions. When downloading a community module from the web, make sure it targets the Odoo version you are using.
On the other hand, major releases (9.0, 10.0) are expected to receive frequent updates, but these should be mostly bug fixes. They are assured to be "API stable", meaning model data structures and view element identifiers will remain stable. This is important because it means there will be no risk of custom modules breaking due to incompatible changes in the upstream core modules.
Be warned that the version in the master branch will result in the next major stable version, but until then, it's not "API stable" and you should not use it to build custom modules. Doing so is like moving on quicksand: you can't be sure when some changes will be introduced that will break your custom module.
The Odoo server supports quite a few other options. We can check all the available options with --help:
$ ./odoo-bin --help
We will review some of the most important options in the following sections. Let's start by looking at how the currently active options can be saved in a configuration file.
Most of the options can be saved in a configuration file. By default, Odoo will use the .odoorc file in your home directory. In Linux systems its default location is in the home directory ($HOME), and in the Windows distribution it is in the same directory as the executable used to launch Odoo.
Note
In previous Odoo/OpenERP versions, the name for the default configuration file was .openerp-serverrc. For backward compatibility, Odoo 10 will still use this if it's present and no .odoorc file is found.
On a clean install, the .odoorc configuration file is not automatically created. We should use the --save option to create the default configuration file, if it doesn't exist yet, and store the current instance configuration into it:
$ ~/odoo-dev/odoo/odoo-bin --save --stop-after-init #save configuration to file
Here, we also used the --stop-after-init option to stop the server after it finishes its actions. This option is often used when running tests or asking to run a module upgrade to check whether it is installed correctly.
Now we can inspect what was saved in this default configuration file:
$ more ~/.odoorc # show the configuration file
This will show all the configuration options available with their default values. Editing them will be effective the next time you start an Odoo instance. Type q to quit and go back to the prompt.
We can also choose to use a specific configuration file, using the --conf=<filepath> option. Configuration files don't need to have all those options you've just seen. Only the ones that actually change a default value need to be there.
The --xmlrpc-port=<port> command option allows us to change the listening port of a server instance from the default 8069. This can be used to run more than one instance at the same time, on the same machine.
Let's try this out. Open two terminal windows. On the first, run this:
$ ~/odoo-dev/odoo/odoo-bin --xmlrpc-port=8070
Run the following command on the second terminal:
$ ~/odoo-dev/odoo/odoo-bin --xmlrpc-port=8071
There you go: two Odoo instances on the same server listening on different ports! The two instances can use the same or different databases, depending on the configuration parameters used. And the two could be running the same or different versions of Odoo.
When developing with Odoo, it is frequent to work with several databases, and sometimes even with different Odoo versions. Stopping and starting different server instances on the same port, and switching between different databases, can cause web client sessions to behave improperly.
Accessing our instance using a browser window running in private mode can help avoiding some of these problems.
Another good practice is to enable a database filter on the server instance to ensure that it only allows requests for the database we want to work with, ignoring all others. This is done with the --db-filter option. It accepts a regular expression to be used as a filter for the valid database names. To match an exact name, the expression should begin with a ^ and end with $.
For example, to allow only the demo database we would use this command:
$ ~/odoo-dev/odoo/odoo-bin --db-filter=^demo$
The --log-level option allows us to set the log verbosity. This can be very useful to understand what is going on in the server. For example, to enable the debug log level, use
--log-level=debug option.
The following log levels can be particularly interesting:
debug_sqlto inspect SQL queries generated by the serverdebug_rpcto detail the requests received by the serverdebug_rpc_answerto detail the responses sent by the server
By default, the log output is directed to standard output (your console screen), but it can be directed to a log file with the --logfile=<filepath> option.
Finally, the --dev=all option will bring up the Python debugger (pdb) when an exception is raised. It's useful to do a post-mortem analysis of a server error. Note that it doesn't have any effect on the logger verbosity. More details on the Python debugger commands can be found at
https://docs.python.org/2/library/pdb.html#debugger-commands
.
You may be running Odoo with a Debian/Ubuntu system either in a local virtual machine or in a server over the network. But you may prefer to do the development work at your personal workstation, using your favorite text editor or IDE. This may frequently be the case for developers working from Windows workstations. But it also may be the case for Linux users who need to work on an Odoo server over the local network.
A solution for this is to enable file sharing in the Odoo host so that files are made easy for editing from our workstation. For Odoo server operations, such as a server restart, we can use an SSH shell (such as PuTTY on Windows) alongside our favorite editor.
Sooner or later, we will need to edit files from the shell command line. In many Debian systems, the default text editor is vi. If you're not comfortable with it, you probably could use a friendlier alternative. In Ubuntu systems, the default text editor is nano. You might prefer it since it's easier to use. In case it's not available in your server, it can be installed with:
$ sudo apt-get install nano
In the following sections, we will assume nano as the preferred editor. If you prefer any other editor, feel free to adapt the commands accordingly.
The Samba service helps make Linux file-sharing services compatible with Microsoft Windows systems. We can install it on our Debian/Ubuntu server with this command:
$ sudo apt-get install samba samba-common-bin
The samba package installs the file-sharing services, and the samba-common-bin package is needed for the smbpasswd tool. By default, users allowed to access shared files need to be registered with it. We need to register our user, odoo for example, and set a password for its file share access:
$ sudo smbpasswd -a odoo
After this, we will be asked for a password to use to access the shared directory, and the odoo user will be able to access shared files for its home directory, although it will be read only. We want to have write access, so we need to edit the Samba configuration file to change it as follows:
$ sudo nano /etc/samba/smb.conf
In the configuration file, look for the [homes] section. Edit its configuration lines so that they match the settings as follows:
[homes]
comment = Home Directories
browseable = yes
read only = no
create mask = 0640
directory mask = 0750
For the configuration changes to take effect, restart the service:
$ sudo /etc/init.d/smbd restart
Tip
Downloading the example code
You can download the example code files for all Packt books you have purchased from your account at http://www.packtpub.com . If you purchased this book from elsewhere, you can visit http://www.packtpub.com/support and register to have the files e-mailed directly to you.
To access the files from Windows, we can map a network drive for the path \\<my-server-name>\odoo using the specific username and password defined with smbpasswd. When trying to log in with the odoo user, you might encounter trouble with Windows adding the computer's domain to the username (for example, MYPC\odoo). To avoid this, use an empty domain by prepending a \ character to the login (for example, \odoo):
If we now open the mapped drive with Windows Explorer, we will be able to access and edit the contents of the odoo user's home directory:
Odoo includes a couple of tools that are very helpful for developers, and we will make use of them throughout the book. They are technical features and the developer mode. These are disabled by default, so this is a good moment to learn how to enable them.
The developer tools provide advanced server configuration and features. These include a debug menu in the top menu bar along with additional menu options in the Settings menu, in particular the Technical menu.
These tools come disabled by default, and to enable them, we need to log in as admin. In the top menu bar, select the Settings menu. At the bottom-right, below the Odoo version, you will find two options to enable the developer mode; any of them will enable the Debug and Technical menus. The second option, Activate the developer mode (with assets), also disables the minification of JavaScript and CSS used by the web client, making it easier to debug client-side behavior:
After that, the page is reloaded and you should see a bug icon in the top menu bar, just before the session user avatar and name providing the debug mode options. And in the Settings option in the top menu, we should see a new Technical menu section giving access to many Odoo instance internals:
Making new modules available in an Odoo instance so they can be installed is something that newcomers to Odoo frequently find confusing. But it doesn't have to be so, so let's demystify it.
There are many Odoo modules available on the Internet. The Odoo apps store at apps.odoo.com is a catalogue of modules that can be downloaded and installed on your system. The Odoo Community Association (OCA) coordinates community contributions and maintains quite a few module repositories on GitHub at https://github.com/OCA/ .
To add a module to an Odoo installation, we could just copy it into the addons directory alongside the official modules. In our case, the addons directory is at ~/odoo-dev/odoo/addons/. This might not be the best option for us since our Odoo installation is based on a version-controlled code repository, and we will want to keep it synchronized with the GitHub repository.
Fortunately, we can use additional locations for modules so we can keep our custom modules in a different directory, without having them mixed with the official ones.
As an example, we will download the code from this book, available in GitHub, and make those addon modules available in our Odoo installation.
To get the source code from GitHub, run the following commands:
$ cd ~/odoo-dev $ git clone https://github.com/dreispt/todo_app.git -b 10.0
We used the -b option to make sure we are downloading the modules for the 10.0 version.
After this, we will have a new /todo_app directory alongside the /odoo directory, containing the modules. Now we need to let Odoo know about this new module directory.
The Odoo server has a configuration option called addons_path to set where the server should look for modules. By default, this points to the /addons directory, where the Odoo server is running.
We can provide not only one, but a list of directories where modules can be found. This allows us to keep our custom modules in a different directory, without having them mixed with the official addons.
Let's start the server with an addons path that includes our new module directory:
$ cd ~/odoo-dev/odoo $ ./odoo-bin -d demo --addons-path="../todo_app,./addons"
If you look closer at the server log, you will notice a line reporting the addons path in use: INFO? odoo: addons paths: [...]. Confirm that it contains our todo_app directory.
We still need to ask Odoo to update its module list before these new modules are made available for installation.
For this, we need developer mode enabled, since it provides the Update Apps List menu option. It can be found in the Apps top menu.
After updating the modules list, we can confirm the new modules are available for installation. Use the Apps menu option to see the list of local modules. Search for todo and you should see the new modules made available.
Note that the second App Store menu option displays the module list from Odoo apps store instead of your local modules:
In this chapter, we learned how to set up a Debian system to host Odoo and install it from the GitHub source code. We also learned how to create Odoo databases and run Odoo instances. To allow developers to use their favorite tools in their personal workstation, we explained how to configure file sharing in the Odoo host.
We should now have a functioning Odoo environment to work with and be comfortable with managing databases and instances.
With this in place, we're ready to go straight into action. In the next chapter, we will create our first Odoo module from scratch and understand the main elements it involves.
So let's get started!
