=========================
Using configuration files
=========================

.. contents::
   :local:
   :depth: 1

The default locations for each component's configuration files are:

* Server---``/opt/wakari/wakari-server/etc/wakari/config.json``.

* Gateway---``/opt/wakari/wakari-gateway/etc/wakari/config.json``.

* Compute---``/opt/wakari/wakari-compute/etc/wakari/config.json``.

Additionally, service-specific configuration files may also be present in the
following locations:

* Server---``/opt/wakari/wakari-server/etc/wakari/wk-server-config.json``.

* Gateway---``/opt/wakari/wakari-gateway/etc/wakari/wk-gateway-config.json``.

* Compute---``/opt/wakari/wakari-compute/etc/wakari/wk-compute-config.json``.

Each service loads each of the configuration files in the following order and
updates the AEN configuration at each step:

#. ``/etc/wakari/config.json``.
#. ``/etc/wakari/wk-gateway-config.json``.
#. ``/opt/wakari/wakari-SERVICE/etc/wakari/config.json``.
#. ``/opt/wakari/wakari-SERVICE/etc/wakari/wk-SERVICE-config.json``.
#. ``./config.json``.
#. ``./wk-gateway-config.json``.


AEN configuration keys
======================

The following is a list of AEN supported configuration keys:

.. csv-table:: Server Configuration Keys
   :header: "Key", "Default", "Description"
   :widths: 30, 30, 80

   ``CDN``, ``$WAKARI_SERVER/static/``, "The location of static assets."
   ``MONGO_DB``, ``wakari``, "The name of the AEN database in mongodb."
   ``MONGO_URL``, ``mongodb://localhost/``, "The URL of your AEN server's mongodb instance. Format:
   ``mongodb://<username>:<password>@<host>:<port>/``"
   ``WAKARI_SERVER``,, "The URL of this AEN server."
   ``DEFAULT_PRIVACY``, ``public``, "The default project privacy setting---can be either ``public`` or ``private``."
   ``SESSION_COOKIE_NAME``, ``wakari.`` ``enterprise.session``, "The Cookie name used to maintain Anaconda Enterprise Notebooks Enterprise login sessions."
   ``PERMANENT_SESSION``, ``True```, "Sets cookie session to permanent. This will keep the session open after the browser is closed. The session will still expire after the number of minutes set in the SESSION_LIFETIME key."
   ``SESSION_LIFETIME``, ``120``, "Time in minutes until the session expires. The counter resets with each request."
   ``USE_SES``, ``false``, "Sets whether AEN will use Amazon SES to send emails."
   ``SMTP``,, "Sets the SMTP email settings."
   ``- host``,, "A SMTP subkey---the SMTP mail server hostname."
   ``- user``,, "SMTP subkey---the username for SMTP server authentication."
   ``- password``,, "SMTP subkey---the password for SMTP server authentication."
   ``- from_addr``,, "SMTP subkey---the From address for emails sent through SMTP."
   ``verify_gateway`` ``_certificate``, ``true``, "A boolean setting that indicates whether your AEN server should verify the gateway SSL certificate."
   ``accounts``, ``wk_server.plugins`` ``.accounts.cloud``, "The account provider class. For LDAP, this should be set to ``wk_server.plugins.accounts.ldap_accounts``."
   ``uniqueEmail``, ``true``, "A boolean setting that indicates whether unique user email addresses are required. See :ref:`note below <uniqueEmail-database>` about updating the database when setting ``uniqueEmail``."
   ``has_internet``, ``true``, "Boolean for retrieving the avatar from the gravatar URL. If false a local default is used instead."
   ``LDAP``, ``389``, "LDAP configurations."
   ``- SERVER``,, "LDAP subkey---A list of LDAP servers. At least one server name must be listed. The primary server should be listed first. All secondary or fail-over servers should be listed after the primary."
   ``- PORT``, ``389``, "LDAP subkey---The LDAP port on the LDAP server."
   ``- AUTH_TYPE``,, "LDAP subkey---LDAP Authentication types. ``simple``---no encryption not secure.``TLS``--encrypted secure requires the ``TLS_CERT`` to be set."
   ``- TLS_CERT``,, "LDAP subkey---the full path to the TLS certificate file. The certificate file must also be provided by the Enterprise."
   ``- BASEDN``,, "LDAP subkey---the LDAP Base DN value."
   ``- OU``,, "LDAP subkey---a list of Organizational Units. Some Enterprises group users by OUs in their LDAP server records. AEN will loop over the list of OUs when authenticating a user. The OU value is a list of lists to support multiple OUs where each OU is a single name or a hierarchy of names."
   ``ANON_USER``, ``anonymous``, "Username---such as ``public`` or ``anonymous``-- assigned users who are not logged in to access projects. To disable public access use the special value ``disabled``. For more information, see :doc:`config-sudo-customizations`."
   ``SEARCH_ENABLED``, ``true``, Boolean indicating whether ElasticSearch is enabled
   ``SEARCH_SERVER``, ``'localhost:9200'``, IP address or domain name and port of ElasticSearch server
   ``LOG_LEVEL``, ``'DEBUG'``, "Log verbosity. One of: 'ERROR' 'WARN' 'INFO' 'DEBUG'"

.. _uniqueEmail-database:

NOTE: If you set ``uniqueEmail`` to ``false``, you must drop the existing index in the database. EXAMPLE: If the index name is ``email_1``, run ``db.users.dropIndex("email_1")``.

.. csv-table:: Gateway Configuration Keys
   :header: "Key", "Default", "Description"
   :widths: 30, 30, 80

   ``WAKARI_SERVER``,, "The URL of the AEN ``WAKARI_SERVER``."
   ``port``, 8089, "The Port number used by the gateway application. Must be a non-privileged port (>= 1024)."
   ``client_id``,, "The client ID assigned to this gateway by the server during ``wk-gateway-configure``."
   ``client_secret``,, "The Client secret assigned to this gateway by the server during ``wk-gateway-configure``."
   ``httpTimeout``, 600, "Timeout in seconds. The default is 10 minutes to allow project creation."
   ``logLevel``, ``info``, "Log verbosity. One of: 'error' 'warn' 'info' 'debug'."
   ``https``,, "Enable SSL encryption. For more information, see :doc:`config-ssl`."
   ``- key``,, "A https subkey--Path to gateway key."
   ``- cert``,, "A https subkey--Path to gateway cert."
   ``- ca``,, "A https subkey--Required if cert was signed by a private root CA or signed by an intermediate authority. It must contain separate values for the paths to the CA root, any intermediates and the certificate for the Server."
   ``- passhphrase``,, "A https subkey--Passphrase required to decrypt SSL certs."

.. csv-table:: Compute Node Configuration Keys
   :header: "Key", "Default", "Description"
   :widths: 30, 30, 80

   ``WAKARI_SERVER``,, "The URL of the AEN ``WAKARI_SERVER``."
   ``MANAGE_ACCOUNTS``, ``true``, "A boolean setting that indicates whether AEN should manage system user accounts. Set to false for LDAP installations."
   ``port``, 2227, "The port number used by the compute-launcher application. Note that individual applications use dynamic ports."
   ``projectRoot``, ``/projects``, "The location of project file storage."
   ``logLevel``, ``info``, Log verbosity. One of: 'error' 'warn' 'info' 'debug'
   ``logMaxSize``, 10000000, Max size in bytes of the logfile. Default is 10 MB. If the size is exceeded then a new file is created and a counter will become a suffix of the log file.
   ``logMaxFiles``, 30, Limit the number of files created when the size of the logfile is exceeded
   ``appIdleTime``, 172800000 (48 hours), "The amount of idle time before applications will be auto-terminated (in msec)."
   ``idleCheckInterval``, 3600000 (1 hour), "The frequency of idle checks."
   ``numericUsernames``, ``false``, "A boolean setting that indicates whether numeric usernames are permitted."
   ``httpTimeout``, 600, "The time before a timeout---in seconds. The default is 10 minutes---600 seconds---to allow time for project creation."
   ``ANON_USER``, ``anonymous``, "Username such as ``public`` or ``anonymous`` for users who are not logged in to access projects. To disable public access use the special value ``disabled``. For more information, see :doc:`config-sudo-customizations`."

.. csv-table:: Server Internal Configuration Keys - Do not change
   :header: "Key", "Default", "Description"
   :widths: 30, 30, 80

   ``PROVIDERS``, ``["wk_server.plugins`` ``.providers.enterprise"]``, "A list of compute provider classes."
   ``MONGO_ACTION`` ``_LOG_SIZE``, 262144000, "The size of the Mongo action log in bytes."
   ``SITE_ADMINS``, , "A list of site administrator email addresses---used for crash notifications and LDAP password reset requests."
   ``FROM`` ``_EMAIL_ADDR``, ," The From address for notification emails sent by AEN."
   ``uniqueUserName``, ``true``, "A boolean setting that indicates whether unique usernames are required."

.. csv-table:: Gateway Internal Configuration Keys - Do not change
   :header: "Key", "Default", "Description"
   :widths: 30, 30, 80

   ``CDN``, ``$WAKARI_SERVER/static/``, "The location of static assets."
   ``SUBDOMAIN_ROUTING``, ``false``, "A boolean that indicates whether subdomains are being used."
   ``refreshTokenExpiration``, ``600000``, "Idle time in milliseconds before the Gateway session expires."

.. csv-table:: Compute Node Internal Configuration Keys - Do not change
   :header: "Key", "Default", "Description"
   :widths: 30, 30, 80

   ``CDN``, ``$WAKARI_SERVER/static/``, "The location of static assets."
   ``USE_SES``, ``false``, "Sets whether AEN will use Amazon SES to send emails."
   ``multiUser``, ``true``, "A boolean that indicates whether multi-user support is enabled."
   ``multiProject``, ``true``, "A boolean that indicates whether multi-project support is enabled."
   ``ANACONDA_ROOT``, ``/opt/wakari/anaconda``, "The location of your Anaconda installation."
   ``appLogs``, ``/opt/wakari/wakari-`` ``compute/var/log/wakari/`` ``compute-launcher-apps``, "The directory where application logs are stored."
   ``appPIDs``, ``/opt/wakari/wakari-compute/`` ``var/run/compute-launcher-apps``, "The directory where application PID files are stored."
   ``applicationLog``, ``/opt/wakari/wakari-compute/`` ``var/log/wakari/`` ``compute-launcher.application.log``, "The path to the compute launcher log."
   ``accessLog``, ``opt/wakari/wakari-compute/`` ``var/log/wakari/`` ``compute-launcher.access.log``, Path to compute launcher access log

.. _check-config-syntax:

Checking configuration file syntax
==================================

To verify that the configuration file contains valid JSON, run:

.. code-block:: bash

    root@server  # python -m json.tool /opt/wakari/wakari-server/etc/wakari/*.json
    root@gateway # python -m json.tool /opt/wakari/wakari-gateway/etc/wakari/*.json
    root@compute # python -m json.tool /opt/wakari/wakari-compute/etc/wakari/*.json

If the file is correct, the contents are displayed.

If there is a syntax error in the file, a "No JSON object could be decoded"
message is displayed instead.

To fix any errors, edit the configuration file and verify that it contains the
correct JSON syntax.
