Installation Instructions
*************************

-------------------------------------------
| MANUAL DE INSTALACIÓN DEL GONG-CM  v1.0 |
-------------------------------------------

La instalación descrita fue efectuada sobre Debian 6.0 (Squeed). Es posible realizar los mismos pasos
en cualquier otro sistema operativo, aunque algunos pasos es posible que sean distintos.


Aunque el proceso es similar utilizando una BBDD sqlite o postgress, este documento se refiere a
la instalación sobre un motor de BBDD MySQL. Se asume que MySQL está correctamente instalado y
configurado, así como el cliente local de MySQL desde línea de comandos. En la siguiente URL se
describe el proceso de instalación:

http://www.debianadmin.com/mysql-database-server-installation-and-configuration-in-debian-2.html


Convenciones

Una linea que empieza por "$" indica el prompt bash en consola.
Una linea que empieza por "mysql>" indica el prompt en la consola de mysql


*********************************************************************************************

Indice
1.- Instalación
2.- Configuración
3.- Actualización
4.- Instalación multisitio
5.- Prueba
6.- Notas de Seguridad

*********************************************************************************************


1.- Instalacion

1.1.- Instalar la BD de Cuadro de Mando.

  En primer lugar apuntaremos el nombre de la BBDD de GONG-GOR desde el que se sincronizarán los datos
  del cuadro de mando (supongamos que es 'gong_gor')

  Crearemos la BBDD 'gong_cm' y el usuario 'gong_cm_user' con password 'gong_cm_user_pass' (estos valores
  se pueden cambiar por los que elijamos para nuestra instalación):

    mysql> create DATABASE gong_cm DEFAULT CHARACTER SET utf8 DEFAULT COLLATE utf8_general_ci;
    mysql> grant ALL ON gong_cm.* TO gong_cm_user@'localhost' IDENTIFIED BY 'gong_cm_user_pass';
    mysql> grant CREATE ROUTINE ON gong_cm.* to gong_cm_user@'localhost';

 Además, es neceario permitir expresamente que el usuario 'gong_cm_user' pueda leer de la BBDD utilizada por
 GONG-GOR . Para ello, suponiendo que esta última se llame 'gong_gor' se deberá ejecutar la siguiente sentencia SQL:

    mysql> GRANT SELECT ON gong_gor.* to gong_cm_user@'localhost';


 Ejecutar el script "instala_gor_cm.sql" para hacer la carga inicial de BBDD

    $ mysql -u gong_cm_user -p gong_cm < instala_gor_cm.sql


1.2.- Instalación de TOMCAT

  En primer lugar debemos instalar la máquina virtual Java de Sun para ello es necesario habilitar los
  repositorios "non-free" en el sistema de forma que el fichero /etc/apt/sources.list contenga una línea
  similar a la siguiente:

    deb http://ftp.debian.org/debian squeeze main contrib non-free

  Una vez que esté dicho repositorio habilitado instalamos SUN-JAVA 6:

    $ apt-get update && apt-get install sun-java6-jre sun-java6-jdk

  Si estamos instalando sobre Debian Wheezy o posteriores, en lugar del paso anterior deberemos seguir
  el método siguiente:

    https://wiki.debian.org/Java/Sun

  Después, instalaremos el conector mysql para java:

    $ apt-get install libmysql-java

  ejecutamos los comandos:

    $ update-alternatives --config java
    $ update-alternatives --config javac

  y seleccionamos en cada uno de ellos la versión 1.6 de Sun recién instalada. A continuación añadimos las
  siguientes líneas al fichero /etc/profile para que Tomcat consiga encontrar los paths de SUN-JAVA:

    # Setup Jave environment 6
    export PATH=$PATH:/usr/lib/jvm/java-6-sun/bin
    export JAVA_HOME=/usr/lib/jvm/java-6-sun
    export JRE_HOME=/usr/lib/jvm/java-6-sun/jre

  y por fín, instalamos Tomcat:

    $ apt-get install tomcat6

  incluimos las siguientes líneas al fichero /etc/default/tomcat6 :

    JAVA_HOME=/usr/lib/jvm/java-6-sun
    TOMCAT6_SECURITY=no

  añadimos al classpath la ubicación de las librerías mysql. Para ello, en la línea 'shared.loader'
  del fichero /etc/tomcat6/catalina.properties incluimos el path '/usr/share/java/*.jar'. Por ejemplo:

    shared.loader=${catalina.base}/shared/classes,${catalina.base}/shared/lib/*.jar,/usr/share/java/*.jar

  y reiniciamos tomcat para que tengan efecto los cambios:

    $ /etc/init.d/tomcat6 restart


1.3.- Instalación de MONDRIAN 

  Descargamos la versión 3.2.1 de Mondrian desde:

    http://sourceforge.net/projects/mondrian/

  y extraemos el contenido del archivo lib/mondrian.war sobre el directorio ${TOMCAT_HOME}/webapps/mondrian 
  ( ${TOMCAT_HOME} es el directorio de aplicaciones de tomcat6: en debian/ubuntu corresponde a la
  ruta /var/lib/tomcat6/webapps ):

    $ mkdir /var/lib/tomcat6/webapps/mondrian
    $ unzip lib/mondrian.war -d /var/lib/tomcat6/webapps/mondrian


**********************************************************************************************


2.- Configuración

2.1.- Copiar el fichero gor_cm.xml en la dirección ${TOMCAT_HOME}/mondrian/WEB-INF/queries/ :

    $ cp gor_cm.xml /var/lib/tomcat6/webapps/mondrian/WEB-INF/queries/


2.2.- Sobreescribir los JSP de la dirección ${TOMCAT_HOME}/mondrian/WEB-INF/queries/
      con el existente en este paquete:

    $ cp cm_economico.jsp /var/lib/tomcat6/webapps/mondrian/WEB-INF/queries/
    $ cp cm_tecnico.jsp /var/lib/tomcat6/webapps/mondrian/WEB-INF/queries/

NOTA: Si está instalando sobre una versión anterior de GONG, es posible que en el directorio de destino se encuentre el fichero "cm.jsp". Este fichero no es necesario a partir de la versión 2.44 de GONG Cuadro de mando y puede ser borrado en caso de existir. 

2.3.- Sobreescribir el fichero testpage.jsp de la dirección ${TOMCAT_HOME}/mondrian/ con el
      existente en este paquete:

    $ cp testpage.jsp /var/lib/tomcat6/webapps/mondrian/


2.3. Copiar el fichero conexion.properties en la dirección
     ${TOMCAT_HOME}/mondrian/WEB-INF/classes/ :

    $ cp conexion.properties /var/lib/tomcat6/webapps/mondrian/WEB-INF/classes/


2.4. Sustituir en el fichero anterior los valores asignados a gor_cm.jdbcUrl, gor_cm.jdbcUser
     y gor_cm.jdbcPassword por los adecuados al usuario y password de la BBDD del cuadro
     de mando definidos en el punto 1.1 de este manual y con el nombre de la BBDD de GONG-GOR:

   gor_cm.jdbcUrl=jdbc:mysql://localhost/gong_cm
   gor_cm.jdbcUser=gong_cm_user
   gor_cm.jdbcPassword=gong_cm_user_pass
   gor_cm.jdbcDBName=gong_gor


2.5. Tras reiniciar Tomcat ya estará lista la aplicación a través de la URL http://localhost:8180/mondrian/testpage.jsp?query=cm

   $ /etc/init.d/tomcat6 restart

2.6. Configurar el acceso a las imágenes y css de mondrian:

   $ cp apache.conf /etc/apache2/conf.d/cuadrodemando.conf
   $ /etc/init.d/apache2 restart


*********************************************************************************************


3. Actualización 

Actualmente (versión1.0.3) la BD de Cuadro de Mando se actualiza desencadenando un procedimiento almacenado que posee
la BD del cuadro de mando. Este proceso lo realiza el script actualiza_cm.py por lo que habrá que copiarlo
al directorio de ejecución:

  $ cp actualizar_cm.py /usr/bin/actualizar_cm.py

Instalaremos las librerías de acceso a BBDD para que el script anterior pueda conectar con la BBDD:

  $ apt-get install python-mysqldb

Para permitir la ejecución diaria, habilite el cron del fichero gong-panelcontrol.cron.d para el usuario de
tomcat (tomcat6), o copie dicho fichero a la ruta /etc/cron.d modificando en él, si fuera necesario, la ruta del
fichero .properties donde se definen los parámetros de conexión y cambiándole el nombre al adecuado para debian:

  $ cp gong-cuadrodemando.cron.d /etc/cron.d/gong-cuadrodemando

Para comprobar que la instalación ha sido correcta, ejecute este script de modo excepcional ahora para que los datos aparezcan
en la BD de Cuadro de Mando:

  $ python /usr/bin/actualizar_cm.py /var/lib/tomcat6/webapps/mondrian/WEB-INF/classes/conexion.properties



*********************************************************************************************


4.- Instalación multisitio.

Si existe más de una instancia de GONG corriendo en la máquina será necesario realizar una instalación multisitio.

4.1.- En primer lugar, crearemos una BBDD de cuadro de mando para cada una de las instancias tal y como se
describe en el punto 1.1 de este manual. Los valores de nombre de bbdd, usuario y password los utilizaremos
en el siguiente punto.

Por cada instancia de GONG-GOR corriendo habrá una variable de entorno GOR_SITEID definida en la
configuración del host virtual de apache (por ejemplo):

  SetEnv GOR_SITEID "ong2"

Usaremos esa variable para diferenciar las consultas al cuadro de mando y las conexiones de BBDD


4.2.- Usando el valor de esa la variable GOR_SITEID crearemos una copia del fichero conexion.properties

  $ cp conexion.properties /var/lib/tomcat6/webapps/mondrian/WEB-INF/classes/cm-ong2.properties

y lo configuraremos con la BBDD específica de esa instancia que hemos creado unas líneas más arriba y
con la correspondiente para la BBDD de GONG-GOR.


4.3.- Después crearemos copia de cm_economico.jsp y de cm_tecnico.jsp de la siguiente forma:

  $ cp cm_economico.jsp /var/lib/tomcat6/webapps/mondrian/WEB-INF/queries/cm_economico-ong2.jsp
  $ cp cm_tecnico.jsp /var/lib/tomcat6/webapps/mondrian/WEB-INF/queries/cm_tecnico-ong2.jsp

modificando estos dos ficheros (cm_economico-ong2.jsp y cm_tecnico-ong2.jsp) para que busquen el fichero properties modificado sustituyendo
la línea

  java.io.InputStream is = cl.getResourceAsStream("conexion.properties");

por

  java.io.InputStream is = cl.getResourceAsStream("cm2-ong.properties");


4.4.- Por último crearemos una copia de cada fichero de cron según el apartado 3 de este manual,
modificando la ruta del fichero properties :

  /var/lib/tomcat6/webapps/mondrian/WEB-INF/classes/conexion.properties

por

  /var/lib/tomcat6/webapps/mondrian/WEB-INF/classes/cm-ong2.properties



*********************************************************************************************


5.- Probar la instalación.

Entre en la aplicación y pruebe el resultado de la instalación accediendo al Cuadro de Mando a través de GONG-GOR.



*********************************************************************************************


6.- Nota de seguridad.

Debido a que tomcat no está autentificado, todas las páginas de mondrian están disponibles a través del puerto 8180.
El usuario final accede a la información de GONG-CM a través de un proxy existente en GONG-GOR. Por lo tanto,
es necesario que se securice la máquina impidiendo las conexiones a dicho puerto que no provengan de localhost.

(Revisar algo mejor la configuración de tomcat para impedir conexiones desde fuera de localhost)




*********************************************************************************************
Fin del Archivo INSTALL.TXT
*********************************************************************************************
