Creating An OpenGroupware Coils Development Instance

These instructions provide a simple recipe to create an OpenGroupware Coils development instance.  Previously creating an instance has admittedly been a bit tedious; but in the last couple of weeks an effort has been made to simplify deployment.

Aside: Always see the Administrator's Guide (WMOGAG) for complete documentation.  Ask questions on the coils-project mailing list.

Step#1) Provisioning dependencies

Both PostgreSQL and RabbitMQ must be provisioned on the host as well as the dependencies of the required Python modules.  The dependencies are easily met on either CentOS6 (with RPMForge enabled) and openSUSE 12.1.  Installing PostgreSQL and RabbitMQ should be performed using the standard methods.

CentOS6  rpm --import http://apt.sw.be/RPM-GPG-KEY.dag.txt
  rpm -Uvh
    http://packages.sw.be/rpmforge-release/rpmforge-release-0.5.2-2.el6.rf.x86_64.rpm
  yum install python python-ldap  python-devel python-setuptools gcc \
              make binutils libxml2-devel libxslt-devel libyaml \
              libyaml-devel postgresql-devel postgresql-libs cmake \
              gcc-c++ freetype-devel libpng-devel libjpeg-devel \
              libsmbclient-devel

openSUSE
  zypper in python python-ldap  python-devel python-Distutils2 gcc make \
            binutils libxml2-devel libxslt-devel libyaml libyaml-devel \
            postgresql-devel postgresql cmake gcc-c++ freetype2-devel \
           libpng14-devel libjpeg62-devel libsmbclient-devel
Text: These commands will install the required system prerequisites for the required Python modules.

A simple method for installing RabbitMQ on openSUSE 12.1 is described  in the "Idjit's Guide To Installing RabbitMQ on openSUSE 12.1"

Step#1.1) Installed a compatible version of the YAJL library.


The YAJL library provides SAX like stream-processing of JSON data.  This library is required by the ijson Python module. This module is not required by OpenGroupware Coils so this step can be skipped;  but usage of this module (and thus library) are strongly recommended

curl -o yajl-1.0.11.tar.gz http://gentoo.osuosl.org/distfiles/yajl-1.0.11.tar.gz

tar xzvf yajl-1.0.11.tar.gz

cd lloyd-yajl-f4baae0/

mkdir build

cd build

cmake ..

sudo make install

sudo /sbin/ldconfig

Text: Fetching, building, and installing the YAJL library.

Step#1.2) Creating PostgreSQL role & database.

A role must be created in the PostgreSQL engine; the recommendation is to name the role "OGoDev".  Remember the password you enter for this role!

sudo -u postgres createuser --password --no-superuser --no-created --no-createrole OGoDev

Text: Creating the "OGoDev" role.

Once a role has been created a database must be created.  The default name for the OpenGroupware database is typically "OGo" but in order to disambiguate the development database(s) from a production instance the recommendation is to name the database "OGoDev?".  I prefer to make ten databases [OGoDev0, OGoDev1, ... OGoDev9] so I have several to play with - this is especially useful for testing.

sudo -u postgres createdb -E UTF-8 -O OGoDev OGoDev0

Text: Creating a database named "OGoDev0" owned by the OGoDev role.

Step#1.3) Define RabbitMQ role & vhost(s).

The OpenGroupware Coils components also need a context with which to connect to the RabbitMQ service.  Keeping to the same role naming scheme you used with PostgreSQL is helpful for keeping this straight.  Just as with PostgreSQL I prefer to define ten roles and virtual hosts [OGoDev0, OGoDev1, .... OGoDev9] so that I can switch the instance between fresh instances.  The commands listed here will create a role with a password, create an eponymous virtual host, and then grant that role full permissions over its vhost.

sudo rabbitmqctl add_user OGoDev0 {AMQPASSWORD}
sudo rabbitmqctl add_vhost OGoDev0
sudo rabbitmqctl set_permissions -p OGoDev0 OGoDev0 ".*" ".*" ".*"

Text: Creating a role and virtual host in RabbitMQ.

A RabbitMQ virtual host is a means to allow multiple services to use the same message broker service while remaining isolated from each other/

Step#2) Create the container for the development install.

virtualenv OGo

cd OGo

echo -e '\nexport PYTHONPATH="$VIRTUAL_ENV/coils/src"\n' >> bin/activate

echo -e '\nexport OGO_SERVER_ROOT="$VIRTUAL_ENV/root"\n' >> bin/activate

Text: Creating a virtualenv instance for development.

The Python module virtualenv provides a convenient means for creating a container for performing Python development.  This [virtualenv] module should be installed in the host's global Python site-packages.

For this container it is also helpful to add the Coils code checkout to the Python path [via PYTHONPATH] and the establish a server root [via OGO_SERVER_ROOT] within the development container.  This customer server root keeps file created by the instance, including configuration, confined to the development container.

Aside: If OGO_SERVER_ROOT is not defined the server root will default to "/var/lib/opengroupware.org".

Step#2) Populate the container.

Now the container needs to be activated and the required Python modules installed.  The ". bin/activate" builds the environment for the container and should be performed from the root directory of the container whenever working with the development instance.

. bin/activate

pip install lxml==2.3.4

pip install psycopg2==2.4.5

pip install pytz

pip install sqlalchemy==0.7.4

pip install xlrd==0.7.7

pip install xlwt==0.7.4

pip install pysmbc==1.0.13

pip install procname==0.3

pip install PyYAML==3.10

pip install ijson==0.8.0

pip install apscheduler==2.0.3

pip install python-dateutil==2.1
pip install vobject==0.8.1c

pip install http://effbot.org/downloads/Imaging-1.1.7.tar.gz

Text: Activating the virtualenv container and installing Python modules.

Now we are ready to checkout the OpenGroupware Coils code into the container.

Read/Write

  hg clone ssh://{YOURUSERNAME}@hg.code.sf.net/p/coils/code coils

Read-Only

  hg clone http://hg.code.sf.net/p/coils/code coils

Text: Checking out the OpenGroupware Coils code base.

Step#3) Test the development container.

The "coils-dependency-check" tool tries to load all the modules used by OpenGroupware Coils and reports success or failure.  This verifies that the Python requirements for operating an OpenGroupware Coils instance have been met.

(OGo)awilliam@workstation:~/OGo> cd coils/src

(OGo)awilliam@workstation:~/OGo/coils/src> tools/coils-dependency-check

OK: Module xlwt (XLS<2007 write support) available.

OK: Module sqlalchemy (Object Relational Modeling) available.

OK: Module coils.foundation.api.dateutil (Date & Time Arithmatic) available.

OK: Module pytz (Python Time Zone tables) available.

OK: Module xlrd (XLS<2007 read support) available.

OK: Module coils.foundation.api.vobject (vCard and vEvent parsing) available.

OK: Module lxml (SAX & DOM XML Processing) available.

OK: Module PIL (Python Imaging Library) available.

OK: Module psycopg2 (PostgreSQL RDBMS connectivity) available.

OK: Module base64 (Encode and decode Base64 data) available.

OK: Module coils.foundation.api.elementflow (Streaming XML Creation) available.

OK: Module coils.foundation.api.pypdf (Simple PDF Operations) available.

OK: Module yaml (YAML parser & serializer) available.

WARN: Module informixdb (Informix RDBMS connectivity) not available.

1 database connectivity modules found.

 * Make sure the RDBMS you intend to use for the SQLalchemy  *

 * ORM is installed and operational.                         *

1 package warnings found.

 * You are missing packages that extend the operation and    *

 * capacity of the OpenGroupware Coils service.  The service *

 * will provide core functionality but some features,        *

 * particularly in regard to OIE, may not be available. It   *

 * is recommended you install the appropriate packages.      *

Text: Run the coils-dependency-check tool to verify your Python installation.

The warning ("WARN") indicates that an optional module could not be loaded.  Warnings indicate that the service will operate but with potentially reduced functionality.  Any error ["ERROR"] means the service will fail to operate.

Step#4) Initialize the development instance.

Now that the environment is ready the Coils tools can be used to initialize and configure the instance.

(OGo)awilliam@workstation:~/OGo/coils/src> tools/coils-initialize-install  --user=awilliam --group=users --log=../../coils.log

Text: Initialize the server's installation; this create the required structure in the server's document root - in this case the value defined by $OGO_SERVER_ROOT.

(OGo)awilliam@workstation:~/OGo/coils/src> tools/coils-server-config --bootstrap

Initialized a new server defaults file.

Loaded configuration BLOB successfully.

Text: Initialize the instance's configuration with default values.

(OGo)awilliam@workstation:~/OGo/coils/src> tools/coils-server-config --directive LSConnectionDictionary --value "{'databaseName': 'OGoDev0', 'hostName': '127.0.0.1', 'password': '{SQLPASSWORD}', 'port': 5432, 'userName': 'OGoDev'}"

Text: Configure the connection to the PostgreSQL database.

(OGo)awilliam@workstation:~/OGo/coils/src> tools/coils-server-config --directive AMQConfigDictionary --value "{'hostname': '127.0.0.1', 'password': '{AMQPASSWORD}', 'port': 5672, 'username': 'OGoDev0', 'vhost': 'OGoDev0' }"

Text: Configure the connection to the RabbitMQ message broker.

(OGo)awilliam@workstation:~/OGo/coils/src> tools/coils-initialize-database --initdb --password={COILSADMINPASSWORD}

Text: Create the initial database schema and provision the administrative "ogo" account with the specified password.

Step#5) Test the instance.

A simple way to test the instance is to start just the HTTP component.

(OGo)awilliam@workstation:~/OGo/coils/src> tools/coils-service-http --asuser

Text: State the Coils HTTP component.

If this component is running you should be able to connect to and browse the WebDAV hierarchy at http://127.0.0.1:8080/dav (authenticate as the OpenGroupware Coils administrative account "ogo" and the COILSADMINPASSWORD you provided.  Browsing the hierarchy can be performed with Nautilus, cadaver, or any WebDAV client.  Use your systems break sequence [typically Ctrl-C] to stop the component.

(OGo)awilliam@workstation:~/OGo/coils/src> tools/coils-master-service --asuser

Text: Start the Coil's master service which will start and manage an instance of every available component.

The coils-master-service tool can be used in the same manner to start-up the full suite of service components providing HTTP and workflow services (include the TCP/9100 and SMTP listeners).