.. _installation:

************
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