.. _Installation:

Installation
============

Requirements
------------

- AntMedia Server 2.17 or later
- A valid Scout license key

Quick install
-------------

Run the following command on your AntMedia server as root or with ``sudo``:

.. code-block:: bash

   curl -fsSL https://downloads.raskenlund.com/scout/antmediaserver/install.sh | sudo bash

This downloads ``Scout-1.0.0.jar`` to the AntMedia plugins directory, sets the correct file
ownership, and restarts the ``antmedia`` service. A skeleton ``scout.properties`` config file
is created at ``/usr/local/antmedia/conf/scout.properties`` if one does not already exist.

You can pass your license key directly to avoid editing the config file manually:

.. code-block:: bash

   curl -fsSL https://downloads.raskenlund.com/scout/antmediaserver/install.sh | sudo bash -s -- --licenseKey=YOUR-LICENSE-KEY

Manual install
--------------

1. Copy ``Scout-1.0.0.jar`` to ``/usr/local/antmedia/plugins/``

2. Copy ``scout.properties.dist`` to ``/usr/local/antmedia/conf/scout.properties`` and add
   your license key at minimum:

   .. code-block:: yaml

      licenseKey: "YOUR-LICENSE-KEY"
      delivery: headers
      scope: both

3. Restart AntMedia:

   .. code-block:: bash

      systemctl restart antmedia

4. Open the Web UI at ``http://<your-server>:5080/rest/scout/ui/`` and use the
   **Applications** section to install the servlet filter for each application you want
   Scout to annotate (see :ref:`Servlet filter` below).

.. _Servlet filter:

Servlet filter
--------------

Scout injects CMSD data by intercepting HLS and DASH responses through a servlet filter.
The filter must be registered in each AntMedia application's ``WEB-INF/web.xml``.

The easiest way to do this is via the Web UI (see :ref:`Web UI`). Alternatively, add the
following to the application's ``WEB-INF/web.xml``:

.. code-block:: xml

   <filter>
       <filter-name>ScoutFilter</filter-name>
       <filter-class>io.ztream.scout.filter.ScoutFilter</filter-class>
       <async-supported>true</async-supported>
   </filter>
   <filter-mapping>
       <filter-name>ScoutFilter</filter-name>
       <url-pattern>/streams/*</url-pattern>
   </filter-mapping>

After editing ``web.xml`` manually, restart the application (or the full AntMedia service).

Verifying the installation
---------------------------

After restarting, publish a stream to a configured application. You should see log entries
from ``Scout`` in ``/usr/local/antmedia/log/ant-media-server.log``. When a client requests
a ``.m3u8``, ``.mpd``, ``.ts``, or ``.m4s`` resource, the ``CMSD-Static`` header (and
optionally inline manifest tag) will appear in the HTTP response.