# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
# LibreSource Installation notes
# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
# Copyright (C) 2004-2007 Artenum SARL / INRIA
# http://www.libresource.org - contact@libresource.org
# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
# Thank you for using LibreSource
# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
# Sommaire
# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- Prerequisites
- Postgres operations
- Customisation of JBoss
- Customisation of the properties files
- Starting/Stoping Jboss/Libresource
- Optimization


# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
# Prerequisites
# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  You must install the following components on the server
   - JBoss Application Server (http://www.jboss.org/downloads/index)
       [this version has been successfully tested on JBoss 4.2.1]
   - JDK 1.5.x or 1.6.x versions (http://java.sun.com/j2se/)
       [the JDK 1.6 is mandatory for the installation of tigase the Jabber Server]
   - PostgreSQL Database server (version 8.x or more recent) (http://www.postgresql.org/)

  You must have the libresource XML configuration files and the libresource EAR file.
   - You can directly download them on (http://www.libresource.org)
   - You can generate them from the source code which can be downloaded on 
     (http://www.libresource.org). A BUILD.txt explain how to generate those files.
     
# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
# Postgres operations
# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

  - create the libresource database in PostgreSQL
  - create the libresource user in PostgreSQL
  - allow this user to be a superuser : 
    ALTER USER libresource WITH superuser;

# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
# Customisation of JBoss
# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

1) Security configuration
  + Edit the file JBOSS/server/default/conf/jboss-service.xml
    and replace "anonymous" by "guest"

  + Edit the file JBOSS/server/default/conf/login-config.xml 
    and add an application policy like the one below.

    <!-- Libresource policy -->
    <application-policy name = "libresource">
	    <authentication>
		    <login-module code = "org.libresource.security.InternalBaseLoginModule"
				  flag = "requisite">                  
			    <!-- Any existing security context will be restored on logout -->
			    <module-option name="restore-login-identity">true</module-option>
		    </login-module>
		    
		    <login-module code = "org.jboss.security.ClientLoginModule"
				  flag = "required">
			    <!-- Any existing security context will be restored on logout -->
			    <module-option name="restore-login-identity">true</module-option>
		    </login-module>
	    </authentication>
    </application-policy>

2) Database access
  After install postgres on the server, configure JBoss to access database
  - Database driver
    + Download from http://jdbc.postgresql.org/download.html the right JDBC driver 
      and copy the jar file to JBOSS/server/default/lib
      
3) Thirdpart library
  Download the "commons-beanutils" library (http://commons.apache.org/downloads/)
  and copy the jar files into the JBOSS/server/default/lib directory
       
# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
# Customisation of the properties files
# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

1) LibreSource config file (libresourceConfig-service.xml)
  - If you did not generate the configuration file from the build process 
    edit the file in order to configure the following properties.

		libresource.log.dir : specify where libresource will write its 
		                      log files. This directory must exist and 
		                      the user who is running jboss must have 
		                      the right to write into it.

		notification.default.type : specify which protocol of notification 
		                            will be checked by default on the web 
		                            when a user click on the Watch Event 
		                            of a resource. (The clue or by the menu)
		                            [mail or jabber]

		jabber.server : Specify the libresource jabber user host that will 
		                notify the libresource users of an event.
		                [http://localhost:9000]

		jabber.username : Name of the jabber user that will be used for 
		                  the Jabber notification. This Jabber user must 
		                  already exist on the specified jabber server.
		jabber.password : Password of the libresource jabber user.

		kernel.serverUrl : Url given as base path for the web part. 
		                   The protocol should be provided too as 
		                   the port if you are not using the default port (80).

		kernel.indexationDataDir : Directory used by the indexation engine to 
		                           read and write its index for quick search.
		                           This directory should exist.
		                           
		libresource.distributedFilesystem : Directory used to write temporary 
		                                    files between the application server 
		                                    and the database.
		                                    Both libresource and postgres user 
		                                    should have access in read write. 
		                                    The point (c) explain how to do it.

		subversion.authz.file.path : File path to the file used in subversion to define
		                             the security rights between repositories and users.
		                             [PATH/authz.txt]
		                             
		subversion.repository.base.path : Directory that contains all the subversion repository.
		
		subversion.create.repository.cmd : Command line that will be executed by the application server
		                                   (The user that is running the application server) to create a new repository.
		                                   At the end of that line will be added the name of this repository.

		subversion.rename.repository.cmd : Command line that will be executed by the application server
                                           (The user that is running the application server) to rename an existing repository.
                                           At the end of that line will be added the name of the old repository and the new name.

  a) create a directory for the LibreSource indexation (kernel.indexationDataDir)
  b) create a directory for the LibreSource file exchange (libresource.distributedFilesystem)
  c) give to the postgres group the right to use these folders
     sudo chgrp postgres tmp/files tmp/index
     sudo chmod g+rwx tmp/files tmp/index
  
  - Copy this file to the directory JBOSS/server/default/deploy/

2) Database access (libresourceDS-ds.xml)
  - If you did not generate the datasource from the build process, edit the file in order to 
    configure the url, user and password to access to your Postgres database.
    
	    connection-url
	    user-name
    	password
    
  - The file content bellow is given as information
    
	<datasources>
	  <local-tx-datasource>
    	<jndi-name>libresourceDS</jndi-name>
	    <connection-url>jdbc:postgresql://localhost:5432/libresource</connection-url>
    	<driver-class>org.postgresql.Driver</driver-class>
	    <user-name>postgres</user-name>
    	<password>postgres</password>
	    <metadata>
         <type-mapping>PostgreSQL 8.0</type-mapping>
        </metadata>
	  </local-tx-datasource>
	</datasources>

	
  - Copy this file to the directory JBOSS/server/default/deploy/
  
3) Mail Notifications (libresourceMail.properties) [OPTIONAL]
  - If you did not generate the MailSession from the build process, edit the file in order to 
    configure the mail.from and your smtp host to send mail.

		<property name="mail.smtp.host" value="smtp.XXXXX.XX"/>
        <property name="mail.from" value="notification@dev.libresource.org"/>

  - The file content bellow is given as information
  
	  <mbean code="org.jboss.mail.MailService" name="jboss:service=libresourceMail">
	    <attribute name="JNDIName">java:/libresourceMail</attribute>
    	<attribute name="User">nobody</attribute>
	    <attribute name="Password">password</attribute>
	    <attribute name="Configuration">
    	   <configuration>
        	  <!-- Change to your mail server prototocol -->
	          <property name="mail.store.protocol" value="pop3"/>
    	      <property name="mail.transport.protocol" value="smtp"/>

        	  <!-- Change to the user who will receive mail  -->
	          <property name="mail.user" value="nobody"/>

    	      <!-- Change to the mail server  -->
        	  <property name="mail.pop3.host" value=""/>

	          <!-- Change to the SMTP gateway server -->
    	      <property name="mail.smtp.host" value="XXXXXXXXXXXXXXXXXXXXXXXX"/>

        	  <!-- Change to the address mail will be from  -->
	          <property name="mail.from" value="XXXXXXXXXXXXXXXXXXXXXXXXXXXXX"/>

    	      <!-- Enable debugging output from the javamail classes -->
        	  <property name="mail.debug" value="false"/>
	       </configuration>
    	   <depends>jboss:service=Naming</depends>
	    </attribute>
	  </mbean>
	  
  - If you want mail notification, copy this file to the directory JBOSS/server/default/deploy/
  
4) Deployement of the ear
  - Copy the file LibreSource-VERSION.ear in the directory JBOSS/server/default/deploy/


# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
# Starting/Stoping JBoss/Libresource
# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Under Windows:
 - To start: JBOSS/bin/run.bat
 - To stop: JBOSS/bin/shutdown.bat
 
Under Linux:
 - To start: JBOSS/bin/run.sh
 - To stop: JBOSS/bin/shutdown.sh

Default URL used:
 - http://localhost:8080/
 
# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
# Optimization
# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

 - Depending the amount of memory you have : 
  export JAVA_OPTS="$JAVA_OPTS -server -Xms768m -Xmx768m"

  - For long execution of the server, we recommand you to execute these commands periodically :
    + vacuumdb -f libresource
      ++ you can, for example, use the cron daemon with the following crontab :
           1       1       *       *       *       vacuumdb -f -a