.. _install-server:

======================
Installing TOA server
======================

This section describes a first-time install on a Linux host. The
outline is:

#. download the release zip from Artifactory,
#. unpack it under ``/opt``,
#. create a dedicated service account and the data root,
#. edit ``config/toa-server.yml``,
#. register a ``systemd`` unit and start the service.

All commands below are shown as ``root``; adjust with ``sudo`` as
needed for the target distribution.

Obtaining the release
=====================

The release bundle is published to LightComp Artifactory. With the
customer's Artifactory account, download the desired version of
``toa-server-<version>-dist.zip`` from:

.. code-block:: text

   https://artifactory.lightcomp.cz/artifactory/distributions/
       com/lightcomp/tahiti/office-addon/toa-server/<version>/

For example, with ``curl`` and a netrc-stored credential::

    curl -n -O \
      https://artifactory.lightcomp.cz/artifactory/distributions/com/lightcomp/tahiti/office-addon/toa-server/1.0.0/toa-server-1.0.0-dist.zip

The zip expands to a single top-level folder ``toa-server-<version>/``
containing the fat jar, a ``config/`` folder with a sample
configuration, and a short ``README.txt``.

Unpacking
=========

Install under ``/opt``:

.. code-block:: console

   # unzip /tmp/toa-server-1.0.0-dist.zip -d /opt/
   # ln -s /opt/toa-server-1.0.0 /opt/toa-server

Using a version-suffixed directory together with a stable
``/opt/toa-server`` symlink makes upgrades straightforward (see
:ref:`install-upgrade`). The service unit below always points at the
symlink and never needs editing for a version bump.

Service account and data root
=============================

Create the system user and the data directory. The data root can
live anywhere you have space; ``/var/lib/toa-server/data`` is a
reasonable default on a single-purpose host.

.. code-block:: console

   # useradd --system --shell /usr/sbin/nologin --home /opt/toa-server toa-server
   # mkdir -p /var/lib/toa-server/data
   # chown -R toa-server:toa-server /var/lib/toa-server
   # chown -R root:toa-server /opt/toa-server-1.0.0
   # chmod -R g+rX /opt/toa-server-1.0.0

The installation directory is owned by ``root`` and only readable by
the service user - the server never needs to write into it.

Configuration
=============

Edit ``/opt/toa-server/config/toa-server.yml`` and set at least:

* ``toa-server.dataRoot`` - absolute path to the data root created
  above (``/var/lib/toa-server/data``).
* ``toa-server.domains`` - at least one entry with its ``code``,
  ``name`` and a ``templates`` source (local ``path`` or remote
  ``url``). Full reference is in :ref:`configure`.
* ``toa-server.cors.allowed-origins`` - leave empty for the
  production setup where the task pane and the API share one origin
  behind the reverse proxy (see :ref:`client-hosting`). Populate it
  only if you deliberately host the task pane on a different origin.

A minimal file looks like:

.. code-block:: yaml

   toa-server:
     dataRoot: /var/lib/toa-server/data
     domains:
       - code: production
         name: Production domain
         templates:
           url: https://cmserver.customer.cz/cmserver2.xml
           refresh: 24h
         storageServer:
           url: https://damis.customer.cz/damis/upload
           domain: b2

Further configuration options are documented in :ref:`configure`.

.. note::

   The configuration file is parsed by Spring Boot and supports both
   YAML and ``application.properties`` syntax. Keep the filename
   ``toa-server.yml``; the packaged launch command references it
   directly.

systemd unit
============

Create ``/etc/systemd/system/toa-server.service``:

.. code-block:: ini

   [Unit]
   Description=Tahiti Outlook Add-in Server
   After=network-online.target
   Wants=network-online.target

   [Service]
   Type=simple
   User=toa-server
   Group=toa-server
   WorkingDirectory=/opt/toa-server
   ExecStart=/usr/bin/java \
       -Xmx1g \
       -jar /opt/toa-server/toa-server.jar \
       --spring.config.additional-location=file:/opt/toa-server/config/
   SuccessExitStatus=143
   Restart=on-failure
   RestartSec=5s

   # Hardening
   NoNewPrivileges=true
   PrivateTmp=true
   ProtectSystem=strict
   ProtectHome=true
   ReadWritePaths=/var/lib/toa-server

   [Install]
   WantedBy=multi-user.target

Notes on the unit:

* The ``ExecStart`` line references ``toa-server.jar``; create a
  convenience symlink inside the install directory so the jar
  filename does not need version-specific edits:

  .. code-block:: console

     # ln -s /opt/toa-server/toa-server-1.0.0.jar /opt/toa-server/toa-server.jar

* ``--spring.config.additional-location`` points at the config folder
  so the bundled ``toa-server.yml`` is loaded in addition to the
  defaults baked into the jar.
* ``ReadWritePaths`` is the only writable path exposed through
  ``ProtectSystem=strict``; adjust it if you chose a different data
  root.
* ``-Xmx1g`` is a starting point - revisit once real traffic volume
  is known.

Enabling and starting the service:

.. code-block:: console

   # systemctl daemon-reload
   # systemctl enable --now toa-server.service
   # systemctl status toa-server.service

Reverse proxy
=============

Once the service is up on port 8080, put it behind the same HTTPS
reverse proxy that serves the Outlook add-in bundle. The proxy
configuration and a complete nginx example are in
:ref:`client-hosting`. Summary:

* TLS is terminated by the reverse proxy;
* the proxy forwards ``/api/*`` to ``http://127.0.0.1:8080/``;
* the task pane and the API share one origin - no CORS is needed.

Windows Server deployments
==========================

Running the same fat jar on Windows Server as a service is
supported but intentionally out of scope for this revision of the
documentation. It will be added once the canonical Windows service
wrapper and deployment path are finalised. Customers who need a
Windows deployment in the interim are asked to contact support.