3.1. Server settings

The settings on this page apply to the server as a whole. Per-domain configuration lives under toa-server.domains[] and is documented in Domains.

3.1.1. Data root

toa-server:
  dataRoot: /var/lib/toa-server/data

toa-server.dataRoot is the filesystem directory under which every received import is stored. Each configured domain gets its own <dataRoot>/<code>/ subfolder, auto-created on startup. The path may be absolute (recommended) or relative to the server’s working directory.

The directory must exist (or its parent must exist so the server can create it) and must be writable by the service account. The recommended layout is documented in Installing TOA server; the on-disk structure is described in On-disk layout.

The key is required whenever at least one domain is configured. Without it the server refuses to start.

3.1.2. Data retention

toa-server:
  dataRetention: 30d

toa-server.dataRetention is the maximum age of an import folder before the server deletes it. A background sweep runs once at startup and then every 24 h; for each configured domain it walks <dataRoot>/<code>/ and removes any yyyy-MM-dd subfolder whose date is strictly older than today - dataRetention.

The sweep is scoped narrowly:

Only entries whose name parses as an ISO date are considered. Other files in a domain root (notably the cached cmserver2.xml template file) are left alone.
Today’s date folder is never deleted, regardless of how short the retention window is.
Only domains declared in toa-server.domains[] are visited. Stale data left behind from a removed domain stays on disk and must be cleaned up manually.

Defaults to 30 days. Set to 0d (or omit and rely on the default having been changed elsewhere) to disable the sweep entirely - the service then logs Data retention sweep disabled at startup and never touches the filesystem.

The retention contract is unconditional: an import that is still DRAFT or whose submission to the storage server failed will be deleted on the same schedule as a successfully submitted one. If you need to investigate a failed import, copy it out of dataRoot before the cutoff. See Retention and cleanup for the operational playbook.

3.1.3. HTTP listener

server:
  port: 8080
  address: 127.0.0.1

The server listens on a single plain-HTTP port. server.port defaults to 8080 and can be changed freely. server.address defaults to binding on all interfaces; setting it to 127.0.0.1 is a good idea on hosts where the reverse proxy lives on the same machine, so the service port is not exposed on the network.

TLS is not configured on this server - it is terminated by the reverse proxy in front of it. See Hosting the task pane for the proxy setup and Prerequisites for the network expectations.

3.1.4. Upload size limits

The server accepts a single upload (an EML page, an attachment, or a binary document) of up to 100 MB out of the box. Bodies above the limit are rejected by Tomcat before they reach the application. Four properties govern this; change all four together to keep them consistent:

server:
  tomcat:
    # Bytes - raise for larger uploads.
    max-http-form-post-size: 209715200   # 200 MB
    max-swallow-size:        209715200   # 200 MB
spring:
  servlet:
    multipart:
      # Suffix accepted (KB, MB, GB).
      max-file-size:    200MB
      max-request-size: 200MB

Note the unit mismatch: the Tomcat pair takes raw bytes, the Spring multipart pair accepts KB / MB / GB suffixes. This is a Spring Boot convention, not a TOA quirk.

The upload body is streamed to disk by the server (On-disk layout), so raising the limit does not translate into proportional memory pressure. Revisit it when you see 413 Payload Too Large responses for real-world attachments.

3.1.5. CORS

toa-server:
  cors:
    allowed-origins:
      - https://localhost:3000

toa-server.cors.allowed-origins lists the HTTPS origins from which the browser is allowed to call the API directly. In a production deployment this list is usually empty - the Outlook add-in shares its origin with the API through the reverse proxy (see Hosting the task pane), which sidesteps CORS entirely.

Populate the list only when you deliberately host the task pane on a different origin from the API. A typical case is local development: the webpack dev server runs on https://localhost:3000 and calls the TOA server on http://localhost:8080.

When the list is empty the server does not emit any Access-Control-* headers. Each entry must be a full scheme + host (and port if non-default). Wildcards are not accepted.

3.1.6. Time zone

The server stamps every import folder with the server-local calendar day (yyyy-MM-dd) and time (HHmm). Both come from the JVM’s default time zone, which is inherited from the host OS at process startup. The same time zone determines when the retention sweep rolls over to a new “today” and so when an import becomes eligible for deletion.

Recommendation: pin the JVM time zone explicitly rather than relying on whatever the host happens to be set to. Two equivalent ways:

set the TZ environment variable for the service (the cleanest option under systemd - Environment=TZ=Europe/Bratislava), or
pass -Duser.timezone=Europe/Bratislava as a JVM argument.

Pick one and keep all TOA server instances of the same customer on the same zone. Mixing zones across instances that share a dataRoot (e.g. via a network mount) will produce date folders that disagree about which day a midnight-edge import belongs to, which in turn makes retention behaviour surprising.

The mapping between the configured zone and the on-disk folder names is described from the operator’s side in On-disk layout.

3.1.7. Logging

The server logs through SLF4J/Logback with a packaged logback-spring.xml that writes both to stdout (captured by journalctl under systemd) and to a rotating file at ./logs/toa-server.log. The four parameters worth tuning are exposed as standard Spring Boot properties; defaults shown:

logging:
  file:
    name: /var/log/toa-server/toa-server.log    # default ./logs/toa-server.log
  logback:
    rollingpolicy:
      max-file-size:    50MB
      total-size-cap:   1GB
      max-history:      30                       # days
  level:
    root: INFO
    com.lightcomp.tahiti.office.addon: DEBUG

Per-package log levels can be raised for troubleshooting without restarting the whole stack. See Logs and monitoring for the full operator-facing description, including key events to look for and the on-disk file rotation contract.