QuickStart

[Home] [Administration]

Quick Start

This QuickStart always assumes the latest OpenGroupware packages available on PyPI.

If you are attempting to create a developers install see Developers QuickStart.

This document describes how to get the OpenGroupware Coils server up and rolling as quickly as possible. For detailed document always consult WMOGAG.

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.5 or Python 2.6 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 OGo {AMQPASSWORD}
sudo /usr/sbin/rabbitmqctl add_vhost OGo
sudo /usr/sbin/rabbitmqctl set_permissions -p OGo OGo ".*" ".*" ".*"

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 OGo
sudo /usr/sbin/rabbitmqctl delete_user OGo

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 OGo

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 OGo OGo

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. 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.

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 OGo -h A.B.C.D OGo

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 OGo
sudo sudo -u postgres dropuser OGo

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

Provisioning User & Group

sudo /usr/sbin/groupadd skyrix
sudo /usr/sbin/useradd -d /var/lib/opengroupware.org -c "OpenGroupware Service" ogo    
sudo mkdir /var/lib/opengroupware.org
sudo chown ogo:skyrix /var/lib/opengroupware.org

OpenGroupware Coils Installation

Package Installation

Now install the OpenGrouwpare packages. Install both OpenGroupware (the server) and snurtle (command line client). Snurtle is the primary interface for server administration and workflow management. Optionally you can install snurtle on just your workstation, but having it available on the server's host can be handy in a pinch.

sudo easy_install OpenGroupware
sudo easy_install snurtle

Installing these packages should also install the required prerequisites. But installation of the prerequisites may depend on the availability of some system packages. If you encounter difficulty with dependency installation please consult WMOGAG for details on the dependency in question. If you cannot resolve the dependency issue with the information provided in WMOGAG then do not hesitate to post a message to the coils-project mail list.

Dependency Check

The OpenGroupware Coils package provides a tool for verifying the dependencies installed on the system. You should run coils-dependency-check whenever upgrading Coils or changing the underlying system to verify all required dependencies are available.

[root@test1 ~]# coils-dependency-check 
OK: Module dateutil (Date & Time Arithmatic) available.
OK: Module xlwt (XLS<2007 write support) available.
OK: Module lxml (SAX & DOM XML Processing) available.
OK: Module PIL (Python Imaging Library) available.
OK: Module argparse (Enhanced argument parsing, required for /wiki protocol) available.
OK: Module markdown (Markdown rendering, required for /wiki protocol) available.
OK: Module psycopg2 (PostgreSQL RDBMS connectivity) available.
OK: Module base64 (Encode and decode Base64 data) available.
OK: Module sqlalchemy (Object Relational Modeling) 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.
OK: Module pytz (Python Time Zone tables) available.
WARN: Module informixdb (Informix RDBMS connectivity) not available.
OK: Module vobject (vCard and vEvent parsing) available.
OK: Module xlrd (XLS<2007 read support) available.
WARN: Module cups (IPP printing support) not available.
OK: Module paramiko (SSH suppport.) available.

1 database connectivity modules found.
 * Make sure the RDBMS you intend to use for the SQLalchemy  *
 * ORM is installed and operational.                         *

2 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.      *

Instance Provisioning

Initializing the install creates the required directory structure in /var/lib/opengroupware.org and sets the file permissions and ownership.

sudo coils-initialize-install  --force

Bootstrapping the configuration creates a default configuration file. Unless a configuration file exists all attempts to use the coils-server-config command will fail.

sudo coils-server-config --bootstrap

RabbitMQ Connectivity

Add connectivity information for the RabbitMQ instance to the server's configuration.

sudo coils-server-config --directive=AMQConfigDictionary --value="{'hostname': '127.0.0.1','password': 'fred123','port': 5672,'username': 'OGo','vhost': 'OGo'}"

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

PostgreSQL Connectivty

Add connectivity information for the PostgtreSQL instance to the server's configuration.

sudo coils-server-config --directive=LSConnectionDictionary --value="{'databaseName': 'OGo', 'hostName': '127.0.0.1','password': 'fred123', 'port': 5432, 'userName': 'OGo'}"

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

Sending Mail

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

sudo 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.

 sudo coils-server-config --directive=skyrix_id --value=WMMI

Initialization and Start-up

sudo coils-initialize-database --initdb --password=fred123

The password specified here will be the password for the administrator account in your OpenGroupware Coils instance - if you forget it you can reset it using the same command without the --initdb parameter, like:

sudo coils-initialize-database --password=fred123

With the --initdb parameter this command will attempt to connect to your provisioned database and create the required data and subsequent entries. If that complete successfully
you should be able to start the OpenGroupware Coils instance:

sudo coils-master-service

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.

$ 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.