[EN] Installing an Open-Exchange with Docs and DAV Support on NGINX (Debian)

Open Exchange. Not only a great alternative to Google Calendar and GMail, but in its newest Version also GoogleDocs and OneDrive!

If you have ever extensively used Google you have come to love the easy nature of online collaborative editing in Sheets and Docs. Up until now you had to rely on one of the major online service for this kind of task. But since the newer Versions of Open Exchange these kinds of features are included in its free Community OX.

In the following Steps we will look at the installation and configuration of Open-Exchange with these features included:

Prerequisites

• A Debian Server (Jessie or Stretch. Wheezy might work with a little more fiddling)
• An installed MySQL Server (Install with apt-get install mysql-server)
• An installed Nginx Webserver (Install with apt-get install nginx)
• A Mailserver (Postfix + Dovecot)

Installation of Packages via APT

First create the File:

$ nano /etc/apt/preferences.d/ca-certificates-java.pref

And enter the following content. This pins the java certificates to the jessie-backports repository:

Package: ca-certificates-java
Pin: release a=jessie-backports
Pin-Priority: 501

After doing that we have to add the APT Repositories of Open-Exchange. This will allow us to install OX modules via apt-get. Create the file:

$ nano /etc/apt/sources.list.d/ox.list

In case you are using Debian Jessie use the following file content:

# Add the Jessie Backports if not already defined elsewhere
deb http:///debian jessie-backports main
# OX Deb
deb http://software.open-xchange.com/products/appsuite/stable/appsuiteui/DebianJessie/ /
deb http://software.open-xchange.com/products/appsuite/stable/backend/DebianJessie/ /
deb https://software.open-xchange.com/products/appsuite/stable/office/DebianJessie /
deb https://software.open-xchange.com/products/appsuite/stable/office-web/DebianJessie /
deb https://software.open-xchange.com/products/appsuite/stable/documentconverter-api/DebianJessie /
deb https://software.open-xchange.com/components/unsupported/oxldapsync/DebianJessie/ /
deb https://software.open-xchange.com/products/appsuite/stable/usm/DebianJessie /

If you are using Debian Stretch use these ones:

# OX Deb
deb http://software.open-xchange.com/products/appsuite/stable/appsuiteui/DebianStretch/ /
deb http://software.open-xchange.com/products/appsuite/stable/backend/DebianStretch/ /
deb https://software.open-xchange.com/products/appsuite/stable/office/DebianStretch/
deb https://software.open-xchange.com/products/appsuite/stable/office-web/DebianStretch /
deb https://software.open-xchange.com/products/appsuite/stable/documentconverter-api/DebianStretch/
deb https://software.open-xchange.com/components/unsupported/oxldapsync/DebianStretch/ /
deb https://software.open-xchange.com/products/appsuite/stable/usm/DebianStretch/

After this is ready, you can update your apt-repository with

$ apt-get update

and install the required open-xchange modules with:

$ 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 open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-dav

You will get some warnings about the packets not being verified, but thats okay.

Configuration

If you are not familiar with OX yet, here is a quick outline of things that we have to configure for everything to work properly:

The OX itself is a Java application. It is created and started by running the "oxinstaller" script. It is possible to run the oxinstaller multiple times and create several server instances with different names. This can be useful if you want to have completely different filestores and databases along with a completely different frontend URL. If this is not necessary it might suffice to work with different contexts only. A context is a subset of logins, meaning they have their own administrator account and are essentially split from other contexts but do still share the same database.

So say you have three different companies on your server. One is a large company with 1000 members and the other two are smaller ones. You might setup two server instances with the oxinstaller command and have one of the servers (again with its own file-storage and database) dedicated to the large company, while the other one is used by both of the remaining companies each one using their own context on the server instance.

Now that you have a basic understanding of what will be going on we are ready to configure our OX:

We will assume that you already have a MySQL Database up and running.

1. Change into the install directory

$ cd /opt/open-xchange/sbin/

2. Create the Configuration DB

This will hold information about our different server instances and their file-stores/databases. In theory you should be able to create a MySQL account with a database and just enter those credentials, but due to issues with the installer script that doesn't quite work. So it is recommended that you give the installer credentials to an account that has GRANT privileges so that the installer can create its own Database with respective user accounts.

$ ./initconfigdb --configdb-pass=db_password -a --mysql-root-user=user --mysql-root-passwd=root_password

Parameter                      | Default value
------------------------------------------------------------
--configdb-user                | openexchange
--configdb-pass                |
--configdb-host                | localhost
--configdb-port                | 3306
--configdb-dbname              | configdb
--addon-sql                    |
--mysql-root-user              | root
--mysql-root-passwd            |
NOTE: use "-a" to create SQL admin user using GRANT command

Where root-user/root-passwd is the mysql account that has permissions to create databases and their respective accounts and configdb-pass is the password for the newly created "openexchange" user that will have access to the "configdb" database (at least if you choose to not specify these values and keep their default).

3. Run the OX-Installer to create a Server instance

It is time to create a server instance. You can do this by running oxinstaller. In this step you will also define the superadmin account for this server instance. It will be needed to register the server, register a file-store, register a database and for creating a context!

$ ./oxinstaller --no-license --servername=oxserver --configdb-pass=db_password --master-pass=admin_master_password --servermemory 2048

Parameter               | Default value
-----------------------------------------------
--servername            |
--imapserver            | myserver.de
--smtpserver            | myserver.de
--mail-login-src        | login
--mail-server-src       | user
--transport-server-src  | user
--configdb-user         | openexchange
--configdb-pass         |
--configdb-readhost     | localhost
--configdb-writehost    | localhost
--configdb-dbname       | configdb
--servermemory          |
--clt-memory            | 50
--configdb-readport     | 3306
--configdb-writeport    | 3306
--tmpdir-path           | /var/spool/open-xchange/uploads
--master-pass           |
--master-user           | oxadminmaster
--jkroute               | APP1
--object-link-hostname  | myserver.de
--extras-link           | http://myserver.de/
--maxSession            | 0
--sessionDefLifeTime    | 3600000
--disableauth           |
--no-license            |
--add-license           |
--name-of-oxcluster     | myserver.de
--network-listener-host | localhost
--ajp-bind-port         |

no-license indicated that we are installing the community version. If you have an active subscription you can enter your license with the add-licence parameter. Note that some of the settings (like imap/smtpserver) will auto detect from an already installed postfix/dovecot server!

At this stage you will use master-pass to define the superadmin password for this server instance. You can also use master-user to change the name. Otherwise it will default to oxadminmaster. In addition to that you will need to specify the db connection to the config db with configdb-pass. If you modified the defaults at step 2, you will have to account for that here by using the other configdb parameters!

Two important settings you should definitely change are servername and servermemory.

The servername will not be publicly visible but is used to differentiate between the server instances. The servermemory is written as a number in MB and defines how many RAM the Java Application may use. This depends on the number of users but should be roughly lie between 2GB and 8GB.

After running oxinstaller you may restart the OX with

$ service restart open-xchange

4. Registering the Server

After installing and starting the server you will have to register it with the configuration database. Why? We don't know, it seems that this step could easily be bundled in with the oxinstaller. But in any case, we have to do it:

$ ./registerserver -n oxserver -A oxadminmaster -P admin_master_password

-A and -P are for defining the superadmin account and its password. After that we have to define the servername with parameter -n this has to be the same one we just used the oxinstaller in step 3!

5. Creating and registering a file-store

The server is now running and registered on our config database. We can now create and register the file-store and our database for this server instance, by first creating the folder and granting open-exchange access:

$ mkdir /some/folder/SomeWhere
$ chown open-xchange:open-xchange /some/folder/SomeWhere

Then registering the file-store with our superadmin account.
Note that the superadmin account binds the registering process to our specific server instance, so there is no need to specify the servername at this time.

$ ./registerfilestore -A oxadminmaster -P admin_master_password -t file:/var/opt/filestore -s 10000

 -A,--adminuser                       ? Admin username
 -P,--adminpass                       ? Admin password
 -t,--storepath                       * Path to store filestore contents in URI format e.g. file:/tmp/filestore
 -s,--storesize                         The maximum size of the filestore in MB. Default: 1000
 -x,--maxcontexts                     The maximum number of contexts. Default: 5000

Again -A and -P to specify the superadmin Account. After that you need to define the Path to the folder we just created by using the -t parameter. Additionally we can set a quota in MB with the -s parameter.

6. Creating and registering our Instance Database

The last step of our instance configuration will setting up a database for our ox server instance to use:

$ ./registerdatabase -A oxadminmaster -P admin_master_password -n oxdatabase -p db_password -m true

 -A,--adminuser                       ? Admin username
 -P,--adminpass                       ? Admin password
 -n,--name                                 * Name of the database
 -H,--hostname                           Hostname of the server
 -u,--dbuser                               Name of the user for the database
 -d,--dbdriver                           The driver to be used for the database. Default: com.mysql.jdbc.Driver
 -p,--dbpasswd                         * Password for the database
 -m,--master                         * Set this if the registered database is the master
 -M,--masterid                           If this database isn't the master give the id of the master here
 -x,--maxunit                             The maximum number of contexts in this database.. Default: 1000
 -l,--poolhardlimit                    Db pool hardlimit. Default: true
 -o,--poolinitial                     Db pool initial. Default: 0
 -a,--poolmax                             Db pool max. Default: 100
    --create-userdb-schemas                        A flag that signals whether userdb schemas are supposed to be pre-created

Once again -A and -P to specify the superadmin Account. -n defines the name of the database whereas -u and -p can be used to define the user account that should be used to connect to it. Beware that that this script wants to create the database itself, so just create the user and grant access to the database but do not create it. 

If you notice that something isn't quite working at this point, you can have a look in the ox logfile located at /var/log/open-xchange/open-xchange.log.0. It usually pretty verbose and lets you know if there is some connection problem with the database. In my case I needed to change the user permissions because ox wanted to create the database "openx_5" instead of "openx" (The name I chose for -n).

7. Creating a context and our first user

We are almost done, now we just have to create our context and its administrator and our first user.

$ ./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

-c,--contextid                       * The id of the context
-A,--adminuser                       ? master Admin user name
-P,--adminpass                       ? master Admin password
-N,--contextname                     context name
-u,--username                         * Username of the user
-d,--displayname                   * Display name of the user
-g,--givenname                       * Given name for the user
-s,--surname                           * Sur name for the user
-p,--password                         * Password for the user
-e,--email                               * Primary mail address
-l,--language                           Language for the user (de_DE,en_US)
-t,--timezone                           Timezone of the user (Europe/Berlin)
-q,--quota                               * Context wide filestore quota in MB.
   --extendedoptions                              Set this if you want to see all options, use this instead of help option
-L,--addmapping                       Add login mappings.Seperated by ","
-F,--destination-store-id   Create context in the given filestore
-D,--destination-database-id   Create context in the given database
   --config                                       Add user/context specific configuration, e. g. '--config/com.openexchange.oauth.twitter=false|true'
   --remove-config                                Remove user/context specific configuration, e. g. '--remove-config/com.openexchange.oauth.twitter'
   --access-combination-name   Access combination name

For the last time  -A and -P to specify the superadmin Account. -c will be used to specify our context id. This has to be unique! After that we use -u for the admin username, -d for the admin display name, -g for the admin given name, -s for the admin surname, -p for the admin password, -e for the Admins EMail and -q for the Admin Quota in MB.

The last thing that is left to do is create our first User which whom we will be able to login:

$ ./createuser -c 1 -A oxadmin -P admin_password -u testuser -d "Test User" -g Test -s User -p secret -e testuser@example.com

-c,--contextid                       * The id of the context
-A,--adminuser                       ? Admin username
-P,--adminpass                       ? Admin password
-u,--username                         * Username of the user
-d,--displayname                   * Display name of the user
-g,--givenname                       * Given name for the user
-s,--surname                           * Sur name for the user
-p,--password                         * Password for the user
-e,--email                               * Primary mail address
-l,--language                           Language for the user (de_DE,en_US)
-t,--timezone                           Timezone of the user (Europe/Berlin)
-x,--department                       Department of the user
-z,--company                             Company of the user
-a,--aliases                             Comma separated list of the email aliases of the user
   --access-combination-name   Access combination name
-f,--filestore                         The identifier for the file storage.
-o,--owner                                 The owner for the file storage. If no owner is given and f/filestore option is set, the user itself is taken as owner
-q,--quota                                 The file storage quota in MB for associated user.
   --addguipreferences         Add a GUI setting (key=value)
   --config                                       Add user/context specific configuration, e. g. '--config/com.openexchange.oauth.twitter=false|true'
   --remove-config                                Remove user/context specific configuration, e. g. '--remove-config/com.openexchange.oauth.twitter'

The options here are widely the same as with createcontext except -A and -P in this case does not refer to the superadmin of the server instance, but the context administrator we just created! Also Quota is optional at this point and will inherit the value from context if not explicitly overridden here.

Important!

As a huge part of the OX is the integration with your postfix/dovecot server. Depending on your configuration there you either login with only your username or the whole email. You can change these settings globally or you can use either a context or a specific user to override specific configuration values using the --config option! In any case it is important to know that your OX Password should be equal to your Mail password, so OpenExchange can use it to login to your IMAP!

Settings

After configuration we need to tweak some settings to enable our installed DAV and Docs modules and make Open-Exchange work with our Mailserver. So first go into the settings directory:

$ cd /opt/open-xchange/etc

After that open these files and configure them to your liking. As these are fairly well documented and easy to understand we will assume that should pose no further problem.

$ nano ./caldav.properties
$ nano ./carddav.properties
$ nano ./documents.properties

Finally open the Mail Settings:

$ nano ./mail.properties

This is where you configure OX to work with your mailserver by modifying the following settings. There are a lot more settings in this file, but these are the ones that specify the communication with your mailserver:

# If your Mailserver expects the whole "mail" or just the "login"
com.openexchange.mail.loginSource=mail
# If the OX Password is also the Mailserver Password. This can be "global"
com.openexchange.mail.passwordSource=session
# Either take the Mailserver from "user" or "global"
com.openexchange.mail.mailServerSource=global
# Either take the SMTP-Server from "user" or "global"
com.openexchange.mail.transportServerSource=global
# (Explanation down below*)
com.openexchange.mail.masterPassword=none
# If Mailserver is global, define it here
com.openexchange.mail.mailServer=imap://localhost:143
# If Mailserver is global, does it use tls?
com.openexchange.mail.mailStartTls=false
# If SMTP Server is global, define it here
com.openexchange.mail.transportServer=smpt://localhost:25
# If SMTP Server is global, does it use tld?
com.openexchange.mail.transportStartTls=false
# This should always be imap!
com.openexchange.mail.defaultMailProvider=imap

*Special Note It is possible to disconnect the OX Passwords from the Mailserver Logins. This can be done by creating a master user for the mailserver that has access to all accounts. If you have a setup like that, you can set the "passwordSource" to global and specify the "masterPassword".

Note All of these settings can be overridden on a context/user basis. Lets say you have one user inside your ox that uses an external mailserver, you can simply override the global config with these values, when creating the user at Step 7:

--config/com.openexchange.mail.mailServer=imap://server.com:143
--config/com.openexchange.mail.transportServer=smtp://server.com:25
--config/com.openexchange.mail.loginSource=mail

Settings up the Nginx Webserver

Author Note The Open-Exchange Wiki says that Nginx is not supported, but seeing as all the Apache2 configuration does is creating a proxy to the OX Java application, I don't see why we shouldn't use nginx here! So here is the config I am currently using:

# Define where the Java Application can be reached
# If you multiple Server you can Cluster them here
upstream oxserver
{
server 127.0.0.1:8009 weight=50;
}
server
{
# Listen on HTTP Port
listen 80;
# Listen on HTTPS Port
listen 443;
ssl_certificate /etc/letsencrypt/live/hostname/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/hostname/privkey.pem;
# These does not really matter as we proxy all Requests into the Java VM
root /var/www/404Error;
index index.html;
# This is your Servername PLEASE CHANGE
server_name my.open-exchange.com;
# Enable GZIP
gzip on;
gzip_types text/plain text/javascript application/javascript text/css text/xml application/xml text/x-js application/x-javascript;
gzip_vary off;
# Add SAMEORIGIN Header and MIME Types
add_header "X-Frame-Options" "SAMEORIGIN";
include mime.types;
types
{
text/cache-manifest appcache;
application/x-font-ttf ttf;
image/png xpng;
text/css less;
}
# / is always redirected to /appsuite
location = /
{
rewrite .* /appsuite/ permanent;
}
# IE 6/7/8 are not Supported and will get an Error Page
location = /appsuite/
{
if ($http_user_agent ~ "MSIE [6-8]")
{
rewrite .* /appsuite/unsupported.html permanent;
}
index ui;
}
# Define some Settings for the Frontent UI
location /appsuite/
{
# Always rewrite URLs to /appsuite if Resource not available
location ~ ^/appsuite/v=
{
rewrite ^/appsuite/v=[^/]*(/.*)$ /appsuite$1 last;
}
# Never Cache this
location ~ /(ui|core|signin)$
{
types { }
default_type text/html;
expires 0; # now
if_modified_since off;
etag off;
}
# Help Pages Fallback
location ~ ^(/appsuite/help(?:-.+)?/l10n)/([a-z_A-Z]+)(.+)
{
try_files $uri $uri/index.html $1/en_US$3 $1/en_US$3/index.html =404;
expires 182d; # Cache for 6 Month
add_header "Cache-Control" "private";
etag off;
}
# Icons Fallbak
location ~ ^(/appsuite/apps/themes)/.*/([^/]+)$
{
try_files $uri $1/icons/default/$2 =404;
expires 182d; # Cache for 6 Month
add_header "Cache-Control" "private";
etag off;
}
# Never cache this
location ~ /online\.js$
{
expires 0; # now
add_header "Cache-Control" "no-store, no-cache, must-revalidate, post-check=0, pre-check=0";
etag off;
}
# These are already GZIPED, so turn gzip off and let the browser know!
location ~ \.(jsz|cssz|xmlz)
{
gzip off;
types {
text/javascript jsz;
text/css cssz;
text/xml xmlz;
}
add_header "Content-Encoding" "gzip";
expires 182d; # Cache for 6 Month
add_header "Cache-Control" "private";
etag off;
}
# Default Caching if none of the above are true
expires 182d; # about 6 months
add_header "Cache-Control" "private";
etag off;
}
# Define the ProxyPass to the Upstream Java VM
location @oxserver
{
proxy_pass http://oxserver;
proxy_read_timeout 100s;
proxy_set_header Host $http_host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
# Define the ProxyPass to the Upstream Java VM. This is for ActiveSync (If you have an active Subscription) and need a higher Timeout!
location @eas_oxserver
{
proxy_pass http://oxserver;
proxy_read_timeout 1900s;
proxy_set_header Host $http_host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
# REWRITES
# REWRITES
# REWRITES
# Redirect /ajax /drive etc. into the OX Java VM
location ~* ^\/(ajax|drive|infostore|publications|realtime|servlet).*
{
error_page 418 = @oxserver; return 418;
}
# Special redirect for the API, this gets forwarded to /ajax
location /appsuite/api
{
rewrite ^/appsuite/api(.*) /ajax$1 last;
# error_page 418 = @oxserver; return 418;
}
# Route Webservices to the OX but only allow internal requests
location ~* ^\/(servlet\/axis2\/services|webservices).*
{
allow 127.0.0.1;
deny all;
error_page 418 = @oxserver; return 418;
}
# Route ActiveSync Requests to the EAS
location ~* ^\/(usm\-json|Microsoft\-Server\-ActiveSync).*
{
error_page 418 = @eas_oxserver; return 418;
}
# Route all different CalDAV and CardDAV URLs into the DAV servlet
location ~* ^\/(principals|Calendar|Reminders|DataAccess|DAVKit|Lightning|Adresboek|dataaccessd|Preferences|Adressbuch|AddressBook|CalendarStore|CalendarAgent|accountsd|Address\ Book|eM\ Client|OX\ Sync|CalDav|CardDav|CoreDAV).*
{
rewrite ^/(.*) /servlet/dav/$1 last;
error_page 418 = @oxserver; return 418;
}
# Reroute the .well-known Folder into the DAV servlet. This is required so that services can autodetect the CalDAV and CardDAV Properties!
location ~* ^\/\.well-known.*
{
rewrite ^/.well-known/caldav(.*) /servlet/dav/ last;
rewrite ^/.well-known/carddav(.*) /servlet/dav/ last;
error_page 418 = @oxserver; return 418;
}
# No .ht Files!
location ~ /\.ht
{
deny all;
}
}

For good measure you can do a restart on the OX and the Nginx Webserver. Do not forget to update your DNS accordingly, so you can access the Webserver.

Congratulations, you should have a fully running OX on Nginx now!