.. index:: web configuration nginx

.. _web-conf:

==========================================
Web server configuration and customization
==========================================

In the Fleio docker deployment we have two containers running nginx:

* ``web`` - public facing nginx, forwards requests to ``backend`` or ``frontend``, depending on the URL
* ``frontend`` - serves static Fleio files

See more info about the the docker deployment in the :ref:`architecture diagram<docker_arch_image>`.

Since nginx configuration files do not support a multi-layer configuration inheritance, but just simple file includes,
we have decided to only allow customizations to be performed through custom built images.

To understand how you can add or modify files in a docker image in a Fleio-upgrade-safe way see:
:ref:`change-docker-files`.

.. _web-nginx-conf:

web nginx configuration
=======================

The ``web`` container is based on one of these images, depending your SSL option:

* ``web`` image, no SSL is used
* ``webownssl`` - you are using your own SSL certificate issued by a Certificate Authority or an unsigned SSL
* ``webletsencrypt`` - you have chosen to use a free `Let's Encrypt <https://letsencrypt.org/>`_ certificate that is
  automatically renewed by Fleio

Note that these image names have been shorten here for convenience. The full image name includes the Fleio docker
registry and the Fleio version suffix. E.g. ``hub.fleio.com/fleio_web-2020-11:1``.

For all above images the nginx configuration template file is ``/etc/nginx/templates/web.conf.template``.

When the container starts the template file is copied to ``/etc/nginx/conf.d/web.conf`` and the ``$FLEIO_DOMAIN``
variable is replaced with the value from your ``.env`` file.

frontend configuration
=======================

Details from the above :ref:`web-nginx-conf` apply to ``frontend`` container, except:

* image name is ``frontend``, or more precisely ``hub.fleio.com/fleio_frontend-2020-11:1`` (depending on the Fleio
  version)
* nginx template path in the image is ``/etc/nginx/templates/frontend.conf.template`` and this is copied to
  ``/etc/nginx/conf.d/frontend.conf`` on ``frontend`` container start

Tips to customize web or frontend
=================================

First of all, make sure you read :ref:`change-docker-files`.

Here are some ideas of how you can customize the ``web`` or the ``frontend`` docker images:

* you can add new nginx configuration files (e.g. with new vhosts) to ``/etc/nginx/conf.d``
* you can add a bash script in path ``/docker-entrypoint.d/30-custom.sh`` inside the image. This directory already
  contains ``/docker-entrypoint.d/20-envsubst-on-templates.sh`` and you should name your file with the ``30-`` prefix.
  This way your script runs after the conf template is copied to ``/etc/nginx/conf.d`` on container start. As you might
  have guessed, the nginx image runs scripts in ``/docker-entrypoint.d/`` automatically and in alphabetical order. Don't
  forget to ``chmod +x`` your script
* In your ``30-custom.sh`` script you can modify configuration files with ``sed`` or similar tools.
* Since the nginx configuration templates might change between Fleio releases, it is very important that you **test your
  custom image before deploying a Fleio upgrade in production**.