Recent changes to QuickStart

QuickStart modified by Adam Tauno Williams

Adam Tauno Williams — Tue, 06 Aug 2013 10:17:11 -0000

--- v22
+++ v23
@@ -97,6 +97,41 @@

 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](https://sourceforge.net/projects/coils/files/WMOGAG-Coils.pdf/download) for details on the dependency in question.  If you cannot resolve the dependency issue with the information provided in [WMOGAG](https://sourceforge.net/projects/coils/files/WMOGAG-Coils.pdf/download) then do not hesitate to post a message to the [coils-project mail list](https://lists.sourceforge.net/lists/listinfo/coils-project).

+###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

WikiPage QuickStart modified by Adam Tauno Williams

Adam Tauno Williams — Fri, 22 Mar 2013 11:04:12 -0000

--- v21
+++ v22
@@ -3,6 +3,9 @@
 #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](DevQuickStart). __
+

 This document describes how to get the OpenGroupware Coils server up and rolling as quickly as possible.  For detailed document always consult [WMOGAG](https://sourceforge.net/projects/coils/files/WMOGAG-Coils.pdf/download).

WikiPage QuickStart modified by Adam Tauno Williams

Adam Tauno Williams — Tue, 19 Mar 2013 16:48:28 -0000

--- v20
+++ v21
@@ -1,3 +1,5 @@
+[Home] [Administration]
+
 #Quick Start

 ___This QuickStart always assumes the latest OpenGroupware packages available on PyPI.___

WikiPage QuickStart modified by Adam Tauno Williams

Adam Tauno Williams — Tue, 19 Mar 2013 16:47:29 -0000

--- v19
+++ v20
@@ -75,8 +75,8 @@

 ##Provisioning User & Group

-    sudo groupadd skyrix
-    sudo useradd -d /var/lib/opengroupware.org -c "OpenGroupware Service" ogo    
+    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

WikiPage QuickStart modified by Adam Tauno Williams

Adam Tauno Williams — Wed, 05 Dec 2012 12:30:46 -0000

--- v18
+++ v19
@@ -75,10 +75,10 @@
 
 ##Provisioning User & Group
 
-    groupadd skyrix
-    useradd -d /var/lib/opengroupware.org -c "OpenGroupware Service" ogo    
-    mkdir /var/lib/opengroupware.org
-    chown ogo:skyrix /var/lib/opengroupware.org
+    sudo groupadd skyrix
+    sudo 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
 
@@ -87,8 +87,8 @@
 
 Now install the OpenGrouwpare packages.  Install both OpenGroupware (the server) and snurtle (command line client).  [Snurtle](https://sourceforge.net/p/snurtle/home/Home/) 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.
 
-    easy_install OpenGroupware
-    easy_install snurtle
+    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](https://sourceforge.net/projects/coils/files/WMOGAG-Coils.pdf/download) for details on the dependency in question.  If you cannot resolve the dependency issue with the information provided in [WMOGAG](https://sourceforge.net/projects/coils/files/WMOGAG-Coils.pdf/download) then do not hesitate to post a message to the [coils-project mail list](https://lists.sourceforge.net/lists/listinfo/coils-project).
 
@@ -97,17 +97,17 @@
 
 Initializing the install creates the required directory structure in /var/lib/opengroupware.org and sets the file permissions and ownership.
 
-    coils-initialize-install  --force
+    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.
 
-    coils-server-config --bootstrap
+    sudo coils-server-config --bootstrap
 
 ####RabbitMQ Connectivity
 
 Add connectivity information for the RabbitMQ instance to the server's configuration.
 
-    coils-server-config --directive=AMQConfigDictionary --value="{'hostname': '127.0.0.1','password': 'fred123','port': 5672,'username': 'OGo','vhost': 'OGo'}"
+    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.
 
@@ -115,7 +115,7 @@
 
 Add connectivity information for the PostgtreSQL instance to the server's configuration.
 
-    coils-server-config --directive=LSConnectionDictionary --value="{'databaseName': 'OGo', 'hostName': '127.0.0.1','password': 'fred123', 'port': 5432, 'userName': 'OGo'}"
+    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.
@@ -124,7 +124,7 @@
 
 You'll want your instance to be able to send e-mail.
 
-    coils-server-config --directive SMTPServer --value "{ 'hostname': 'smtp.example.net', 'password': 'fred123', 'starttls': 'YES', 'username': 'ogo', 'SuppressEMailAttribute': 'receive_email', }"
+    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.
@@ -133,20 +133,20 @@
 
 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.
 
-     coils-server-config --directive=skyrix_id --value=WMMI
+     sudo coils-server-config --directive=skyrix_id --value=WMMI
 
 ###Initialization and Start-up
 
-    coils-initialize-database --initdb --password=fred123
+    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:
 
-    coils-initialize-database --password=fred123
+    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:
 
-    coils-master-config
+    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.

WikiPage QuickStart modified by Adam Tauno Williams

Adam Tauno Williams — Wed, 05 Dec 2012 10:55:22 -0000

--- v17
+++ v18
@@ -26,15 +26,25 @@
 
 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 -u postgres createuser --pwprompt --no-superuser --no-createdb --no-createrole OGo
+    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 -u postgres createdb -E UTF-8 -O OGo OGo
+    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.__
 
@@ -46,9 +56,22 @@
 
 Once the rule(s) are in place inform the PostgreSQL instance that it needs to reload its configuration.
 
-    sudo -u postgres pg_ctl --pgdata /var/lib/pgsql/data reload
+    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
 
@@ -76,7 +99,7 @@
 
     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.
+Bootstrapping the configuration creates a default configuration file.  Unless a configuration file exists all attempts to use the ___coils-server-config___ command will fail.
 
     coils-server-config --bootstrap

WikiPage QuickStart modified by Adam Tauno Williams

Adam Tauno Williams — Wed, 05 Dec 2012 00:03:42 -0000

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

WikiPage QuickStart modified by Adam Tauno Williams

Adam Tauno Williams — Tue, 04 Dec 2012 23:57:39 -0000

--- v15
+++ v16
@@ -138,3 +138,6 @@
 
 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](http://www.opengroupware.us/2012/12/using-nginx-with-opengroupware-coils.html)

WikiPage QuickStart modified by Adam Tauno Williams

Adam Tauno Williams — Tue, 04 Dec 2012 23:53:22 -0000

--- v14
+++ v15
@@ -1,5 +1,6 @@
 #Quick Start
 
+___This QuickStart always assumes the latest OpenGroupware packages available on PyPI.___
 
 This document describes how to get the OpenGroupware Coils server up and rolling as quickly as possible.  For detailed document always consult [WMOGAG](https://sourceforge.net/projects/coils/files/WMOGAG-Coils.pdf/download).

WikiPage QuickStart modified by Adam Tauno Williams

Adam Tauno Williams — Tue, 04 Dec 2012 23:51:23 -0000

--- v13
+++ v14
@@ -1,12 +1,14 @@
 #Quick Start
 
 
-This document describes how to get the OpenGroupware Coils server up and rolling as quickly as possible.  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 detailed document always consult [WMOGAG](https://sourceforge.net/projects/coils/files/WMOGAG-Coils.pdf/download). 
+
+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.
 
 ##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 due to its extensive use off the multiprocessing Python module.
+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
 
@@ -64,6 +66,9 @@
     easy_install OpenGroupware
     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](https://sourceforge.net/projects/coils/files/WMOGAG-Coils.pdf/download) for details on the dependency in question.  If you cannot resolve the dependency issue with the information provided in [WMOGAG](https://sourceforge.net/projects/coils/files/WMOGAG-Coils.pdf/download) then do not hesitate to post a message to the [coils-project mail list](https://lists.sourceforge.net/lists/listinfo/coils-project).
+
+
 ###Instance Provisioning
 
 Initializing the install creates the required directory structure in /var/lib/opengroupware.org and sets the file permissions and ownership.
@@ -119,5 +124,16 @@
 
     coils-master-config
 
-Once this is started 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___.
+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.
+