anybox-odoo-host

Warning

This 2.x version is the Debian 8 (Jessie) version. It does not provide an automatic upgrade path from the 1.x versions (meant for Debian ≤ 7).

Introduction

anybox-odoo-host is a package for the Debian GNU/Linux distribution that provides a standardized structure and utilities to host one or several Odoo (formerly OpenERP) instances.

It relies heavily on Anybox’s Odoo and OpenERP recipes. Each instance’s software is expected to be packaged before hand with the recipe’s freeze/extract commands, and provided as single archive file (various formats and download options are supported).

Odoo/OpenERP instances are isolated as system users, and processes are handled as user-level systemd services.

Installation

Supported OpenERP/Odoo versions: 6.0 through 8.0 Supported Debian versions: 8 (Jessie)

The simplest is to hook to Anybox Debian sources and use the following combination:

deb http://apt.anybox.fr/openerp common main
deb http://apt.anybox.fr/openerp anybox contrib
deb http://apt.anybox.fr/openerp anybox-jessie contrib

Packages undergoing evaluation will be uploaded to the testing variants:

deb http://apt.anybox.fr/openerp common main
deb http://apt.anybox.fr/openerp anybox-testing contrib
deb http://apt.anybox.fr/openerp anybox-jessie-testing contrib

Architecture

Here is a example diagram for a server with two Odoo 8 instances, the rightmost one having an additional service (Odoo Connector for Magento).

  • the web front-end (reverse proxy) is optional, and defaults to Nginx. Apache2 is also supported.
  • In the default installation, the PostgreSQL server is local, with client connections through Unix Domain socket (peer authentication), but there is support for remote PostgreSQL servers as well. Any PostgreSQL version for apt.postgresql.org can be used.
  • Database servers can be in high-availability, with PostgreSQL replication (WAL streaming with hot standbies). These setups are supported by helpers and general awareness of upgrade scripts of this possibility
  • each instance has his own system user and a PostgreSQL role, with databases creation rights if the database server is local.
  • Odoo processes are registered and handled as user-level systemd services; you may think of the dashed area as the instance’s systemd or the user slice (CGroup)
  • Each buildout produces the running and upgrade commands that gets referenced as services.
  • The templating system allows to handle more complex cases such as the other.service in the diagram (just a silly naming example) easily.
  • Nothing that you can read in the diagram is hardcoded, everything is configurable, with help from the installation commmands. The latter provide a starting point that is intended to be managed afterwards by the system administrators, with their tools of choice.

Commands

All commands related to this package are prefixed with anybox-, to avoid overlapping with other tools we would not be aware of.

Most are written in Python and accept the --help argument:

anybox-odoo-deploy --help

Most of conventions and coincidences are nothing but default values for the numerous options. These default values can also be specified in a system-wide configuration file <aoh_conffiles_main>.

Note

According to the general Debian conventions, some scripts are located in /usr/sbin. Especially if only root can launch them.

Frequent commands

userctl/anybox-odoo-instancectl:

Manage instance services, to be executed as the instance system user.

On most systems it can be spelled simply userctl, but the full unambiguous name is actually anybox-odoo-instancectl.

See its separate man page.

For details on Odoo services organisation, see also User-level services and target (part of anybox-odoo-deploy man page).

anybox-odoo-deploy:

The main deployment workhorse. Downloads, extracts, installs buildout archives and create/upgrade databases. In this Jessie version, it also initiates the instance’s services and start/stop them as needed.

See its separate man page for explanations.

anybox-odoo-ls-instances:
Useful introspection script with configurable output. Produces more info if run as root (notably, instances ports).
service postgresql (Debian standard):
monitor a local PostgreSQL. Use reload to apply configuration change(s) without taking risks: most of postgresql.conf and pg_hba.conf settings can be changed with a simple reload. Other settings are described in the comments

Instance initialisation commands

Without being rare these commands are meant to be executed only one time for each project.

anybox-odoo-add-instance-user:
create the system user and the PostgreSQL role for an instance. Also takes care of systemd initializations.
anybox-odoo-vhost-init:
create a reverse proxy for an instance in a local general purpose web server. Takes care of certificates for HTTPS.

Rare or automatic commands

anybox-odoo-rm-instance:
it can be useful sometimes. Don’t worry: there are lots of confirmation steps.
anybox-odoo-allctl:
used to stop/start all Odoo instances in one shot
anybox-odoo-rotating-backup:
take a database backup and optionally keep a fixed number of active snapshots. See Local backups production
anybox-rsync-pg-backups:
(For local PostgreSQL servers only) To ship backups from primary to replicate in cases.
anybox-pg-init-slave:
(For local PostgreSQL servers only) Very dangerous delete all databases and initiate PostgreSQL cluster as replicate from a primary.

Configuration files

Main file

The main configuration file is /etc/anybox-odoo-host.cfg. This is a YAML file that must evaluate as a dict. It holds some transversal parameters, and also system-wide defauts for the commands that support it (anybox-odoo-deploy at the time of this writing).

Instance configuration files

~INSTANCE/`hostname`.cfg:
buildout configuration file which expresses the specificities of this server with respect to other servers where potentially the same buildout could be deployed: ports, DB accesses, process options…
~INSTANCE/.config/systemd/user/:
standard location for user-level systemd units (services, targets…)

Templates

The instance configuration files are initialized by templates which are located in /etc/odoo/. You may alter them, and in some cases make you own.

Logs

buildouts:
~INSTANCE/log, but that may be changed through the local buildout configuration file, and ultimately comes with the default buildout templates shipping with anybox-odoo-host.

Backups

They are located in /var/backups/postgresql. This directory has special ACL so that customer’s system user can produces dumps, to be separated and to be accessible by the backup user.

Warning

Never user chmod on dumps except if we know how to monitor and check ACL (cf man getfacl, man setfactl, man acl).

For high-availability pairs servers case, anybox-rsync-pg-backups is used to send backups from master to slave

Local backups production

The anybox-odoo-rotating-backup script does:

  • produce database backup in /var/backup/postgresql (thanks to permissions and ACLs set up by anybox-odoo-host)
  • limit local backups number
  • optionally, inform Shinken backups are done
  • optionally, restore freshly backuped database including date in the name, this is the rotative part
  • nothing if the server is a slave for the Postgres replication !

anybox-odoo-rotating-backup is started by customer’s system user cron, as initialised by anybox-odoo-deploye:

.. _anybox_rsync_pg_backups:

Backups shipping

The anybox-rsync-pg-backups script uses a dedicated SSH key and it started by a cron from /etc/cron.d, which next informs Shinken that all was done correctly.

Here is a typical example, showing Shinken passive notifications:

gracinet@aoh1:~$ sudo cat /etc/cron.d/anybox-rsync-pg-backups
08 01 * * * backup /usr/bin/anybox-rsync-pg-backups aoh2.anybox.fr --key-file ~/.ssh/id_aoh1_backup --shinken-enable --shinken-service 'Pull Backups' --shinken-host aoh1 --logging-level WARNING

Note

anybox-odoo-host also prepares the cron in /etc/cron.d/, to uncomment and to configure with the right hostname.

Instance directory structure

Example

Here’s the listing of files and directory in a real-life instance:

instance@server2:~ $ ls -l
total 401308
lrwxrwxrwx  1 customer_example openerp       19 Sep 30 10:16 current_buildout -> project-example-openerp-1.1b5-2
drwxr-xr-x  2 customer_example openerp     4096 Sep 30 10:16 log
drwxr-xr-x  2 customer_example openerp     4096 Sep 30 10:16 dumps
-rw-r--r--  1 customer_example openerp      631 Jul 26 11:56 server2.cfg
drwx------ 24 customer_example openerp     4096 Sep 27 08:40 project-example-openerp-1.1b4-2
drwx------ 24 customer_example openerp     4096 Sep 30 10:17 project-example-openerp-1.1b5-2
drwxr-xr-x  2 customer_example openerp     4096 Sep  3 10:54 tarballs

current_buildout

The subdirectory current_buildout is a symbolic link to the last delivery (results of archive extraction)

It allows to reconcile two requirements:

  • path stability, particularly in the user-level services
  • quick switch from one version to another, especially useful to rollback a failed deployment

current_buildout is the default value picked by anybox-odoo-deploy.

`hostname`.cfg

In the previous example, it’s server2.cfg. This file contains the local configuration thanks to the extends of the delivered file (generally release.cfg, but you can change it)

Jinja2 Templating

The scripts that create configuration files in anybox-odoo-host use the Jinja2 templating engine.

Jinja2 is initialized with a SandboxedEnvironment using the FileSystemLoader and StrictUndefined to trap missing values and report them to the user.

See the Jinja2 reference documentation at http://jinja.pocoo.org/docs/dev/api/ for explanations about these.

The scripts will pass only relevant values to the template, according to the execution context. To check for existence of a value from within the template, do:

{% if the_value is defined %}

(is_defined this is one of the default Environment tests, see http://jinja.pocoo.org/docs/dev/api/#jinja2.Environment.tests)