.. _manager-configuration-reference:

Manager Configuration
=====================

The Manager is highly configurable using environment variables.

+----------------------------------------+-----------------------+-------------------------------------------------------------+
| Environment Variable                   | Default Value         | Description                                                 |
+========================================+=======================+=============================================================+
| MVI_HOST_NAME                          | "localhost"           | Host name of the machine running the manager.               |
+----------------------------------------+-----------------------+-------------------------------------------------------------+
| MVI_PROXY_HTTP_PORT                    | 80                    | Proxy port for HTTP communication with manager.             |
+----------------------------------------+-----------------------+-------------------------------------------------------------+
| MVI_PROXY_HTTPS_PORT                   | 443                   | Proxy port for HTTP communication with manager.             |
+----------------------------------------+-----------------------+-------------------------------------------------------------+
| MVI_PROXY_CONFIG_PATH                  | "proxy_config"        | Path to proxy configuration files.                          |
+----------------------------------------+-----------------------+-------------------------------------------------------------+
| MVI_AUTH_ENABLED                       | False                 | Using the manager required login if true.                   |
+----------------------------------------+-----------------------+-------------------------------------------------------------+
| MVI_MAX_REQUEST_BODY                   | 1000000000            | Maximum allowed transferred filesize. 1GB default.          |
+----------------------------------------+-----------------------+-------------------------------------------------------------+
| MVI_LOG_LEVEL                          | "INFO"                | Minimum logger level for manager.                           |
+----------------------------------------+-----------------------+-------------------------------------------------------------+
| MVI_ACCESS_LOGS_ENABLED                | True                  | Whether to print access logs.                               |
+----------------------------------------+-----------------------+-------------------------------------------------------------+
| MVI_PROXY_HTTPS                        | False                 | Sets up a secure connection to the manager if true          |
+----------------------------------------+-----------------------+-------------------------------------------------------------+
| MVI_HTTPS_STAGING_SERVER               | False                 | Sets if a staging server without rate limits should be used |
+----------------------------------------+-----------------------+-------------------------------------------------------------+
| MVI_CONFIG_EMAIL                       | null                  | Email address HTTPS and sending notifications.              |
+----------------------------------------+-----------------------+-------------------------------------------------------------+
| MVI_CONFIG_EMAIL_PASSWORD              | null                  | Password for config email, only required for notifications. |
+----------------------------------------+-----------------------+-------------------------------------------------------------+
| MVI_NOTIFICATION_SMTP_SERVER           | null                  | SMTP server URL.                                            |
+----------------------------------------+-----------------------+-------------------------------------------------------------+
| MVI_NOTIFICATION_SMTP_PORT             | null                  | Port to SMTP server, usually 587 or 465.                    |
+----------------------------------------+-----------------------+-------------------------------------------------------------+
| MVI_ACTIVATION_KEY                     | ""                    | License activation key. Without key Manager lives for 12h.  |
+----------------------------------------+-----------------------+-------------------------------------------------------------+

Secure Manager Connection
^^^^^^^^^^^^^^^^^^^^^^^^^

It is possible to get a secure HTTPS connection to the manager using automatically
created certificates from `Let's Encrypt <https://letsencrypt.org>`_. To enable HTTPS you must
start a new manager with the environment variable
``MVI_PROXY_HTTPS`` set to true. We also recommend that you set an email
address with the environment variable ``MVI_CONFIG_EMAIL``, so you can get
notified if the certificate is about to run out. 

.. warning:: For the `Let's Encrypt` certificates to work,
    the server must have a valid hostname which resolves via DNS to the server's IP
    address. It will not work if you access the manager using an IP address or
    ``localhost`` due to how TLS certificates are generated.

Email notifications
^^^^^^^^^^^^^^^^^^^

The first step is to set up an email address that the MVI Manager can use to send
the notification emails. For this you need an
`SMTP <https://en.wikipedia.org/wiki/Simple_Mail_Transfer_Protocol>`_ server with
an email account that you can use. We recommend to have a dedicated email address
for sending MVI notifications.

The manager is configured with a notification sender email at startup. We do this
by setting four different environment variables at manager startup

+----------------------------------------+-----------------------+
| Environment Variable                   | Value                 |
+========================================+=======================+
| MVI_CONFIG_EMAIL                       | "email@address.com"   |
+----------------------------------------+-----------------------+
| MVI_CONFIG_EMAIL_PASSWORD              | "password"            |
+----------------------------------------+-----------------------+
| MVI_NOTIFICATION_SMTP_SERVER           | "smtp.server.url"     |
+----------------------------------------+-----------------------+
| MVI_NOTIFICATION_SMTP_PORT             | Usually 587 or 465    |
+----------------------------------------+-----------------------+

Upon startup of the manager, if everything worked, an email will be sent from
"email@address.com" to itself, to show that it successfully connected. Otherwise,
as long as the manager could still start, any issues with the email configuration 
will be viewable on the notification tab in the dashboard.

Typical production setup
^^^^^^^^^^^^^^^^^^^^^^^^

The example below starts a Manager instance that is listening on ``my.domain.com``, enforcing traffic over https with access
control enabled and being activated using a provided activation key:

.. code-block:: shell

    docker run
        --name mvi_manager
        -v /var/run/docker.sock:/var/run/docker.sock
        -v mvi_data:/data
        -p 80:80
        -p 443:443
        -e MVI_HOST_NAME=my.domain.com
        -e MVI_PROXY_HTTPS=True
        -e MVI_AUTH_ENABLED=True
        -e MVI_ACTIVATION_KEY=...
        -e MVI_CONFIG_EMAIL=<some@email.com>
        -e MVI_CONFIG_EMAIL_PASSWORD=<password for some@email.com>
        -e MVI_NOTIFICATION_SMTP_SERVER=<your smtp server address>
        -e MVI_NOTIFICATION_SMTP_PORT=<your smtp server port>
        --restart always
        -d ghcr.io/vikinganalytics/mvi/mvi_manager:{version}

.. tip:: To ease working with all environment variables, it is possible to make use
    of the ``--env-file`` parameter to ``docker run``. 
    See `here <https://docs.docker.com/engine/reference/commandline/run/#set-environment-variables--e---env---env-file>`_
    for details on syntax etc.