.. _client-hosting:

=========================
Hosting the task pane
=========================

The task pane is a collection of static files (HTML, JS, CSS, icons,
``manifest.xml``) produced by the webpack build and shipped in the
``site/`` subfolder of ``toa-client-<version>.zip``. It can be served
from any HTTPS origin the customer controls - nginx, IIS, Apache,
Azure Static Web Apps, or an internal CDN.

Required properties of the origin
=================================

* **HTTPS with a publicly trusted certificate.** Outlook refuses to
  load resources from origins with invalid certificates, and the
  add-in will simply not render.
* **Same origin for the static bundle and the API.** The add-in calls
  the TOA server using the relative base path ``/api/...``; a reverse
  proxy on the same origin must forward those requests to the Spring
  Boot backend. This keeps the browser happy with one cookie scope,
  avoids CORS entirely, and sidesteps mixed-content rules.
* **HTTP compression** (gzip or brotli) on ``*.js``, ``*.html``,
  ``*.css`` is recommended - the bundle is a few hundred kB
  uncompressed.

Example nginx configuration
===========================

.. code-block:: nginx

   server {
       listen 443 ssl http2;
       server_name addin.customer.cz;

       ssl_certificate     /etc/ssl/addin/fullchain.pem;
       ssl_certificate_key /etc/ssl/addin/privkey.pem;

       root  /var/www/toa-addin/site;
       index taskpane.html;

       # Static bundle: everything under /, with cache-busting on JS
       # chunks (webpack hashes filenames).
       location / {
           try_files $uri =404;
       }

       # Reverse proxy to the TOA server. Keep the /api/ prefix in the
       # public URL but strip it before forwarding so the server sees
       # the native paths declared in tao-openapi.yml.
       location /api/ {
           proxy_pass         http://127.0.0.1:8080/;
           proxy_set_header   Host               $host;
           proxy_set_header   X-Forwarded-For    $proxy_add_x_forwarded_for;
           proxy_set_header   X-Forwarded-Proto  $scheme;
       }
   }

TLS and certificates
====================

If the customer uses Let's Encrypt or a corporate PKI, certificate
renewal is out of scope for TOA itself. Just make sure the
reverse-proxy and the TOA server are not exposed via different
hostnames - the add-in assumes a single origin.

Cache and versioning
====================

Webpack writes hashed filenames for JS and asset chunks
(``taskpane.<hash>.js``), so aggressive browser caching on those is
safe. The two files that change without a filename hash are
``taskpane.html`` and ``manifest.xml``; serve those with
``Cache-Control: no-cache`` or a short max-age so that updates
propagate within minutes of a redeploy.

Outlook itself caches the manifest for several hours after the user
logs in; see :ref:`client-m365-deployment` for how to force a refresh
through the admin center.