2.2. Installing TOA server

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

  1. download the release zip from Artifactory,

  2. unpack it under /opt,

  3. create a dedicated service account and the data root,

  4. edit config/toa-server.yml,

  5. register a systemd unit and start the service.

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

2.2.1. 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:

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.

2.2.2. Unpacking

Install under /opt:

# 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 Upgrading an existing installation). The service unit below always points at the symlink and never needs editing for a version bump.

2.2.3. 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.

# 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.

2.2.4. 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 Configuration.

  • 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 Hosting the task pane). Populate it only if you deliberately host the task pane on a different origin.

A minimal file looks like:

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 Configuration.

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.

2.2.5. systemd unit

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

[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:

    # 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:

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

2.2.6. 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 Hosting the task pane. 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.

2.2.7. 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.