.. _install-prerequisites:

==============
Prerequisites
==============

Operating system
================

A 64-bit Linux distribution with ``systemd`` as the service manager.
The server is tested on RHEL 9 and its rebuilds (Rocky, AlmaLinux),
and on Debian 12 / Ubuntu 22.04 LTS or newer. Any distribution that
provides a JDK 21 and a working ``systemd`` should be fine.

Java runtime
============

A **JDK 21 (LTS)** runtime is required. Eclipse Temurin is
recommended; other vendor builds (Azul Zulu, Amazon Corretto,
RedHat build of OpenJDK) work equally well. The server will refuse
to start on older major versions.

Confirm the installed version::

    $ java -version
    openjdk version "21.0.x" 2024-xx-xx LTS

The JDK does not need to be on the shell ``PATH`` for the service
itself - the systemd unit can reference the ``java`` binary by
absolute path.

Disk space
==========

Two directories need to be planned for:

* **Installation directory** (e.g. ``/opt/toa-server``) - holds the
  fat jar, the ``config/`` folder and the bundled README. A few tens
  of megabytes.

* **Data root** (``toa-server.dataRoot`` in the configuration) - holds
  every received import until it is either forwarded to the storage
  server and cleaned up, or retained for audit. Size this directory
  for the expected mail volume and retention window; the on-disk
  layout is one folder per import day (see :ref:`operate-data-layout`).
  The data root and the installation directory may live on different
  filesystems.

A few hundred MB of RAM is enough for a basic install; a 1 GB heap
(``-Xmx1g``) is a comfortable starting point and covers bursts of
large EML uploads (single upload is capped at 100 MB by default).

Network
=======

The server itself listens on a single HTTP port (default ``8080``,
configurable through ``server.port``) and is designed to sit behind a
reverse proxy that terminates TLS and serves the Outlook add-in task
pane on the same origin. The reverse proxy then forwards ``/api/*``
requests to the TOA server - see :ref:`client-hosting` for a full
nginx example.

The server does **not** terminate TLS itself. Exposing the raw
``:8080`` port to the internet is not supported.

Outbound connectivity required by the server:

* **Storage server** (e.g. Damis) - HTTP(S) endpoint configured per
  domain under ``storageServer.url``. Reachable from the server host.
* **Template catalogue URL** (optional) - if any domain uses
  ``templates.url`` to fetch its cmserver XML, the server must be
  able to reach that URL on startup and at the configured refresh
  interval.

No inbound or outbound database connections are required. The server
persists all state on the local filesystem under ``dataRoot``.

Service account
===============

It is strongly recommended to run the server as a dedicated,
non-login system user (e.g. ``toa-server``). The user needs:

* read access to the installation directory;
* read-write access to the data root;
* no shell login (``/sbin/nologin`` or ``/usr/sbin/nologin``);
* no elevated privileges - the server never binds to a privileged
  port; the reverse proxy does that.

The concrete account creation command is shown in :ref:`install-server`.

Artifactory access
==================

The release artefacts are distributed through the LightComp
Artifactory instance. The customer receives a dedicated account with
read access to the ``distributions`` repository (base URL
``https://artifactory.lightcomp.cz/artifactory/distributions/``).
The credentials are delivered separately and are not documented
here.