INSTALL.txt

==================================================
Plone 4 buildout for http://land.copernicus.eu
==================================================

.. contents ::

Buildout is a tool for easily creating identical development or production
environments. This tool gives you the right versions of Zope, Plone products
and python libraries to ensure that every installation gets exactly the same
configuration.

Everything is installed in a local folder. This prevents conflicts with
already existing python and zope packages. Nothing other than this folder
is touched, so the user doesn't need any special priviliges.

There are three configurations available for running this buildout:
 1. one for developers (development)
 2. one for production (deployment)
 3. one for demonstration (staging)

System requirements and preparation
===============================================
The buildout is intended to run on Linux/Unix-based operating systems. The
buildout has been used and tested on *Debian*, *Ubuntu* for development and *CentOS 5* and *CentoOS 6* for production.

The below system libraries must be installed on the server before you run the buildout. These must be globally
installed by the server administrator.

For CentOS, the EPEL and RPMForge repositories need to be configured before installing
the packages, since some of them are not included in the base repo.

All installs will require the basic GNU build and archive tools: gcc, g++, gmake, gnu tar, gunzip, bunzip2 and patch.

On Debian/Ubuntu systems, this requirement will be taken care of by installing build-essential. On RPM systems (RedHat, Fedora, CentOS), you'll need the gcc-c++ (installs most everything needed as a dependency) and patch RPMs.

====================  ====================   =============================
Debian/Ubuntu         CentOS                 dependency for
====================  ====================   =============================
python 2.7            python 2.7             buildout
python-dev            python-devel           buildout
wget                  wget                   buildout
lynx                  lynx                   buildout
tar                   tar                    buildout
gcc                   gcc                    buildout
git > 1.8.3           git > 1.8.3            buildout
graphviz              --                     eea.relations
graphviz-gd           --                     eea.relations
graphviz-dev          graphviz-devel         eea.relations
ImageMagick > 6.3.7+  ImageMagick > 6.3.7+   eea.relations
libc6-dev             glibc-devel            buildout
libxml2-dev           libxml2-devel          buildout
libxslt-dev           libxslt-devel          buildout
libsvn-dev            subversion-devel       buildout
libaprutil1-dev       apr-util-devel         buildout
wv                    wv                     http://wvware.sourceforge.net
poppler-utils         poppler-utils          pdftotext
libjpeg-dev           libjpeg-turbo-devel    Pillow
libldap2-dev          openldap-devel         OpenLDAP
libsasl2-dev          cyrus-sasl-devel       OpenLDAP
pdftk                 pdftk                  eea.pdf
readline-dev          readline-devel         buildout
build-essential       make                   buildout
libz-dev              which                  buildout
libssl-dev            openssl-devel          buildout
--                    patch                  buildout
--                    gcc-c++                buildout
libcurl3-dev          curl-devel             sparql-client and pycurl2
--                    redhat-lsb-core        init script
====================  ====================   =============================

Additional info to install git for CentOS::

$ wget http://puias.math.ias.edu/data/puias/computational/6/x86_64/git-1.8.3.1-1.sdl6.x86_64.rpm
$ wget http://puias.math.ias.edu/data/puias/computational/6/i386/perl-Git-1.8.3.1-1.sdl6.noarch.rpm
$ yum update  git-1.8.3.1-1.sdl6.x86_64.rpm perl-Git-1.8.3.1-1.sdl6.noarch.rpm


Notes regarding using Copernicus buildout with python2.7 as a Software Collection
---------------------------------------------------------------------------------

Copernicus buildout can be used with python2.7 installed as a Software Collection, but we need to enable the python27 collection
prior to setting up the buildout or trying to manually start/stop the instances generated by the buildout. Enabling the
python27 software collection can easily be done by issueing the following command::

$ scl enable python27 bash

After this, all other commands/operations are the same as those for system python 2.7. The init script and the zopesendmail daemon
have been adapted to work seamlessly with either system python2.7 and Software Collection python2.7, without any additional step
required.

More informations about Software Collection can be found at `https://www.softwarecollections.org/en/`_.

Run buildout for development
----------------------------
The first time you want to use this buildout you first have to get
all software from subversion and then run a few commands::

   $ git clone git@github.com:eea/land.copernicus.plonebuildout.git
   $ cd land.copernicus.plonebuildout
   $ ./install.sh
   $ ./bin/buildout -c development.cfg

This first three steps only have to be done the first time you use this
buildout. When you later want to update the site because people have committed
changes you do::

   $ cd land.copernicus.plonebuildout
   $ git pull -u
   $ ./bin/develop rb

To start the application with ZEO support::

$ ./bin/zeoserver start
$ ./bin/www1 start

... and without ZEO support::

$ ./bin/instance start

Now we will have a running Plone buildout. The development buildout by default install ZEO
and two ZEO clients (*./bin/www1* and *./bin/www2*) plus one Zope instance that can be
used without ZEO support (*./bin/instance*).

Run buildout for production (deployment)
----------------------------------------
Some preliminary preparations must be done by system administrators on the deployment server:

* a user and user group called 'zope' should be created having neccesary rights
* the project folder must be created under /var/local/land.copernicus.plonebuildout with group owner zope and 2775 (rwxrwxr-x) mode
* add under /etc/profile:

::

 if [ "`id -gn`" = "zope" ]; then
     umask 002
 fi

The first time you want to use the copernicus plonebuildout you have to run a
few commands (as user zope)::

$ cd /var/local
$ git clone git@github.com:eea/land.copernicus.plonebuildout.git
$ cd land.copernicus.plonebuildout
$ ./install.sh
$ ./bin/buildout -c deployment.cfg
$ chmod -R g+rw .

The above installation process will install and configure, in addition to
Zope and ZEO, the following:

* *Apache* basic configuration
* *Pound* for load balancing ZEO clients
* *Memcache*
* Daemon for sending *emails*
* *ZEO clients* - 2 instances
* *ZEO server*

Processes on production should be started with sudo, e.g::

$ sudo ./bin/memcached start
$ sudo ./bin/zeoserver start
$ sudo ./bin/www1 start
$ sudo ./bin/www2 start
$ sudo ./bin/poundctl start

In case we use python 2.7 as a Software Collection, the above commands should be issued like the following::

$ sudo scl enable python27 -- ./bin/memcached start
$ sudo scl enable python27 -- ./bin/zeoserver start
$ sudo scl enable python27 -- ./bin/www1 start
$ sudo scl enable python27 -- ./bin/www2 start
$ sudo scl enable python27 -- ./bin/poundctl start

In order to avoid this, it is recommended that you use the restart-portal init script generated in 
/etc/init.d the script from /var/local/land.copernicus.plonebuildout/etc/rc.d/restart-portal. The script will automatically
use the Software Collection python 2.7 if there is no system python 2.7 without any other user intervention.

For the application stack to be restarted when server reboot, the system
administrator should add under /etc/init.d the script from
/var/local/land.copernicus.plonebuildout/etc/rc.d/restart-portal, e.g.::

$ cd /var/local/land.copernicus.plonebuildout/etc/rc.d
$ ln -s `pwd`/restart-portal /etc/init.d/restart-portal
$ chkconfig --add restart-portal
$ service restart-portal start

Apache configuration file should be symlinked from
/var/local/land.copernicus.plonebuildout/etc/apache-vh.conf under
/etc/httpd/conf.d, this operation should be done by system
administrators, e.g.::

$ ln -s /var/local/land.copernicus.plonebuildout/etc/apache-vh.conf /etc/httpd/conf.d/land-copernicus-apache-vh.conf

Run buildout for staging 
----------------------------
Some preliminary preparations must be done by system administrators on the staging server:

* a user and user group called 'zope' should be created having neccesary rights
* the project folder must be created under /var/local/land.copernicus.plonebuildout with group owner zope and 2775 (rwxrwxr-x) mode
* add under /etc/profile:

::

 if [ "`id -gn`" = "zope" ]; then
     umask 002
 fi

The first time you want to use the copernicus plonebuildout you have to run a
few commands (as user zope)::
The first time you want to use this buildout you first have to get
all software from subversion and then run a few commands::

   $ git clone git@github.com:eea/land.copernicus.plonebuildout.git staging
   $ cd staging
   $ ./install.sh
   $ ./bin/buildout -c staging.cfg

This first three steps only have to be done the first time you use this
buildout. When you later want to update the site because people have committed
changes you do::

   $ cd staging
   $ git pull -u
   $ ./bin/develop rb

The above installation process will install and configure, in addition to
Zope and ZEO, the following:

* *Apache* basic configuration
* *Pound* for load balancing ZEO clients
* *Memcache*
* Daemon for sending *emails*
* *ZEO clients* - 2 instances
* *ZEO server*
* *Supervisor* for monitor and control the processes: seo, pound, memcached,
  www1, www2 

To start processess on staging::

   $ ./bin/supervisord

If the supervisord is already started you will receive this error::

   $ .bin/supervisord
   Error: Another program is already listening on a port that one of our HTTP
   servers is configured to use.  Shut this program down first before starting
   supervisord.
   For help, use bin/supervisord -h

To start all instance::

   $ ./bin/supervisorctl start all

This command will start seo, pound, memcached, www1, www2.
 
To restart all instance::

   $ ./bin/supervisorctrl restart all

To stop all instance::

   $ ./bin/supervisorctrl stop all

To see the status for all instance::

   $ ./bin/supervisorctl status

To stop only one instance e.g. www1::

   $ ./bin/supervisorctl restart www1

To stop supervisor daemon::

   $ ./bin/supervisorctl shutdown


User permissions
~~~~~~~~~~~~~~~~
On production server, system administrators should setup:

* umask 002 for all users
* all users members of 'zope' group

Database packing
~~~~~~~~~~~~~~~~
Packing is a vital regular maintenance procedure The Plone database does not automatically prune deleted content. You must periodically pack the database to reclaim space.

Data.fs should be packed daily via a cron job::

 01 2 * * * /var/local/land.copernicus.plonebuildout/bin/zeopack

Synchronisation database
~~~~~~~~~~~~~~~~~~~~~~~~
The synchronisation is done by the sync-data.sh via cron job, which is set for
zope user::

 0 03 * * Sun /var/local/staging/sync-data.sh >> /var/local/staging/sync-data.log

To edit the cron job for the zope user::

    $ crontab -e

The synchronisation script makes logs in sync-data.log.

Portal Property for Google Maps Api Key
---------------------------------------
In ZMI -> portal_properties add a plone property sheet called geographical_properties and inside it add a new string property called google_key.
In this property you have to paste the API KEY, what you can generate at https://developers.google.com/maps/documentation/javascript/v2/introduction#Obtaining_Key

.. _`https://www.softwarecollections.org/en/`: https://www.softwarecollections.org/en/