=======================
Configuration reference
=======================

.. contents::
   :local:


Files
=====

Anaconda Repository loads configuration files with the extension
``.yaml`` from the following locations:

* ``/etc/binstar/``
* ``/etc/anaconda-server/``
* ``$PREFIX/etc/anaconda-server``

NOTE: ``$PREFIX`` is the location where repository is installed.

Files are loaded from these directories in order, with later files
overriding earlier files. Files are loaded from each directory in
alphabetical order.

If an environment variable ``ANACONDA_SERVER_CONFIG`` is set with the
path of a configuration file, this file is loaded after the three
already listed. Its settings override any conflicting settings in
the earlier files.

Each configuration setting variable can have its value set with the
``anaconda-server-config --set`` command, or by editing a
configuration file.

EXAMPLE: To set a value named VALUE_ONE to 50, add this to a
configuration file::

  VALUE_ONE: 50

Or, you can set a value named VALUE_ONE to 50 with this command::

  anaconda-server-config --set VALUE_ONE 50


..  BRAND
    CACHE_DIR
    CDN
    DOCUMENTATION_DIR
    JOURNAL_FILE
    LICENSES_DIR
    LOAD_FILES
    LOGGING
    LOG_DIR
    MAX_IPYNB_SIZE
    PASSWORD_RULES
    PASSWORD_SALT
    PRIVATE_KEY
    PROPAGATE_EXCEPTIONS
    SECRET_KEY
    LOCK_DOWN
    AVATAR_METHOD
    AVATAR_GRAVATAR_URL
    AVATAR_STATIC_URL
    SUPERUSER_ORG_ADMIN
    csrf_enabled
    deploy_type
    enabled_features
    login_enabled
    queue_prefix
    signup_enabled
    upload_endpoint

Logging
=======

The location of the server's log file is defined in the supervisord configuration file ``$PREFIX/etc/supervisord.conf`` by the ``stdout_logfile`` config entry located in the [program:anaconda-server] section.

Advanced configuration of logging requires setting a LOGGING key on the server's config.yaml. It uses Python's logging module config structure.


Usernames
=========

USER_REGEX
----------

A regular expression that defines the allowable user names.

For example, this setting specifies that user names contain only
lowercase letters, periods, plus and minus characters
(``.``, ``+`` and ``-``)::

    USER_REGEX: '^[a-z.+-]+$'

NOTE: The default value for ``USER_REGEX`` is ``^[a-z0-9_][a-z0-9_-]+$`` which
translates to: at least one alphanumeric character or underscore, followed
by zero or more alphanumeric, dash or underscore characters.

NOTE: Escape any extra instances of the single quote character ``'``
as ``\'``. Do not use the slash and ampersand characters ``/``
and ``&``, which have special meanings in URLs.

NOTE: If USER_REGEX is changed and the server is restarted, existing
usernames that do not match the new USER_REGEX do not cause errors.

Database
========

Repository uses MongoDB as the database back end.

MONGO_URL
---------

A `MongoDB connection URI <https://docs.mongodb.com/manual/reference/
connection-string/>`_ is used to connect to the MongoDB database
server. It can be used to configure the hostname and port, as well
as database authentication.

For example::

    MONGO_URL: mongodb://anaconda-server:Pa55w0rd@mongodb.serv/

MONGO_DBNAME
------------

The MongoDB database where Repository stores its data.

MQ_DBNAME
---------

The MongoDB database where Repository stores data used for
asynchronous processing.

MONGO_REPLICA_SET
-----------------

The name of a
`MongoDB replica set <https://docs.mongodb.com/manual/replication/>`_
Repository connects to after establishing a connection to the database
server.

File storage
============

Repository can serve package contents from a local file-system, or
from Amazon Web Services Simple Storage Service: AWS S3.

Storage_type
------------

The storage mechanism to use. Valid choices are ``fs``, for
file-system storage, or ``s3``, for AWS S3 storage.

keyname_full_path
-----------------

When this option is set, Repository stores the files by full paths and not just
by hashes. This way a tensorflow file uploaded by the user `Bob` will be stored
on ``<fs_storage_root>/Bob/tensorflow/osx-64/tensorflow-1.1.0-np112py36_0.tar.bz2-594ac56e7e042600648defdb``.

NOTE: The storage path does not always contain the current file owner and their
user name. This is because the file location on the storage does not change
when you rename a user or transfer a file to a different user.

Fs_storage_root
---------------

If configured to use file-system storage, the absolute path to a
directory where Repository stores all uploaded packages.

PACKAGE_BUCKET_ID
-----------------

If configured to use AWS S3 storage, the name of an AWS S3 bucket
where Repository stores uploaded packages.

You can identify the name of your bucket by using ``<bucket>`` in
your ``http://<bucket>.s3.amazonaws.com`` URL.

S3_REGION_NAME
--------------

The S3 region that the bucket is located in. The available regions can
be found in the
`Amazon AWS documentation
<http://docs.aws.amazon.com/general/latest/gr/rande.html#s3_region>`_.

S3_SERVER_SIDE_ENCRYPTION
-------------------------

This variable can be set to ``AES256`` to enable
`server-side encryption <http://docs.aws.amazon.com/AmazonS3/latest/dev/
UsingServerSideEncryption.html>`_ for packages stored in the S3 bucket.

Notebooks
=========

.. _repo-max-ipynb-size:

MAX_IPYNB_SIZE
--------------

Specifies the maximum allowed size when uploading notebooks to the
server. The default is 25 MB. This variable can be set in
``config.yaml``.

Web server
==========

.. _server-name:

SERVER_NAME
-----------

The name and port number of the server. This option is required for
subdomain support.

For example::

    SERVER_NAME: anaconda.srv:8080

port
----

The port number of the server. Defaults to ``8080``.

subdomains
----------

If set to ``true``, Repository serves ``conda`` package from a
separate subdomain. Defaults to ``false``.

For example::

    SERVER_NAME: anaconda.srv:8080
    subdomains: true

Allows access to conda packages at ``http://conda.anaconda.srv:8080/``.


SESSION_COOKIE_DOMAIN
---------------------

The domain that Repository sets on the session cookie. If this is
not set, the cookie is valid for all subdomains of ``SERVER_NAME``.

See :doc:`secure-user-content`.

USER_CONTENT_DOMAIN
-------------------

As a cross-site scripting (XSS) protection, notebook content can be
served from a separate domain name. If this option is configured,
Repository only serves rendered notebooks from this domain.

See :doc:`secure-user-content`.

ssl_options
-----------

Repository can serve content over HTTPS, using user-provided SSL
certificates.

For example::

    ssl_options:
        certfile: /etc/anaconda-server/server.crt
        keyfile: /etc/anaconda-server/server.key
    PREFERRED_URL_SCHEME: https

certfile
^^^^^^^^

The absolute path to a PEM-formatted X.509 certificate file.

keyfile
^^^^^^^

The absolute path to a PEM-formatted private key for the associated
certificate.

ssl_version
^^^^^^^^^^^

An integer that specifies the SSL protocol version as defined by Python's ``ssl`` module::

    PROTOCOL_SSLv2 = 0
    PROTOCOL_SSLv23 = 2
    PROTOCOL_SSLv3 = 1
    PROTOCOL_TLS = 2
    PROTOCOL_TLSv1 = 3

    PROTOCOL_TLSv1_1 = 4
    PROTOCOL_TLSv1_2 = 5

The default is ``5`` (TLS v1.2).

PREFERRED_URL_SCHEME
--------------------

The preferred scheme that is used to generate URLs. Set this to
``https`` if HTTPS is configured.

gunicorn
--------

Repository uses `Gunicorn <http://gunicorn.org/>`_. The most commonly
used options are ``timeout`` and ``workers``. A complete list of
settings can be found in `Gunicorn's documentation
<http://docs.gunicorn.org/en/latest/settings.html#settings>`_.

For example::

    gunicorn:
        timeout: 60
        workers: 5

timeout
^^^^^^^

The number of seconds for which a worker is allowed to process a
request, before being forcefully terminated.

Default: 120

workers
^^^^^^^

The number of workers that Gunicorn spawns to serve Repository.
Defaults to 2 × the number of CPUs + 1.

Authentication
==============

AUTH_TYPE
---------

The method Repository uses to authenticate users. Valid choices are
``NATIVE``, for built-in authentication, ``KERBEROS``, for Kerberos,
and ``LDAP``.

KRB5_HOSTNAME
-------------

See :ref:`kerberos-configuration-options`.

KRB5_SERVICE_NAME
-----------------

See :ref:`kerberos-configuration-options`.

KRB5_KTNAME
-----------

See :ref:`kerberos-configuration-options`.

LDAP
----

Options for configuring LDAP authentication and group synchronization.

For example::

    LDAP:
      # Replace with company LDAP server
      URI: 'ldap://<ldap.company.com>'
      # Replace <uid=%(username)s,ou=People,dc=company,dc=com> with your company specific LDAP Bind/Base DN
      # Bind directly to this Base DN.
      BIND_DN: '<uid=%(username)s,ou=People,dc=company,dc=com>'
      # password of the user specified in the BIND_DN
      BIND_AUTH: abc123456

      USER_SEARCH:
          base: cn=Users,dc=example,dc=com
          filter: sAMAccountName=%(username)s

      # Map LDAP keys into application specific keys
      KEY_MAP:
          name: 'cn'
          company: 'o'
          location: 'l'
          email: 'mail'

      OPTIONS:
          OPT_NETWORK_TIMEOUT: 60
          OPT_TIMEOUT: 60

NOTE: To use LDAP with SSL, set the ``USER_REGEX`` and ``account_names_filter``
options::

    account_names_filter: false
    USER_REGEX: ^[a-z0-9_][a-z0-9_-.]+$
    LDAP:
        [configuration continues as above with URI, BIND_DN, and so on]

See :ref:`ldap-configuration-options`.

LOCK_DOWN
---------

Makes all views with the exception of the login form and welcome page,
unaccessible to anonymous users.


.. _repo-admin-reference-emails:

Email
=====

Repository can be configured to send email for various reasons,
including to reset forgotten usernames and passwords. Email can be
sent using SMTP protocol, or through Amazon Web Services Simple Email
Service (AWS SES).

SMTP_HOST
---------

The hostname of the SMTP server.

SMTP_PORT
---------

The port of the SMTP server.

SMTP_TLS
--------
If set to ``true``, Repository attempts an SSL connection to the
SMTP server.

SMTP_USERNAME
-------------

The username to authenticate against the SMTP server before attempting
to send email.

SMTP_PASSWORD
-------------
The password to authenticate against the SMTP server before attempting
to send email.

USE_SES
-------

If set to ``true``, Repository sends email with AWS SES. To
authenticate to AWS, the server should be configured with
`an appropriate IAM role <http://docs.aws.amazon.com/ses/latest/
DeveloperGuide/control-user-access.html>`_, or have credentials
specified in a `Boto configuration file <http://boto.cloudhackers.com/
en/latest/boto_config_tut.html#credentials>`_.

RETURN_ADDRESS
--------------

The ``From:`` email address that Repository uses as sender.

ALLOW_DUPLICATED_EMAILS
-----------------------

If set to ``true``, Repository allows different users to share the
same email or secondary email. Defaults to ``false``.

require_email_validation
------------------------

If set to ``true``, Repository emails new users a unique token
to validate their email address before permitting them to log in.


Advanced
========

.. _avatar-method:

AVATAR_METHOD
-------------

The method to use to generate the user avatar URL. Valid choices are:

    * 'gravatar' to use the gravatar.com service
    * 'default' to show a predefined static icon
    * 'static' to use a custom static URL

.. _avatar-gravatar-url:

AVATAR_GRAVATAR_URL
-------------------

A URL for a Gravatar compatible service. Default:
``https://www.gravatar.com/``. This URL is used as the prefix to build a
valid gravatar URL.

.. _avatar-static-url:

AVATAR_STATIC_URL
-----------------

A static URL to use when ``AVATAR_METHOD`` is set to ``static``. Defaults to
an empty string.

.. _constructor-timeout:

CONSTRUCTOR_TIMEOUT
-------------------

The timeout in seconds for the call to ``constructor`` while building installers, parcels and management packs.
Defaults to 60 seconds.

.. _constructor-token-timeout:

CONSTRUCTOR_TOKEN_TIMEOUT
-------------------------

To provide access to private packages while building an installer, a temporary token is created. It must
be valid during the call to ``constructor`` and it should expire soon after the call completes.
``CONSTRUCTOR_TOKEN_TIMEOUT`` sets the token's valid lifetime in seconds. Defaults to 60 seconds.
This value should be greater than or equal to ``CONSTRUCTOR_TIMEOUT``.


.. _constructor-allowed-options:

CONSTRUCTOR_ALLOWED_OPTIONS
---------------------------

A list of ``constructor`` option names that are allowed to be included in the installer construction form. The
default is ``[]`` (no options are allowed).


.. _parcels-root:

PARCELS_ROOT
------------

The prefix with which Cloudera parcels are generated.
Defaults to ``/opt/cloudera/parcels``.

.. _parcel-distro-suffixes:

PARCEL_DISTRO_SUFFIXES
----------------------

The distributions for which Cloudera parcels are generated. Defaults to
``['el5', 'el6', 'el7', 'lucid', 'precise', 'trusty', 'wheezy',
'jessie', 'squeeze', 'sles11', 'sles12']``.

For example, if you want to support only Ubuntu::

    PARCEL_DISTRO_SUFFIXES:
        - lucid
        - precise
        - trusty

.. _default-channels:

DEFAULT_CHANNELS
----------------

The Repository accounts that environments installed with the
:ref:`bundled Anaconda distributions <bundled-installers>` pull
packages from. Defaults to ``['anaconda', 'r-channel']``.

For example, to add an additional ``custom`` account::

    DEFAULT_CHANNELS:
        - anaconda
        - r-channel
        - custom

.. _constructor-tmpdir:

CONSTRUCTOR_TMPDIR
------------------

When ``constructor`` builds an installer it stores the configuration in this
temporary directory. The default is ``None``, which tells ``constructor`` to
create a temporary directory using Python's ``tempfile.mkdtemp``.

.. _standard-labels:

STANDARD_LABELS
----------------

A list of standarized labels. If a user defines a label that is
not listed as standard, a warning notice will be shown in the package's
page. Defaults to ``['main', 'dev', 'alpha', 'beta', 'broken']``.

CONDA_CACHE_SIZE
----------------

The maximum size (in bytes) of the ``repodata.json`` requests cache. Set to
``0`` to disable ``repodata.json`` caching. Default: 1 Gb. When the maximum
size is reached, the 10 least recently used entries of the cache are evicted.

CACHE_METHOD
------------

The method used for caching repodata info. It can either be ``tempfile``
(the prior method of caching) or ``diskcache``,
which uses SQLite as a back-end. Default: ``diskcache``.

REMEMBER_COOKIE_ENABLED
=======================

Sets whether to use the *remember me* cookie to keep the session alive.
If it's set to true the ``REMEMBER_COOKIE_DURATION`` setting is relevant, and if
it's set to false, the ``PERMANENT_SESSION_LIFETIME`` is relevant.
Defaults to ``true``.

PERMANENT_SESSION_LIFETIME
==========================

An integer that sets how many **minutes** the session will live. Only used when
``REMEMBER_COOKIE_ENABLED`` is false. Default is 44640 (31 days).

REMEMBER_COOKIE_DURATION
========================

An integer that sets how many **minutes** the session will live when using the
*remember me* cookie. Only used when ``REMEMBER_COOKIE_ENABLED`` is true.
Default is 525600 (365 days).

SUPERUSER_ORG_ADMIN
===================

Whether superusers should automatically be granted admin rights on organizations.
Default is ``false``.

NEXT_URL_WHITELIST
==================

List of hostnames that are marked as safe when redirecting requests due to the presence
of a "next" request parameter. It is mainly used under an Anaconda Enterprise Notebooks
Single Sign-on Set-up. The default is [] (no external redirects are safe).

NEXT_URL_WHITELIST_REGEXP
=========================

A regular expression to match hostnames that are marked as safe when redirecting requests
due to the presence of a "next" request parameter. It is mainly used under an Anaconda
Enterprise Notebooks Single Sign-on Set-up. The default is '(?!)' which matches nothing,
so only local redirects are allowed.
