DevQuickStart

[Home] [Administration] [Development]

• Quick Start
  • Assumptions
  • RabbitMQ
  • PostgreSQL
  • OpenGroupware Coils Installation
    • Check-Out Code
    • Instance Provisioning
    • Activate Your Build Environment
    • Check Your Dependencies
      • Sending Mail
      • Instance Id
    • Starting The Service
    • Notes
  • Installing Tests

Quick Start

This QuickStart always assumes you are creating a development install. If you are creating an instance intended for production use see the QuickStart page.

This document describes how to get the OpenGroupware Coils server up and rolling as quickly as possible for the purpose of developmetn and testing. For detailed document always consult WMOGAG. This procedure will create a private server root in a folder inside the code checkout, other than the PostgreSQL database and RabbitMQ instance this instance of Coils is entirely self contained, it runs as the user (not switching to a special user account).

If you encounter problems with any of the following steps and WMOGAG does not provide enough information to help you out then do not hesitate to post a message to the coils-project mail list. If you are encountering a problem - then someone else may as well, help us get it fixed - or the documentation improved - by letting us know about it.

Assumptions

It is assumed that you have a working Python 2.6, or Python 2.7 installation on your host and that you have administrative privileges. It is also assumed that you are using a UN*X like operation system such as LINUX or BSD.

OpenGroupware Coils is not tested on Microsoft platforms; there are probably issues running OpenGroupware Coils on Microsoft platforms due to its extensive use off the multiprocessing Python module.

RabbitMQ

Installing and provisioning RabbitMQ is a RabbitMQ issue. There are serveral articles available concerning installing RabbitMQ no nodes are available on your network.
- Idjit's Guide To Installing RabbitMQ On openSUSE 12.2
- Idjit's Guide To Installing RabbitMQ on openSUSE 12.1
- Enabling the RabbitMQ Management Plugin

RabbitMQ must be operational on a node on your network (possibly your local machine) before it can be provisioned for access. On the RabbitMQ host (or cluster) you need to configure a virtual host and user for the OpenGroupware Coils components. This is typically accomplished using the rabbitmqctl command; the following commands will create a virtual host named OGo as well as a user named OGo which has permissions to utilize that virtual host.

sudo /usr/sbin/rabbitmqctl add_user OGoDev {AMQPASSWORD}
sudo /usr/sbin/rabbitmqctl add_vhost OGoDev0
sudo /usr/sbin/rabbitmqctl set_permissions -p OGoDev0 OGoDev ".*" ".*" ".*"

The password you provision here will be required later when configuring the OpenGroupware Coils instance.

FYI: Removing the vhost and user
If you want to start over you can delete the RabbitMQ vhost and user with the commands:

sudo /usr/sbin/rabbitmqctl delete_vhost OGoDev0
sudo /usr/sbin/rabbitmqctl delete_user OGoDev

After which the user and vhost can be recreated as new.

PostgreSQL

The example below assume that the PostgreSQL administrative user on your database host is "postgres". The double use of sudo is correct as the examples run the second sudo as root in order to become the user postgres.

On your PostgreSQL server create a role and database.

sudo sudo -u postgres createuser --pwprompt --no-superuser --no-createdb --no-createrole OGoDev

This will prompt you for a password for the new "OGo" PostgreSQL role. You will need to remember this password for later. Now create the database, owned by the new role.

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

NOTE: The location of your PostgreSQL configuration files may vary, depending on your distribution and packaging. But the filenames themselves should always be the same as documented here.

The provision access from that role to access the database. Typically this is managed by rules in the /var/lib/pgsql/data/pg_hba.conf file. If you are using the PGDG packages for PostgreSQL 9.3 on CentOS or RHEL the file is, by default, found in the "/var/lib/pgsql/9.3/data/" directory.

For example, if you are using password authentication to the database from a host having IPv4 address A.B.C.D you would create an entry like:

host    all             all             A.B.C.D/32            password

If you will have multiple OpenGroupware Coils hosts participating in the cluster each needs to be permitted database access via PostgreSQL's access rules.

Once the rule(s) are in place inform the PostgreSQL instance that it needs to reload its configuration.

sudo sudo -u postgres pg_ctl --pgdata /var/lib/pgsql/data reload

If your distribution does not provide the pg_ctl command you can also restart the service. If you are using the CentOS packages from PGDG for PostgreSQL 9.3 the path to the pg_ctl tool is "/usr/pgsql-9.3/bin/pg_ctl".

TEST: Once the database reload has been performed you should be able to connect to the database from the OpenGoupware Coils host using the credential provided. Please ensure that this step is working before proceeding further. On the intended OpenGroupware Coils host the following command in conjunction with the password set by createuser should connect to the database [assuming here A.B.C.D is the address of your PostgreSQL instance].

psql -U OGoDev -h A.B.C.D OGoDev0

FYI: Removing the databse and user

If you desire at some point to start over with your installation you can drop the database and database user with the following commands:

sudo sudo -u postgres dropdb OGoDev0
sudo sudo -u postgres dropuser OGoDev

You will not be able to drop the database user so long as it is the owner of objects in the database.

OpenGroupware Coils Installation

You need all the packages required to build the required Python modules. These include:
* gcc
* make
* libxml2-devel
* libxslt-devel
* postgresql-devel

Check-Out Code

git clone git://git.code.sf.net/p/coils/coils-code coils
cd coils

Now edit the of the Makefile. Numerous defaults are defined here. Especially you should change the HGUSER value to your SourceForge username; automatically for some repository actions are provided via the the Makefile and they assume that this is correct.

make provision

Instance Provisioning

Initializing the install creates the required directory structure in the specified directory and sets the file permissions and ownership. Normally on a production install this would be /var/lib/opengroupware.org and the files would be owned by the server user. But for a development install it is possibly to create one owned by your own user with a root in your home directory (in the code checkout). Variables can be adjusted in the Makefile, the make process can configure the setup of the development instance.

make initialize-database

Activate Your Build Environment

. bin/activate

You'll need to this whenever you start working in your build environment. This will localize everything to your development instance. Most of the Makefile targets will do this for you before performing any action, but it is a good idea to do whenever you start work - that way things you run one-off or by hand will find the correct environment.

Check Your Dependencies

The coils-dependency-check will verify that the required options are available as well as reporting what optional modules are found. This is a great way to know if everything regarding provisioning came out OK.

tools/coils-dependency-check

If there are optional modules you want to utilize but that where not installed by automatic provisioning you can install them using pip once your development environment is activated.

$ tools/coils-dependency-check
...
WARN: Module pycups (IPP printing support) not available.
WARN: Module paramiko (SSH suppport.) not available.
...
$ pip install paramiko
$ pip install pycups
$ tools/coils-dependency-check
...
OK: Module pycups (IPP printing support) available.
OK: Module paramiko (SSH suppport.) available.
...

Note that optional modules may have system dependencies that need to be satisfied. Dependencies for optional modules are all documented in WMOGAG.

Sending Mail

You'll want your instance to be able to send e-mail.

tools/coils-server-config --directive SMTPServer --value "{ 'hostname': 'smtp.example.net', 'password': 'fred123', 'starttls': 'YES', 'username': 'ogo', 'SuppressEMailAttribute': 'receive_email', }"

The password and other parameters in this example should be substituted with those matching your configuration.

Instance Id

Set a server instance name. This should be some unique-ish string that describes your organization or the server's role. For the most part the use of this configuration directive is deprecated in favor of the automatically generated cluster id, but it is still used when generating some labels.

 tools/coils-server-config --directive=skyrix_id --value=EXAMPLE

Starting The Service

The makefile provides a simple way to run the master service which will start the required services.

make run-master

If this appears to run then everything is probably working - if exists shortly after starting you probably have a RabbitMQ / AMQ configuration problem. But if it runs you can test the AMQ bus operation using using coils-ping-service command which will attempt to send an OpenGroupware ping request over the configured messaging vhost to the specified component.

$ tools/coils-ping-service --service=coils.workflow.manager
Store root is /var/lib/opengroupware.org
Pinging "coils.workflow.manager"
Got response from coils.workflow.manager/__ping

If you get a response then the AMQ bus is operational and the specified component is alive and attached to the bus.

Once you've proofed your AMQ configuration you can navigate to http://127.0.0.1:8080/dav with your favorite WebDAV client and login as the administrative account ("ogo") using the password you provided to coils-initialize-database.

Congratulations, you have an operational OpenGroupware Coils instance.

Notes

• If you want to address your OpenGroupware Coils instance over the standard TCP/80 HTTP port, or using SSL/TLS (recommended for all production use), the recommended method is to have OpenGroupware Coils listen on localhost and access it via a reverse proxy such as nginx. See Using nginx with OpenGroupware Coils
• For information on OIE see the OIE wiki page.

Installing Tests

You probably want the testing repository. To add the tests to you setup run:

make install-tests

This will checkout the tests repository. Then you can run the available tests just by performing:

make run-tests