.. _apps-smart_settings:


========
Settings
========

Mayan EDMS can be configure using various methods.


.. _environment_variables:

Via environment variables
=========================


#. Go to the :menuselection:`System --> Setup --> Indexes` menu.
#. Create a new index using :guilabel:`Actions` > :guilabel:`Create new`.


To use environment variables, lookup the name of the setting you want to
override in the :menuselection:`System --> Setup --> Settings` menu.
To pass a value via an environment variable append
``"MAYAN_"`` to the name of the settings option. For example, to change
the number of documents displayed per page (``COMMON_PAGINATE_BY``, by default 40),
use:

.. code-block:: console

    export MAYAN_COMMON_PAGINATE_BY=10

Restart Mayan EDMS and the new value will take effect. The Settings menu
can be used to verify if the overridden setting value is being interpreted
correctly.


.. _configuration_file:

Via YAML configuration file
===========================

.. versionadded:: 3.1

It is possible to modify the different settings by creating or editing the
``media/config.yml`` file. This file is formatted in the YAML markup language
(http://yaml.org/). Here is an example of what the looks like:

.. code-block:: yaml

    DOCUMENT_PARSING_AUTO_PARSING: true
    DOCUMENT_PARSING_PDFTOTEXT_PATH: /usr/bin/pdftotext
    EMAIL_BACKEND: django.core.mail.backends.smtp.EmailBackend
    EMAIL_HOST: localhost
    EMAIL_HOST_PASSWORD: ''
    EMAIL_HOST_USER: ''
    EMAIL_PORT: 25
    EMAIL_TIMEOUT: null
    EMAIL_USE_SSL: false
    EMAIL_USE_TLS: false
    FILE_UPLOAD_MAX_MEMORY_SIZE: 2621440
    HOME_VIEW: common:home

Every time Mayan EDMS is able to start correctly it will copy the ``config.yml``
and create a backup copy in the same directory named ``config_backup.yml``.
This file is used to revert to the last know configuration file known
to be valid. You can revert manually by copy the file or by using the
``revertsettings`` management command from the command line.


Via Python settings files
=========================

Another way to configure Mayan EDMS and the one required when more extensive
setup is required (such as when using external Python libraries), is via
Python-style, settings files. A folder named ``|DEFAULT_USER_SETTINGS_FOLDER|`` is
created for the purpose of hosting these settings files.

Create a file with any valid name and a ``.py`` extension in the
``|DEFAULT_USER_SETTINGS_FOLDER|`` folder. The file must starts with a global import
of ``mayan.settings.production``. In the form:

.. code-block:: python

    from mayan.settings.production import *

Now add the corresponding lines to override the default settings.
In the settings file, it is not necessary to prepend the string ``MAYAN_`` to
the setting option. For example, to change the number of documents displayed
per page (``COMMON_PAGINATE_BY``, by default 40),
use:

.. code-block:: python

    COMMON_PAGINATE_BY=10

versus:

.. code-block:: python

    export MAYAN_COMMON_PAGINATE_BY=10

when using the environment variable method.

For this example let's assume the file was saved with the name ``mysettings.py``.

The way used to tell Mayan EDMS to import this file will vary based on the
installation method.

For the :ref:`chapters-docker` installation method, the full import
path will be ``|DEFAULT_USER_SETTINGS_MODULE|.mysettings`` and can only be passed
via the ``MAYAN_SETTINGS_MODULE`` environment variable like this:

.. code-block:: console

    docker run <...> -e MAYAN_SETTINGS_MODULE=|DEFAULT_USER_SETTINGS_MODULE|.mysettings


.. note::

   The settings files must be valid Python modules. Errors in the Python
   settings files might prevent Mayan EDMS for starting properly. Errors
   other than syntax errors, might cause Mayan EDMS to starting up in an
   incomplete manner making debugging difficult.


Setting priority
================

The settings will be applied in the following order:

#. YAML configuration file.
#. Python settings file.
#. Environment variables.

Only settings overridden via environment variables will be identified as
such in the settings view.

Settings overridden or set via Python settings files will not be identified
as such in the settings view.
