.. index::
    single: Tutorials

.. _tutorials:

Tutorials
=========

Nginx integration
-----------------

Prerequisites
^^^^^^^^^^^^^

* Self-hosted target app with Nginx reverse proxy.
* Installed :ref:`Tirreno platform <installation>`.

.. attention::
    Before implementing the provided Nginx configuration in a production
    environment, testing it in a development or staging environment is
    crucial. Using these settings without prior testing and validation
    is strongly discouraged and done entirely at your own risk.

Tirreno Integration
^^^^^^^^^^^^^^^^^^^

Basics
""""""

In order to enable integration with :tirreno:`Tirreno`, information
about the original target app requests has to be transmitted to the
:tirreno:`Tirreno` :term:`API <sensor>`.

To achieve this, in the Nginx configuration file add the ``location
= /mirror {...}`` block to the ``server`` context. Also, append ``mirror
/mirror;`` directives to all existing ``location`` blocks.

.. literalinclude:: /examples/nginx-part.conf
   :language: nginx
   :linenos:

For the example to function in your environment, remember to replace
the placeholders with actual values. That is:

* Enter your :tirreno:`Tirreno` URL as ``proxy_pass`` value.

* Enter :tirreno:`Tirreno` :term:`tracking code` as ``Api-Key`` header
  value (see :ref:`API` page).

Configuration Details
"""""""""""""""""""""

The subsection below demonstrates the complete :ref:`Nginx configuration
<example-nginx-configuration>` file. It contains additional placeholders
that must be replaced with values pertinent to your setup.

Also, note the following details:

Time format
    The :tirreno:`Tirreno` API requires the :ref:`parameter
    <required-parameters>` ``eventTime`` to be sent in the ``Y-m-d
    H:i:s.v`` format (with milliseconds). Since Nginx does not support
    direct timestamp format manipulation, the example configuration uses
    the ``map`` directive for time formatting.

Timezone
    Ensure that Nginx or its environment is configured to use the UTC
    timezone. For instance, you can use the directive ``env TZ=UTC`` in
    the Nginx configuration file to specify the timezone.

User name
    Example configuration above uses ``$APPUSERID`` variable. You may set
    it according to your actual user name extraction.

Final Steps
"""""""""""

After adjusting the Nginx configuration, verify its syntax with ``sudo
nginx -t``. Apply the changes by reloading the configuration file or by
restarting the web server (e.g., ``sudo systemctl restart nginx``).

Now open your target app client and login. Finally, visit the
:tirreno:`Tirreno` :term:`console` to check the displayed :term:`event`
details.

.. _example-nginx-configuration:

Example Nginx Configuration
^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. literalinclude:: /examples/nginx.conf
   :language: nginx
   :linenos:

Your Tirreno Adventure Awaits
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

This use case is just one small example of what you can achieve with the
:tirreno:`Tirreno` platform.

:tirreno:`Tirreno` is the easiest way to get started with fraud prevention.
An open-source version of :tirreno:`Tirreno` is available for
free on `GitHub <https://github.com/TirrenoTechnologies/tirreno>`_.