OPEN-XCHANGE - The Collaboration and Integration Environment (c) 2002-2005

This document describes briefly how to configure,
install the OPEN-XCHANGE Server and components.


  INDEX

  1. Basic Requirements
  2. Upgrades
  3. Configuration
  4. Compile
  5. Installation
  6. Post configuration and installation
  6.1 Database (PostgreSQL)
  6.2 Directory (OpenLDAP)
  6.3 Webserver and Servlet Engine (Apache and Tomcat)
  6.4 Open-Xchange config files
  6.5 Create user/group
  6.9 WebDAV
  7. Test Drive 
  7.1 Start Open-Xchange
  8. FAQ
  9. Documentation
  99. Finally
  


  ---------------------------------------



  1. Basic Requirements

     The following prerequisites exists to build OPEN-XCHANGE:
     
      - Java SDK >= 1.4 to compile (and run the application)
      - Apache Ant
      - make
      - C compiler (optional)
      - tar, gzip to unpack the package
      - jsdk.jar (Java Servlet Development Kit)
        (sometimes called servlet.jar or even servlet-2.*.jar
        and this file is shipped with Tomcat.)
      - Java Database Connectivity (JDBC) Driver, should be provided with your
        database
      - mail.jar (JavaMail API)
      - activation.jar (JavaBeans Activation Framework)
      - jdom.jar XML API
     
       
  2. Upgrades
  
     It can happen that we have to change the internal data format
     from one version to another. Mostly this will happen from a 
     developer branch to a maintainance branch. But this can also
     happen between minor versions. Until a maintenance branch
     is not marked with "secure upgrade", we highly recommend that
     you start with a clean system to avoid any errors and other
     related issues.
    
      
  3. Configuration
  
     Short version:
     
     ./configure ; make; make install
     
     Please note that this will only work if you have installed
     all needed libraries and your classpath environment is
     established  correct.
     
     Long version:
     
     The script
     
     ./configure
     
     will check that your system meets the requirements and provides
     several options for customizations.
     
     To get a complete list of options just run the script with the 
     help option:
     
     ./configure --help
     
     
     You can customize your build and installation by changing one
     or more options to the configure script. The most importend
     options will be explained below:
     
     --prefix=/PATH/TO/THE/FINAL/DESTINATION
     
     With the "prefix" option you can define that all files
     will be installed under the given directory.
     
     --enable-webdav
     
     Builds the WebDAV/XML interface and other interfaces like 
     the ical interaface
     
     --with-dbname=openexchange
     --with-dbuser=openexchange
     --with-dbpass=openexchange
     --with-dbhost=127.0.0.1
     
     This four options can be used to specify importend
     database parameters. If you set this options with 
     configure, some config files are written with the
     given parameters.  You can always change this
     parameters later on.
     
     --with-mailjar=/FULL/PATH/TO/FILE
     --with-activationjar=/FULL/PATH/TO/FILE
     --with-jdomjar=/FULL/PATH/TO/FILE
     --with-jsdkjar=/FULL/PATH/TO/FILE
     --with-jdbcjar=/FULL/PATH/TO/FILE
     
     Specifies the location where the libraries are stored.
     Please be sure that you do not use symbolic links because
     some people encountered strange errors by using symlinks.
     If you are getting compile errors, make sure that the
     files are readable for the current user. Another source
     of error is maybe that you are using a wrong version
     of the library.
     
     Please take a look to the Wiki to see which versions
     are currently tested and are marked as "working":
     
     http://www.open-xchange.org/oxwiki/WorkingLibraries
     
     If you have have noticed that you are using a library
     not mentioned in on the list, please do not hesitate
     and add it to help other users.
     
     Below you find an example "configure" we are using on one of
     our test systems:
     
     ./configure -prefix=/opt/open-xchange \
     --enable-webdav \
     --with-dbname=openexchange \
     --with-dbuser=openexchange \
     --with-dbpass=openexchange \
     --with-dbhost=127.0.0.1 \
     --with-mailjar=/usr/share/oxlibs/mail.jar \
     --with-activationjar=/usr/share/oxlibs/activation.jar \
     --with-jdomjar=/usr/share/oxlibs/jdom.jar \ 
     --with-xercesjar=/usr/share/oxlibs/xml-apis.jar \ 
     --with-jsdkjar=/usr/share/oxlibs/jsdk.jar \ 
     --with-jdbcjar=/usr/share/oxlibs/postgresql.jar
     
     
     Please note that there are several other options 
     that can help you to make the configuration and 
     installation easier - we do not mention everything
     here, but exploring the configure options maybe helps
     you to get a successful installation and a working
     solution.

     
  4. Compile
      
     Just write a simple to start the compile procedure:

     make

     You should not get any errors, warnings can be ignored.
     If you see any error, you should double check your options
     and maybe the configure shows you some helpful messages
     that can lead you into the right direction.
     
     
  5. Installation
     
     Become root, for example with
     
     su
      
     and install the application by typing
           
     make install

     You can now change to the PREFIX directory and check the
     correct installation.


  6. Post configuration and installation
  
     We expect that you have an existing database, directory
     server, a servlet engine an a mail server incl. SMTP and IMAP
     that can be used for the next steps. If not, we have created
     a section in the Open-Xchange Wiki where you maybe can find
     some helpful information for installation and configuration
     and we also invite YOU to participate. If YOU have made
     a successful installation or configuration please do not
     hesitate to help other people by providing those information.
     
     6.1 Database (PostgreSQL)
     
         If no database exists, create a new database (UNICODE)
	 and insert the initial database dump for the OPEN-XCHANGE.
	 You find the initial database dump right here:
	 
	 PREFIX/share/init_database.sql
	 
	 Please note that if you already have a database installed,
	 coming from an erlier Open-Xchange installation, we recommend
	 to drop the old database and re-create a new one to avoid
	 errors and unwanted side effects.
	 
	 ------   PostgreSQL specific -----
	 
	 Create the database openexchange:
	 
	 (perhaps you should do this as user "postgres")
	 
	 createdb -E UTF-8 -U openexchange openexchange
	 
	 Import the initial database dump for Open-Xchange
	 
	 psql -U openexchange < PREFIX/share/init_database.sql
	 
	 ------   PostgreSQL specific -----
	 	 
	 You have to run the script      
	 PREFIX/sbin/dbinit_ox
	 once to initiate the OX Folders 
	 and the default right templates.
	 
	 Additional information:
	 
	 http://www.open-xchange.org/oxwiki/Integrations
	 
     6.2 Directory (OpenLDAP)
     
         Open-Xchange makes use of the following standard schemas:

	 core.schema
         cosine.schema
	 nis.schema
	 inetorgperson.schema
	 
	 Also the final installation contains the necessary file
	 
	 PREFIX/share/openxchange.schema
	 
	 that must be included to your directory schema.
	 
	 To have a workinh directory server you should be also
	 import the initial directory ldif into your directory,
	 the file is located like shown below:
	 
	 PREFIX/share/init_ldap.ldif
	 
	 Both, the Open-Xchange groupware and the webmailer
	 require a file ldap.conf that should looks like this
	 example:
	 
	 # Open-Xchange ldap conf
	 host    127.0.0.1
	 base    dc=example,dc=org
	 
	 Please remember that both services needs this file:
	 
	 PREFIX/etc/groupware/ldap.conf
	 PREFIX/etc/webmail/ldap.conf

	 
	 ------ OpenLDAP specific -----
	 
	 Make sure that your LDAP Server has OpenLDAPaci enabled.
	
	 Your slapd.conf should contain the following schema includes:
	 
	 include         OPENLDAP_PREFIX/openldap/schema/core.schema
	 include         OPENLDAP_PREFIX/openldap/schema/cosine.schema
	 include         OPENLDAP_PREFIX/openldap/schema/nis.schema
	 include         OPENLDAP_PREFIX/openldap/schema/inetorgperson.schema
	 include         OPENLDAP_PREFIX/openldap/schema/openxchange.schema
	 
	 
	 Edit PREFIX/share/initial_ldap.ldif and change the password:
	 userPassword: {CRYPT}newmailadminpass
	 
	 HINT: You can generate a passwd with slappasswd
	 
	 Add the initial.ldif with

	 slapadd -l PREFIX/share/init_ldap.ldif

	 ------ OpenLDAP specific -----	

	 Additional information:
	 
	 http://www.open-xchange.org/oxwiki/Integrations
	 
     6.3 Webserver and Servlet Engine (Apache and Tomcat)
     
         According to the configuration parameters of "configure",
	 everything should be copied to the correct location.
	 This includes 
	 
	  - Perl login scripts
	  - Images, CSS and Javascripts
	  
	 The configuration and compile process should have
	 created two "war" files that can be deployed naturally
	 by most servlet engines (for example tomcat
	 provides a manager console for deployment) so that
	 you do not need to touch any configuration file
	 except the one for your httpd server.
	  
	 ------ Apache specific -----
	 
	 Apache must know that some urls are
	 handled by the servlet engine:
	 
	 (this example is for Apache with the jk2
	 connector and we used the file workers2.properties)
	 
	  
	 # Uri mapping
         [uri:/servlet/*]
	 worker=ajp13:localhost:8009
	 
	 Please note that this must be done for all
	 servlet related urls! 	 	  
	 
	 ------ Apache specific -----
	 
	 Additional information:
	 
	 http://www.open-xchange.org/oxwiki/Integrations	 
	  
     6.4 Open-Xchange config files
     
         Edit the file 
	 
	 PREFIX/etc/admintools.conf 
	 
         and change the settings to the settings according
	 to your directory server and database system
	 
     6.5 Create user/group
     
         You find some helpful script in the
	 
	 directory PREFIX/sbin/
     
	 To add an user exexute the following script
	 
         PREFIX/sbin/adduser_ox \
	 --username=john \
	 --passwd=password \
	 --name=john \ 
	 --sname=doe \
	 --maildomain=example.org \
	 --ox_timezone=Europe/Berlin

	 To add the neely created user to a group, execute the
	 script like the example below:
	 
         PREFIX/sbin/addgroup_ox \
	 --group=developers  	 
	 
  7. Test Drive 
  
     You have now installed the Open-Xchange Server. Open-Xchange
     consist of four components and you should be sure that all
     of them are installed properly to start the test.
     
     To be sure that everythings will work as expected
     we recommend to tail all importend log files:
     
      - groupware.log
      - sessiond.log
      - sessiond.log
      
      (this file can be found in the PREFIX/var/log/ directory)
      
      Additional log files where helpful information can be found:
      
      - httpd log file
      - servlet log file
      - database log file
      - directory log file
      - mail server log file

      7.1 Start Open-Xchange
       
          Now you are ready to start Open-Xchange with
      
          PREFIX/etc/init.d/openexchange start
	  
	  You should now be able to access Open-Xchange via
	  a browser:
	  
	  http://YOUR.OPEN-XCHANGE.IP/cgi-bin/login.pl	  
  
  8. FAQ

     Please refer the FAQ section www.open-xchange.org
     
     http://mirror.open-xchange.org/ox/EN/community/faq.htm
  

  9. Documentation

     additional information for integration, suported clients,
     language support, distributed environements, technical background,
     how to participate and many more can be found on the web page
     
     http://www.open-xchange.org

     
   
       
 99. Finally  
     
     The entire Open-Xchange Team wants to thank
     you for using this software.
     
     
     