From 35999a1bed4fd1feff097779e8d3cdf25e81efc4 Mon Sep 17 00:00:00 2001 From: David Moreau Simard Date: Fri, 25 Jan 2019 12:29:11 -0500 Subject: [PATCH] Misc updates to security and configuration documentation - Improve docs on ARA_ENV - Refresh outdated defaults - Fix broken link on ara-web git repo Change-Id: Ib882dc7415cc7b50f35a3a6bfbf1bc0fbe401dc8 --- doc/source/configuring.rst | 68 ++++++++++++++++++++++++-------------- doc/source/security.rst | 4 +-- 2 files changed, 45 insertions(+), 27 deletions(-) diff --git a/doc/source/configuring.rst b/doc/source/configuring.rst index 0761ffd..405cf0b 100644 --- a/doc/source/configuring.rst +++ b/doc/source/configuring.rst @@ -22,7 +22,7 @@ For more details, click on the configuration parameters. +--------------------------------+------------------------------------------------------+------------------------------------------+ | Environment Variable | Usage | default | +================================+======================================================+==========================================+ -| ARA_BASE_DIR_ | Default directory for storing data and configuration | ``~/.ara`` | +| ARA_BASE_DIR_ | Default directory for storing data and configuration | ``~/.ara/server`` | +--------------------------------+------------------------------------------------------+------------------------------------------+ | ARA_SETTINGS_ | Path to an ara-server configuration file | ``None`` | +--------------------------------+------------------------------------------------------+------------------------------------------+ @@ -32,7 +32,7 @@ For more details, click on the configuration parameters. +--------------------------------+------------------------------------------------------+------------------------------------------+ | ARA_WRITE_LOGIN_REQUIRED_ | Whether authentication is required for writing data | ``False`` | +--------------------------------+------------------------------------------------------+------------------------------------------+ -| ARA_ENV_ | Environment to load configuration for | ``default`` | +| ARA_ENV_ | Environment to load configuration for | ``development`` | +--------------------------------+------------------------------------------------------+------------------------------------------+ | ARA_LOG_LEVEL_ | Log level of the different components | ``INFO`` | +--------------------------------+------------------------------------------------------+------------------------------------------+ @@ -82,15 +82,15 @@ ARA_BASE_DIR - **Environment variable**: ``ARA_BASE_DIR`` - **Configuration file variable**: ``BASE_DIR`` - **Type**: ``string`` -- **Default**: ``~/.ara`` +- **Default**: ``~/.ara/server`` The directory where data will be stored by default. Changing this location influences the default root directory for the ``ARA_STATIC_ROOT`` and ``ARA_DATABASE_NAME`` parameters. -This is also the default location where the configuration template -(``default_config.yaml``) is generated by ARA. +This is also used to determine the location where the default configuration +file, ``settings.yaml``, will be generated by ara-server. ARA_SETTINGS ~~~~~~~~~~~~ @@ -102,10 +102,10 @@ ARA_SETTINGS - **Provided by**: dynaconf_ Location of an ara-server configuration file to load settings from. -``ara-server`` generates a default configuration template at ``~/.ara/server/default_config.yaml`` -that you can use to get started. +``ara-server`` generates a default configuration file at +``~/.ara/server/settings.yaml`` that you can use to get started. -Note that while the configuration template is in YAML by default, it is possible +Note that while the configuration file is in YAML by default, it is possible to have configuration files written in ``ini``, ``json`` and ``toml`` as well. Settings and configuration parsing in ara-server is provided by the dynaconf_ @@ -119,7 +119,7 @@ ARA_ENV - **Environment variable**: ``ARA_ENV`` - **Configuration file variable**: None, this variable defines which section of a configuration file is loaded. - **Type**: ``string`` -- **Default**: ``default`` +- **Default**: ``development`` - **Provided by**: dynaconf_ If you are using ara-server in different environments and would like keep your @@ -128,22 +128,42 @@ environment's settings. For example:: - # Increase verbosity and debugging for the "dev" environment - dev: - LOG_LEVEL: DEBUG - DEBUG: TRUE - SECRET_KEY: dev - # Make sure we're not running DEBUG in production and use standard verbosity. - production: + # Default settings are used only when not provided in the environments + default: + READ_LOGIN_REQUIRED: false + WRITE_LOGIN_REQUIRED: false LOG_LEVEL: INFO - DEBUG: FALSE + DEBUG: false + # Increase verbosity and debugging for the default development environment + development: + LOG_LEVEL: DEBUG + DEBUG: true + SECRET_KEY: dev + # Enable write authentication when using the production environment + production: + WRITE_LOGIN_REQUIRED: true SECRET_KEY: prod -In order to use the settings from the "dev" environment, you would set -``ARA_ENV`` to ``dev``. +With the example above, loading the development environment would yield the +following settings: + +- READ_LOGIN_REQUIRED: ``false`` +- WRITE_LOGIN_REQUIRED: ``false`` +- LOG_LEVEL: ``DEBUG`` +- DEBUG: ``true`` +- SECRET_KEY: ``dev`` Another approach to environment-specific configuration is to use -``ARA_SETTINGS`` and keep your settings in different files instead. +``ARA_SETTINGS`` and keep your settings in different files such as ``dev.yaml`` +or ``prod.yaml`` instead. + +.. tip:: + If it does not exist, ara-server will generate a default configuration + file at ``~/.ara/server/settings.yaml``. + This generated file sets up all the configuration keys in the **default** + environment. + This lets users override only the parameters they are interested in for + specific environments. ARA_READ_LOGIN_REQUIRED ~~~~~~~~~~~~~~~~~~~~~~~ @@ -249,10 +269,8 @@ ARA_CORS_ORIGIN_WHITELIST Hosts in the whitelist for `Cross-Origin Resource Sharing `_. -This setting is typically used in order to allow the API and a web interface -(*such as ara-web_*) to talk to each other. - -.. _ara-web: https://github.com/openstack/ara-web +This setting is typically used in order to allow the API and a web client +(such as `ara-web `_) to talk to each other. ARA_ALLOWED_HOSTS ~~~~~~~~~~~~~~~~~ @@ -341,7 +359,7 @@ ARA_DATABASE_NAME The name of the database. When using sqlite, this is the absolute path to the sqlite database file. -When using drivers such as MySQL or Postgresql, it's the name of the database. +When using drivers such as MySQL or PostgreSQL, it's the name of the database. ARA_DATABASE_USER ~~~~~~~~~~~~~~~~~ diff --git a/doc/source/security.rst b/doc/source/security.rst index d61a66d..7e242f9 100644 --- a/doc/source/security.rst +++ b/doc/source/security.rst @@ -3,8 +3,8 @@ Authentication and security =========================== -ara-server ships with a default configuration that privileges simplicity and -lets users get started quickly. +ara-server ships with a default configuration that emphasizes simplicity to +let users get started quickly. By default: