View source for AppSuite:Open-Xchange Installation Guide for Debian 11.0

{{Version|7.10.6}}

= OX App Suite on Debian GNU/Linux 11 =

{{QuickInstIntro|release=appsuite}}

= Requirements =

* Plain installed Debian GNU/Linux 11, no graphical tools required
* A supported Java Virtual Machine ([https://oxpedia.org/wiki/index.php?title=AppSuite:OX_System_Requirements#Server_Platforms learn more])
* A working internet connection
* vim is not installed by default on Debian. If you want to copy & paste the commands from this article into a shell window, you need to apt-get install vim first.

= Database installation =

Please consult our [[OXLoadBalancingClustering_Database#Standalone_database_setup|database installation instructions]] for information on how to install a database on the local system.

Before proceeding, make sure the local machine has got a working MySQL service in one of the supported versions / flavors with the configuration / tunings applied as mentioned on our [[My.cnf|corresponding page]].

= JRE Installation =

Debian Bullseye ships with OpenJDK 11 JRE, which is not suitable for OX App Suite. It is therefore required to install Eclipse Temurin 8 JRE with HotSpot VM. A comprehensive installation guide can be found at https://adoptium.net/de/installation/linux/#_deb_installation_on_debian_or_ubuntu. Quick instructions are:

 # install repo key
 $ wget -qO - https://packages.adoptium.net/artifactory/api/gpg/key/public | sudo apt-key add -
 
 # add repository
 $ cat << EOF > /etc/apt/sources.list.d/adoptopenjdk.list
 deb https://packages.adoptium.net/artifactory/deb/ buster main
 EOF

= Add Open-Xchange Repository =

Open-Xchange maintains public available software repositories for different platforms, such as Debian. This repository should be added to the Debian installation to enable simple installation and updates.

Start a console and modify the Debian repository information file. Also add the Open-Xchange software repository:

 $ cat << EOF >> /etc/apt/sources.list.d/open-xchange.list
 
 deb https://software.open-xchange.com/products/appsuite/stable/appsuiteui/DebianBullseye/ /
 deb https://software.open-xchange.com/products/appsuite/stable/backend/DebianBullseye/ / 
 
 # if you have a valid maintenance subscription, please uncomment the 
 # following and add the ldb account data to the url so that the most recent
 # packages get installed
 # deb https://[CUSTOMERID:PASSWORD]@software.open-xchange.com/products/appsuite/stable/appsuiteui/updates/DebianBullseye /
 # deb https://[CUSTOMERID:PASSWORD]@software.open-xchange.com/products/appsuite/stable/backend/updates/DebianBullseye /
 EOF

= Updating repositories and install packages =

It is highly recommended to import the Open-Xchange build key to your package systems trusted keyring in order to make sure only Open-Xchange packages with valid signing are installed on the system. Otherwise you'll encounter warnings about untrusted package sources. To import the Open-Xchange buildkey, please refer to this quick guide: [[Importing_OX_Buildkey#Importing_key_into_apt_based_systems|Importing OX Buildkey]].

Reload the package index. This will download the package descriptions available at the software repositories and will enable the Open-Xchange repository as a valid source for signed packages:

 $ apt-get update

The following command starts the download and installation process of all required package for Open-Xchange deployment:

If you want to install everything on a single server, just run

 $ apt-get install open-xchange open-xchange-authentication-database open-xchange-grizzly \
   open-xchange-admin open-xchange-appsuite \
   open-xchange-appsuite-backend open-xchange-appsuite-manifest

'''Note 1:''' You have to choose between one of the available authentication packages depending on your requirements.
Open-Xchange configuration

To avoid confusion right at the start notice that Open-Xchange uses multiple administration levels and requires different credentials at some stages at the installation and server management. Note that the passwords chosen at this guide are weak and should be replaced by stronger passwords.

The MySQL database user
* Username: openexchange
* Password used at this guide: db_password
* Responsibility: Execute all kinds of database operations

The Open-Xchange Admin Master
* Username: oxadminmaster
* Password used at this guide: admin_master_password
* Responsibility: Manage contexts, manage all kinds of low level server configuration

The Context Admin
* Username: oxadmin
* Password used at this guide: admin_password
* Responsibility: Manage users/groups/resources inside a context

As stated above we assume the MySQL service has been installed previously, and it is running and available.

A good idea is to add the Open-Xchange binaries to PATH:

 $  echo PATH=$PATH:/opt/open-xchange/sbin/ >> ~/.bashrc && . ~/.bashrc

Now we have to initialize the Open-Xchange configdb database. This can all be done by executing the initconfigdb script.

 $ /opt/open-xchange/sbin/initconfigdb --configdb-pass=db_password -a --mysql-root-passwd=root_password

Use the --mysql-root-passwd option to supply the MySQL root password as configured during database installation.

Add the -i option if you want to remove an already existing open-xchange configdb.

'''Note:''' The -a parameter adds an openexchange account to MySQL. This account will be used for database connections from the OX App Suite middleware and requires [https://oxpedia.org/wiki/index.php?title=AppSuite:DB_user_privileges some privileges]. You can also create that account manually [https://oxpedia.org/wiki/index.php?title=OXLoadBalancingClustering_Database#Creating_Open-Xchange_user during database installation / configuration], in which case you can (should) skip the -a parameter here.

Before starting any service, all basic configuration files need to be set up correctly. The --configdb-pass option indicates the password of the openexchange database user previously created, the --master-pass options specifies the password of the Open-Xchange adminmaster user that will be created when executing the oxinstaller script.

'''Important:''' You should have your Open-Xchange license code at hand. If you do not plan to license Open-Xchange, you can use the option --no-license instead. Please also check [https://oxpedia.org/wiki/index.php?title=OXReportClient OXReportClient] documentation for more information about configuring a supported and maintained Open-Xchange server.

'''Important:''' For MAX_MEMORY_FOR_JAVAVM a rule of thumb for simple installations is half available system memory. The value must be in MB. For example "1024" for 1GB .

 $ /opt/open-xchange/sbin/oxinstaller --add-license=YOUR-OX-LICENSE-CODE \
 --servername=oxserver --configdb-pass=db_password \
 --master-pass=admin_master_password --network-listener-host=localhost --servermemory MAX_MEMORY_FOR_JAVAVM

'''Note:''' In a clustered setup, --network-listener-host must be set to *

Now is a good time to configure the way OX will authenticate to your mail server. Edit the file /opt/open-xchange/etc/mail.properties and change the com.openexchange.mail.loginSource to use. This is very important for servers that require your full email address to log in with.

 # adjust com.openexchange.mail.loginSource
 $ vim /opt/open-xchange/etc/mail.properties

After initializing the configuration, restart the Open-Xchange Administration service by executing:

 $ systemctl restart open-xchange

Next we have to register the local server at the Open-Xchange configdb database:

 $ /opt/open-xchange/sbin/registerserver -n oxserver -A oxadminmaster -P admin_master_password

Now we have to create a local directory that should be used as Open-Xchange filestore. This directory will contain all Infostore content and files attached to groupware objects. To maintain access by the Open-Xchange Groupware service, it is required to grant permissions to the open-xchange system user.

 $ mkdir /var/opt/filestore
 $ chown open-xchange:open-xchange /var/opt/filestore

Now register the directory as a filestore at the Open-Xchange server:

 $ /opt/open-xchange/sbin/registerfilestore -A oxadminmaster -P admin_master_password \
 -t file:/var/opt/filestore -s 1000000

'''Note:''' You might want to adapt the value provided with -s, the "The maximum size of the filestore in MB", see registerfilestore --help.

'''Note 2:''' If you are setting up OX App Suite, you need a shared filestore accross your OX servers even though you do not plan to have the OX Files feature enabled for your customers.

Finally register the groupware database, this is a separated database where all groupware specific data is stored:

 $ /opt/open-xchange/sbin/registerdatabase -A oxadminmaster -P admin_master_password \
 -n oxdatabase -p db_password -m true

'''Note 3:''' Take into account that a global database is needed in order to store data across context boundaries. Please see this [https://oxpedia.org/wiki/index.php?title=AppSuite:CrossContextDatabase documentation] on how to register it.

= Configure services =

Now as the Open-Xchange Server has been set up and the database is running, we have to configure the Apache webserver and the mod_proxy_http module to access the groupware frontend. <!-- To gain better GUI performance, the usage of mod_expires and mod_deflate is strongly recommended. Those modules will limit the amount of client requests and compress the delivered content. -->

 $ a2enmod proxy proxy_http proxy_balancer expires deflate headers rewrite mime setenvif lbmethod_byrequests

Configure the mod_proxy_http module by creating a new Apache configuration file.

 $ vim /etc/apache2/conf-available/proxy_http.conf




 <IfModule mod_proxy_http.c>
    ProxyRequests Off
    ProxyStatus On
    # When enabled, this option will pass the Host: line from the incoming request to the proxied host.
    ProxyPreserveHost On
    # 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>
        Order Deny,Allow
        Deny from all
        Allow from 127.0.0.1
    </Location>
 
    # Enable the balancer manager mentioned in
    # https://oxpedia.org/wiki/index.php?title=AppSuite:Running_a_cluster#Updating_a_Cluster
    <IfModule mod_status.c>
      <Location /balancer-manager>
        SetHandler balancer-manager
        Order Deny,Allow
        Deny from all
        Allow from 127.0.0.1
      </Location> 
    </IfModule>
 
    <Proxy balancer://oxcluster>
        Order deny,allow
        Allow from all
        # multiple server setups need to have the hostname inserted instead localhost
        BalancerMember http://localhost:8009 timeout=100 smax=0 ttl=60 retry=60 loadfactor=50 route=APP1
        # Enable and maybe add additional hosts running OX here
        # BalancerMember http://oxhost2:8009 timeout=100 smax=0 ttl=60 retry=60 loadfactor=50 route=APP2
       ProxySet stickysession=JSESSIONID|jsessionid scolonpathdelim=On
       SetEnv proxy-initial-not-pooled
       SetEnv proxy-sendchunked
    </Proxy>
 
    # The standalone documentconverter(s) within your setup (if installed)
    # Make sure to restrict access to backends only
    # See: https://httpd.apache.org/docs/$YOUR_VERSION/mod/mod_authz_host.html#allow for more infos
    #<Proxy balancer://oxcluster_docs>
    #    Order Deny,Allow
    #    Deny from all
    #    Allow from backend1IP
    #    BalancerMember http://converter_host:8009 timeout=100 smax=0 ttl=60 retry=60 loadfactor=50 keepalive=On  route=APP3
    #    ProxySet stickysession=JSESSIONID|jsessionid scolonpathdelim=On
    #       SetEnv proxy-initial-not-pooled
    #    SetEnv proxy-sendchunked
    #</Proxy>
    # Define another Proxy Container with different timeout for the sync clients. Microsoft recommends a minimum value of 15 minutes.
    # Setting the value lower than the one defined as com.openexchange.usm.eas.ping.max_heartbeat in eas.properties will lead to connection
    # timeouts for clients.  See https://support.microsoft.com/?kbid=905013 for additional information.
    #
    # NOTE for Apache versions < 2.4:
    # When using a single node system or using BalancerMembers that are assigned to other balancers please add a second hostname for that
    # BalancerMember's IP so Apache can treat it as additional BalancerMember with a different timeout.
    #
    # Example from /etc/hosts: 127.0.0.1    localhost localhost_sync
    #
   # Alternatively select one or more hosts of your cluster to be restricted to handle only eas/usm requests
   <Proxy balancer://eas_oxcluster>
      Order deny,allow
      Allow from all
      # multiple server setups need to have the hostname inserted instead localhost
      BalancerMember http://localhost_sync:8009 timeout=1900 smax=0 ttl=60 retry=60 loadfactor=50 route=APP1
      # Enable and maybe add additional hosts running OX here
      # BalancerMember http://oxhost2:8009 timeout=1900  smax=0 ttl=60 retry=60 loadfactor=50 route=APP2
      ProxySet stickysession=JSESSIONID|jsessionid scolonpathdelim=On
      SetEnv proxy-initial-not-pooled
      SetEnv proxy-sendchunked
    </Proxy>
 
   # When specifying additional mappings via the ProxyPass directive be aware that the first matching rule wins. Overlapping urls of
   # mappings have to be ordered from longest URL to shortest URL.
   # 
   # Example:
   #   ProxyPass /ajax      balancer://oxcluster_with_100s_timeout/ajax
   #   ProxyPass /ajax/test balancer://oxcluster_with_200s_timeout/ajax/test
   #
   # Requests to /ajax/test would have a timeout of 100s instead of 200s 
   #   
   # See:
   # - https://httpd.apache.org/docs/current/mod/mod_proxy.html#proxypass Ordering ProxyPass Directives
   # - https://httpd.apache.org/docs/current/mod/mod_proxy.html#workers Worker Sharing
   ProxyPass /ajax balancer://oxcluster/ajax
   ProxyPass /appsuite/api balancer://oxcluster/ajax
   ProxyPass /drive balancer://oxcluster/drive
   ProxyPass /infostore balancer://oxcluster/infostore
   ProxyPass /realtime balancer://oxcluster/realtime
   ProxyPass /servlet balancer://oxcluster/servlet
   ProxyPass /webservices balancer://oxcluster/webservices
 
   #ProxyPass /documentconverterws balancer://oxcluster_docs/documentconverterws
 
   ProxyPass /usm-json balancer://eas_oxcluster/usm-json
   ProxyPass /Microsoft-Server-ActiveSync balancer://eas_oxcluster/Microsoft-Server-ActiveSync
 
 </IfModule>


Modify the default website settings to display the Open-Xchange GUI

 $ vim /etc/apache2/sites-enabled/000-default.conf
 
 <VirtualHost *:80>
        ServerAdmin webmaster@localhost
 
        DocumentRoot /var/www/html
        <Directory /var/www/html>
                Options -Indexes +FollowSymLinks +MultiViews
                AllowOverride None
                Order allow,deny
                allow from all
                RedirectMatch ^/$ /appsuite/
        </Directory>
 
        <Directory /var/www/html/appsuite>
                Options None +SymLinksIfOwnerMatch
                AllowOverride Indexes FileInfo
        </Directory>
 </VirtualHost>

If you want to secure your Apache setup via HTTPS (which is highly recommended) or if you have proxies in front of your Apache please follow the instructions at:

* [https://oxpedia.org/wiki/index.php?title=AppSuite:Grizzly#.2Fopt.2Fopen-xchange.2Fetc.2Fserver.conf Grizzly configuration] in general, and specifically:
* [https://oxpedia.org/wiki/index.php?title=AppSuite:Grizzly#X-FORWARDED-PROTO_Header X-FORWARDED-PROTO Header]
* [https://oxpedia.org/wiki/index.php?title=AppSuite:Grizzly#X-FORWARDED-FOR_Header X-FORWARDED-FOR Header]

to properly instruct the backend about the security status of the connection and the remote IP used to contact the backend.

Enable the proxy configuration

 $ a2enconf proxy_http.conf

After the configuration is done, restart the Apache webserver

 $ systemctl restart apache2

== Apache Setting for more concurrent Connections ==

By default apache2 is configured to support 150 concurrent connections. This forces all parallel requests beyond that limit to wait. Especially if, for example, active sync clients maintain a permanent connection for push events to arrive. The following article explains how that can be done

[https://oxpedia.org/wiki/index.php?title=Tune_apache2_for_more_concurrent_connections Apache Setting for more concurrent Connections]

= Creating contexts and users =

Now as the whole setup is complete and you already should get a login screen when accessing the server with a webbrowser, we have to setup a context and a default user as the last step of this tutorial.

The mapping defaultcontext will allow you to set this context as the default one of the entire system so that users which will be created within this context can login into Open-Xchange Server without specifying their domain at the login screen. Only one context can be specified as defaultcontext. The oxadmin user that will be created by this command is the default admin of the created context. This account will gather additional functions that are also described in the administration manual. The context id parameter must to be unique and numeric, otherwise the server will complain when you try to create a context. New contexts must be created by the oxadminmaster user, user accounts inside a context are created with the credentials of the contexts oxadmin account. The access-combination-name property defines the set of available modules and functions for users of the context.

 $ /opt/open-xchange/sbin/createcontext -A oxadminmaster -P admin_master_password -c 1 \
 -u oxadmin -d "Context Admin" -g Admin -s User -p admin_password -L defaultcontext \
 -e oxadmin@example.com -q 1024 --access-combination-name=groupware_standard

To create a user for testing purposes (Make sure the password you use here for the user is the same password as your email account or you will not be able to use the email module until it is set right):

 $ /opt/open-xchange/sbin/createuser -c 1 -A oxadmin -P admin_password -u testuser \
 -d "Test User" -g Test -s User -p secret -e testuser@example.com \
 --imaplogin testuser --imapserver 127.0.0.1 --smtpserver 127.0.0.1

Now connect to the server with a webbrowser and login using the credentials testuser / secret.

A complete overview about the different parameter is provided at the [https://oxpedia.org/wiki/index.php?title=OX_Permission_Level permission matrix].

If you need to migrate a batch of users and contexts at once, check the CSV Batch Import documentation [https://oxpedia.org/wiki/index.php?title=Csv_import page].

= Log files and issue tracking =

== Default logging mechanism ==

Whenever unexpected or erroneous behavior takes place, it will be logged depending on the configured loglevel. All logfiles are stored at the operating systems default location. Events triggered by the Open-Xchange Groupware services are logged to a rotating file open-xchange.log.0. Those files are the very first place to monitor.

 $ tail -f -n200 /var/log/open-xchange/open-xchange.log.0

== Alternative logging mechanisms ==

Apart from the default file logging mechanism, Open-Xchange supports logging via logback framework and therefore via syslog and/or logstash. This makes it possible to directly log to a local or remote syslog daemon or other services. Logback is highly customizable, please see the documentation below.

* [https://oxpedia.org/wiki/index.php?title=AppSuite:OX_Logging Logback configuration Guide OX App Suite]

[[Category: AppSuite]]