Installation¶

App Suite Proxy is a plain standalone Java application. The preferred way of running it however, is using the official Docker image or building own images based on the official ones.

Docker¶

Docker images are currently only available OX-internally using the Gitlab registry gitlab.open-xchange.com:4567/middleware/appsuite-proxy. As soon as OX provides a public registry for official Docker images, App Suite Proxy release images will be published there.

Supported tags¶

Latest versions: latest always gives you the most recent official release. In addition <major>.<minor>-latest (e.g. 1.2-latest) to always get the latest patch release of the according minor release.
Pinned versions: <major>.<minor>.<patch>, e.g. 1.2.0
Development snapshots
- develop: Bleeding edge, always points to the latest successful build on develop branch
- release-<version>: Always points to the latest successful build on a certain release branch
- <major>.<minor>.<patch>-<commit>, e.g. 1.2.0-1d3c4dc: A concrete snapshot build based on a develop commit`

How to use this image¶

In general:

docker run -dit -p 8080:8080 <image>

Configuration¶

The most important configuration settings can be provided as environment variables, for example PROXY_TLS_ENABLED. See the according configuration sections in this documentation. Any documented setting that has an according “EnvVar” annotation can be set as such.

If you need to set settings where no environment variable is available, it is advised to mount an application.properties file:

docker run --mount type=bind,source=/path/to/application.properties,target=/opt/open-xchange/appsuite-proxy/etc/application.properties,readonly [...]

File-based configuration like routing.yml, backends.yml, sharding.yml and logback.xml are always supposed to be mounted in the way as described above. The same is true for Zuul Groovy filters, for which the target path is /opt/open-xchange/appsuite-proxy/filters/(inbound|outbound|endpoint).

If you want to change your global log level in a docker container setup there is the possibility to set it on container startup. Use the environment variable GLOBAL_LOG_LEVEL=DEBUG to enable debug logging.

Build from source¶

Docker¶

Easiest is again to use docker by building an up-to-date image locally:

./gradlew buildImage

Plain Java on Linux¶

Follow the tutorial found in the README.md file to build an archive. Extract the archive into folder /opt/open-xchange/ and continue with the setup of groups and users.

Create a symlink to simplify later version changes and permission settings:

ln -s appsuite-proxy-<proxy_version> /opt/open-xchange/appsuite-proxy

Note

At the moment there is no distribution package available for the App Suite Proxy. This will change as soon as the first release is published. There will also be full docker images available by then.

Create permissions

Create an own system user alongside a dedicated group to run the later created App Suite Service.

Create a dedicated group:

groupadd -r appsuite-proxy

Create system user without login or home:

useradd -g appsuite-proxy appsuite-proxy

Set permissions:

chown -R appsuite-proxy:appsuite-proxy /opt/open-xchange/appsuite-proxy/bin/appsuite-proxy
chmod -R 650 /opt/open-xchange/appsuite-proxy/bin/appsuite-proxy
chown -R appsuite-proxy:appsuite-proxy /opt/open-xchange/appsuite-proxy/etc/
chmod -R 640 /opt/open-xchange/appsuite-proxy/etc/

Create logging folder:

mkdir /var/log/open-xchange/appsuite-proxy
chgrp appsuite-proxy /var/log/open-xchange/appsuite-proxy
chmod -R 750 /var/log/open-xchange/appsuite-proxy

Create service

Create a systemd service unit to control the process. For this purpose, create a file appsuite-proxy.service in directory /etc/systemd/system followed by a systemctl daemon-reload.

appsuite-proxy.service:

[Unit]
Description=appsuite-proxy
After=syslog.target
After=network.target

[Service]
User=appsuite-proxy
ExecStart=/opt/open-xchange/appsuite-proxy/bin/appsuite-proxy
SuccessExitStatus=143
LimitNOFILE=65536
LimitNPROC=65536

[Install]
WantedBy=multi-user.target