Recent changes to DevQuickStart

DevQuickStart modified by Adam Tauno Williams

Adam Tauno Williams — Tue, 11 Aug 2015 02:14:01 -0000

--- v8
+++ v9
@@ -90,7 +90,7 @@

 ###Check-Out Code

-    hg clone http://hg.code.sf.net/p/coils/code coils
+    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.

DevQuickStart modified by Adam Tauno Williams

Adam Tauno Williams — Wed, 16 Jul 2014 11:44:25 -0000

--- v7
+++ v8
@@ -52,7 +52,9 @@

 ___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:
+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

@@ -62,7 +64,7 @@

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

DevQuickStart modified by Adam Tauno Williams

Adam Tauno Williams — Tue, 29 Apr 2014 11:19:22 -0000

--- v6
+++ v7
@@ -1,4 +1,4 @@
-[Home] [Administration]
+[Home] [Administration] [Development]

 [TOC]

DevQuickStart modified by Adam Tauno Williams

Adam Tauno Williams — Tue, 29 Apr 2014 11:15:50 -0000

--- v5
+++ v6
@@ -101,6 +101,36 @@

     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](https://sourceforge.net/projects/coils/files/WMOGAG.pdf/download).
+
 ####Sending Mail

 You'll want your instance to be able to send e-mail.
@@ -114,7 +144,7 @@

 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=WMMI
+     tools/coils-server-config --directive=skyrix_id --value=EXAMPLE

 ###Starting The Service

DevQuickStart modified by Adam Tauno Williams

Adam Tauno Williams — Tue, 06 Aug 2013 11:43:57 -0000

--- v4
+++ v5
@@ -1,4 +1,6 @@
 [Home] [Administration]
+
+[TOC]

 #Quick Start

@@ -88,6 +90,9 @@

     hg clone http://hg.code.sf.net/p/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
@@ -134,3 +139,13 @@

    - 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](http://www.opengroupware.us/2012/12/using-nginx-with-opengroupware-coils.html)
    - For information on OIE see the [OIE wiki page](wiki:OpenGroupwareIntegrationEngine).
+
+##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

DevQuickStart modified by Adam Tauno Williams

Adam Tauno Williams — Wed, 12 Jun 2013 01:50:49 -0000

--- v3
+++ v4
@@ -92,30 +92,9 @@

 ###Instance Provisioning

-Initializing the install creates the required directory structure in /var/lib/opengroupware.org and sets the file permissions and ownership.
+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.

-    tools/coils-initialize-install  --force --log=`pwd`/coils.log --user=$LOGNAME
-
-Bootstrapping the configuration creates a default configuration file.  Unless a configuration file exists all attempts to use the ___coils-server-config___ command will fail.
-
-    tools/coils-server-config --bootstrap
-
-####RabbitMQ Connectivity
-
-Add connectivity information for the RabbitMQ instance to the server's configuration.
-
-    tools/coils-server-config --directive=AMQConfigDictionary --value="{'hostname': '127.0.0.1','password': 'fred123','port': 5672,'username': 'OGoDev','vhost': 'OGoDev0'}"
-
-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.
-
-    tools/coils-server-config --directive=LSConnectionDictionary --value="{'databaseName': 'OGoDev0', 'hostName': '127.0.0.1','password': 'fred123', 'port': 5432, 'userName': 'OGoDev'}"
-
-
-The password and other parameters in this example should be substituted with those matching your configuration.
+    make initialize-database

 ####Sending Mail

@@ -132,18 +111,11 @@

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

-###Initialization and Start-up
+###Starting The Service

-    tools/coils-initialize-database --initdb --password=fred123
+The makefile provides a simple way to run the master service which will start the required services.

-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:
-
-    tools/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:
-
-    tools/coils-master-service -a
+    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.

WikiPage DevQuickStart modified by Adam Tauno Williams

Adam Tauno Williams — Fri, 22 Mar 2013 11:21:56 -0000

--- v2
+++ v3
@@ -4,7 +4,7 @@

 ___This QuickStart always assumes you are creating a development install.  If you are creating an instance intended for production use see the [QuickStart](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](https://sourceforge.net/projects/coils/files/WMOGAG-Coils.pdf/download). 
+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](https://sourceforge.net/projects/coils/files/WMOGAG-Coils.pdf/download).   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](https://lists.sourceforge.net/lists/listinfo/coils-project).  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.

WikiPage DevQuickStart modified by Adam Tauno Williams

Adam Tauno Williams — Fri, 22 Mar 2013 11:20:32 -0000

WikiPage DevQuickStart modified by Adam Tauno Williams

Adam Tauno Williams — Fri, 22 Mar 2013 11:18:23 -0000

[Home] [Administration]

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.

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

hg clone http://hg.code.sf.net/p/coils/code coils
cd coils
make provision

Instance Provisioning

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

tools/coils-initialize-install  --force --log=`pwd`/coils.log --user=$LOGNAME

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

tools/coils-server-config --bootstrap

RabbitMQ Connectivity

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

tools/coils-server-config --directive=AMQConfigDictionary --value="{'hostname': '127.0.0.1','password': 'fred123','port': 5672,'username': 'OGoDev','vhost': 'OGoDev0'}"

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.

tools/coils-server-config --directive=LSConnectionDictionary --value="{'databaseName': 'OGoDev0', 'hostName': '127.0.0.1','password': 'fred123', 'port': 5432, 'userName': 'OGoDev'}"

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.

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=WMMI

Initialization and Start-up

tools/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:

tools/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:

tools/coils-master-service -a

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.