AppSuite:Upgrade from 6.22 Debian 6.0

Update of Open-Xchange Server v6.22 to OX App Suite on Debian GNU/Linux 6.0

This document describes updating an OX 6 Server installation from version 6.22 to OX App Suite.

Supported update path

Updates from an OX6 installation to OX App Suite (any version) are only possible from 6.22. If you have an earlier version of Open-Xchange Server 6 installed, please update at least to OX6 v6.22.0 before attempting an update to OX App Suite. See Open-Xchange 6.20 to 6.22 Update Guide for Debian 6.0 for instructions regarding that update.

Requirements

• An Open-Xchange Server installation v6.22.0 or later. This update guide is valid for a system installed through our Download and Installation Guide for Debian GNU/Linux 6.0 (Squeeze)
• If you have custom packages done by Open-Xchange, please discuss with your Open-Xchange contact when these packages are available for OX App Suite 7. Do not attempt the update earlier.
• Custom packages built for 6.22.1 or earlier might not work with OX App Suite 7.0.
• As for every update we strongly recommend that you make a backup of your system(s) before you proceed.

Update Open-Xchange Repositories

We start by adding some App Suite repos to our sources.list.

# adjust your existing repository list with the new locations
deb http://software.open-xchange.com/products/appsuite/stable/backend/DebianSqueeze/ /
deb http://software.open-xchange.com/products/appsuite/stable/appsuiteui/DebianSqueeze/ /

Updating repositories and update packages

Reload the package index:

$ apt-get update

Download and update all installed packages:

$ apt-get dist-upgrade

Please note: For some config files, the following interaction dialog may occur:

Configuration file `/opt/open-xchange/etc/hazelcast.properties'
 ==> File on system created by you or by a script.
 ==> File also in package provided by package maintainer.
   What would you like to do about it ?  Your options are:
    Y or I  : install the package maintainer's version
    N or O  : keep your currently-installed version
      D     : show the differences between the versions
      Z     : start a shell to examine the situation
 The default action is to keep your current version.
*** hazelcast.properties (Y/I/N/O/D/Z) [default=N] ? 

Chose Y to install the new version. Check later no manual changes have been screwed. You can do this by comparing the new (installed) config file with the dpkg.old files created by dpkg.

One configuration setting is to be made manually:

# vi /opt/open-xchange/etc/cluster.properties
com.openexchange.cluster.name=oxcluster

IMPORTANT: Please be extremely careful when executing apt-get autoremove after the upgrade. On some test systems packages were marked for automatic removal even if they were still needed.

To remove a package from the autoremove list, you can use:

$ apt-mark unmarkauto package1 [package2 [package3 [...]]]

Restart Open-Xchange

To restart Open-Xchange Server after the update, run

$ /etc/init.d/open-xchange restart

You might want to check with

$ ps aux | grep open-xchange

that there is exactly one newly spawned process running Open-Xchange Server.

Now the backend has been upgraded to the latest stable OX App Suite backend.

Update the OX6 frontend

The OX6 frontend needs to get updated to the latest OX6 version to work with the latest OX App Suite backend. While older OX6 frontends may work up to a certian degree, the only fully working and supported OX6 frontend to a given OX App Suite backend is the OX6 frontend version released together with this OX App Suite backend.

The first supported combination of OX6 frontend with OX App Suite backend was 6.22.2 and 7.0.2.

Upon the first connection after the backend update, you will get the message Error: updating database, try later. The second try should succeed.

Add the App Suite UI

# apt-get install open-xchange-appsuite open-xchange-appsuite-backend open-xchange-appsuite-manifest

Then, you need to adjust Apache's service configuration.

Before all, you need to decide whether whether you want to replace AJP by Grizzly now, or later. AJP is deprecated with OX App Suite 7.4 and will be discontinued with OX App Suite 7.6 in November 2014. For more information, see AppSuite:Grizzly. If you want to stick for the moment with AJP, you need to adjust its configuration nevertheless. We encourage you to swith to Grizzly.

Furthermore, you need to adjust the default.conf file. Basically you need to merge the OX6 and App Suite versions of those files.

Sample versions of those files are given in the following.

# /etc/apache2/sites-available/default
<VirtualHost *:80>
       ServerAdmin webmaster@localhost
 
       DocumentRoot /var/www/
 
       <Directory /var/www/>
               Options Indexes FollowSymLinks MultiViews
               AllowOverride None
               Order allow,deny
               allow from all
               RedirectMatch ^/$ /appsuite/
       </Directory>
 
       <Directory /var/www//appsuite>
               Options None +SymLinksIfOwnerMatch
               AllowOverride Indexes FileInfo
       </Directory>
 
       ErrorLog ${APACHE_LOG_DIR}/error.log
 
       # Possible values include: debug, info, notice, warn, error, crit,
       # alert, emerg.
       LogLevel warn
 
       CustomLog ${APACHE_LOG_DIR}/access.log combined
 
       # deflate
       AddOutputFilterByType DEFLATE text/html text/plain text/javascript application/javascript text/css text/xml application/xml text/x-js application/x-javascript

       # pre-compressed files
       AddType text/javascript .jsz
       AddType text/css .cssz
       AddType text/xml .xmlz
       AddType text/plain .po
 
       AddEncoding gzip .jsz .cssz .xmlz
       SetEnvIf Request_URI "\.(jsz|cssz|xmlz)$" no-gzip
 
       ExpiresActive On
 
       <Location /ox6>
                # Expires (via ExpiresByType to override global settings)
                ExpiresByType image/gif "access plus 6 months"
                ExpiresByType image/png "access plus 6 months"
                ExpiresByType image/jpg "access plus 6 months"
                ExpiresByType image/jpeg "access plus 6 months"
                ExpiresByType text/css "access plus 6 months"
                ExpiresByType text/html "access plus 6 months"
                ExpiresByType text/xml "access plus 6 months"
                ExpiresByType text/javascript "access plus 6 months"
                ExpiresByType text/x-js "access plus 6 months"
                ExpiresByType application/x-javascript "access plus 6 months"
                ExpiresDefault "access plus 6 months"
                Header append Cache-Control "private"
                Header unset Last-Modified
                Header unset Vary
                # Strip version
                RewriteEngine On
                RewriteRule v=\w+/(.+) $1 [L]
                # Turn off ETag
                Header unset ETag
                FileETag None
       </Location>
 
       <Location /ox6/ox.html>
                ExpiresByType text/html "now"
                ExpiresDefault "now"
                Header unset Last-Modified
                Header set Cache-Control "no-store, no-cache, must-revalidate, post-check=0, pre-check=0"
                # Turn off ETag
                Header unset ETag
                FileETag None
       </Location>
 
       <Location /ox6/index.html>
                ExpiresByType text/html "now"
                ExpiresDefault "now"
                Header unset Last-Modified
                Header set Cache-Control "no-store, no-cache, must-revalidate, post-check=0, pre-check=0"
                # Turn off ETag
                Header unset ETag
                FileETag None
       </Location>
 
</VirtualHost>

# /etc/apache2/conf.d/proxy_ajp.conf
# Please note that the servlet path to the soap API has changed:
 <Location /webservices>
     # restrict access to the soap provisioning API
     Order Deny,Allow
     Deny from all
     Allow from 127.0.0.1
     # you might add more ip addresses / networks here
     # Allow from 192.168 10 172.16
 </Location>
 # the old path is kept for compatibility reasons
 
<Location /servlet/axis2/services>
    # restrict access to the soap provisioning API
    Order Deny,Allow
    Deny from all
    Allow from 127.0.0.1
    # you might add more ip addresses / networks here
    # Allow from 192.168 10 172.16
</Location>
 
 
<IfModule mod_proxy_ajp.c>
   ProxyRequests Off
   <Proxy balancer://oxcluster>
       Order deny,allow
       Allow from all
       # multiple server setups need to have the hostname inserted instead localhost
       BalancerMember ajp://localhost:8009 timeout=100 smax=0 ttl=60 retry=60 loadfactor=50 route=OX1
       # Enable and maybe add additional hosts running OX here
       # BalancerMember ajp://oxhost2:8009 timeout=100  smax=0 ttl=60 retry=60 loadfactor=50 route=OX2
       ProxySet stickysession=JSESSIONID
   </Proxy>
 
   # OX AppSuite frontend
   <Proxy /appsuite/api>
       ProxyPass balancer://oxcluster/ajax
   </Proxy>
 
   <Proxy /ajax>
       ProxyPass balancer://oxcluster/ajax
   </Proxy>
   <Proxy /servlet>
       ProxyPass balancer://oxcluster/servlet
   </Proxy>
   <Proxy /infostore>
       ProxyPass balancer://oxcluster/infostore
   </Proxy>
   <Proxy /publications>
       ProxyPass balancer://oxcluster/publications
   </Proxy>
   <Proxy /Microsoft-Server-ActiveSync>
       ProxyPass balancer://oxcluster/Microsoft-Server-ActiveSync
   </Proxy>
   <Proxy /usm-json>
       ProxyPass balancer://oxcluster/usm-json
   </Proxy>
   <Proxy /webservices>
       ProxyPass balancer://oxcluster/webservices
   </Proxy>
</IfModule>

After this, stop and start the apache2 and open-xchange services. Then you should be able to use the App Suite UI.

Remove the OX6 GUI

This step is optional. You may just skip it and offer both GUIs, the OX6 GUI and the App Suite GUI. (This is only supported with OX6 v6.22.2 and later.)

If you want to uninstall the OX6 GUI, this step consists of removing the OX6 GUI packages and adjusting Apache's configuration.

The packages to be removed can be identified by their version number in the output of dpkg -l | grep open-x. It will probably boil down to uninstall everything which starts with open-xchange-gui, as the names of the App Suite UI packages start with open-xchange-appsuite.

# apt-get remove open-xchange-gui*

After deinstallation of the OX6 GUI packages, adjust the /etc/apache2/sites-available/default file to remove obsolete stuff which was required for the OX6 GUI, but is not required by the App Suite UI. To do so, you may consult the Installation Guide for OX Appsuite to learn which sections of the file are required for an App Suite UI.

The AJP or Grizzly configuration will not require adjustments; the settings for App Suite are a superset of the settings of the OX6 GUI.

Leftover configuration files and runtime data

After the update you may see leftover configuration files and runtime data below /opt/open-xchange/etc.

Some of these files belong to packages which have been uninstalled during the update, they are marked with the status rc in the output of dpkg -l. You can remove these packages with the command

$ dpkg --purge <packagename>

Other orphaned files may be runtime data or temporary files which do not belong to any package and therefore couldn't be removed during the package update.

Finally, there may be backup files created by the package manager during earlier updates.

It is safe to remove all files ending in .dpkg-bak or .dpkg-remove