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

.. contents::
    :local:

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

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

``$PREFIX`` is the location where Anaconda Repository was installed.

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

..  BRAND
    CACHE_DIR
    CDN
    DOCUMENTATION_DIR
    JOURNAL_FILE
    LICENCES_DIR
    LOAD_FILES
    LOGGING
    LOG_DIR
    MAX_IPYNB_SIZE
    PASSWORD_RULES
    PASSWORD_SALT
    PRIVATE_KEY_PATH
    PROPAGATE_EXCEPTIONS
    SECRET_KEY
    csrf_enabled
    deploy_type
    enabled_features
    login_enabled
    queue_prefix
    signup_enabled
    upload_endpoint


Database
--------

Anaconda Repository uses MongoDB as the database backend.

MONGO_URL
=========

A `MongoDB connection URI <https://docs.mongodb.com/manual/reference/connection-string/>`_ 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 Anaconda Repository will store its data.

MQ_DBNAME
=========

The MongoDB database where Anaconda Repository will store data used for asynchronous processing.

MONGO_REPLICA_SET
=================

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

File storage
------------

Anaconda 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).

fs_storage_root
===============

The absolute path to a directory where Anaconda Repository will store all uploaded packages, if configured to use
file-system storage.

PACKAGE_BUCKET_ID
=================

The name of an AWS S3 bucket where Anaconda Repository will store uploaded packages, if configured to use AWS S3 storage.

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

Web server
----------

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``, Anaconda Repository will serve ``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 Anaconda Repository will set on the session cookie. If this is not set, the cookie will be valid
for all subdomains of ``SERVER_NAME``. See :ref:`here <securing-user-created-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, Anaconda Repository will only serve rendered notebooks from this domain.

See :ref:`here <securing-user-created-content>`.

ssl_options
===========

Anaconda 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.

PREFERRED_URL_SCHEME
====================

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

gunicorn
========

Anaconda 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 that a worker is allowed to process a request for, before being forcefully terminated.
Defaults to 30.

workers
~~~~~~~

The number of workers that gunicorn will spawn to serve Anaconda Repository. Defaults to 2 × the number of CPUs + 1.

Authentication
--------------

AUTH_TYPE
=========

The method Anaconda Repository will use 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:
        URI: ldap://ldap.server
        BIND_DN: cn=Anaconda Repository,cn=Users,dc=example,dc=com
        BIND_AUTH: Pa55w0rd

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

        KEY_MAP:
            name: cn

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

Email
-----

Anaconda Repository can be configured to send email after launching kapsels. 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``, Anaconda Repository will attempt 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``, Anaconda Repository will send 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 Anaconda Repository will use as sender.

require_email_validation
========================

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


Advanced
--------

.. _parcels-root:

PARCELS_ROOT
============

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

.. _parcel-distro-suffixes:

PARCEL_DISTRO_SUFFIXES
======================

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

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

    PARCEL_DISTRO_SUFFIXES:
        - lucid
        - precise
        - trusty
