.. _configure-server: ================ 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 :ref:`configure-domains`. Data root ========= .. code-block:: yaml 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 ``//`` 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 :ref:`install-server`; the on-disk structure is described in :ref:`operate-data-layout`. The key is required whenever at least one domain is configured. Without it the server refuses to start. Data retention ============== .. code-block:: yaml 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 ``//`` 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 :ref:`operate-retention` for the operational playbook. HTTP listener ============= .. code-block:: yaml 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 :ref:`client-hosting` for the proxy setup and :ref:`install-prerequisites` for the network expectations. 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: .. code-block:: yaml 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 (:ref:`operate-data-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. CORS ==== .. code-block:: yaml 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 :ref:`client-hosting`), 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. .. _configure-server-timezone: 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 :ref:`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 :ref:`operate-data-layout`. 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: .. code-block:: yaml 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 :ref:`operate-logs` for the full operator-facing description, including key events to look for and the on-disk file rotation contract.