Merge "Misc updates to security and configuration documentation"

recordsansible · Jan 25, 2019 · 4238a0f · 4238a0f
2 parents 706c235 + 35999a1
commit 4238a0f
Show file tree

Hide file tree

Showing 2 changed files with 43 additions and 25 deletions.
diff --git 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:
+    # 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
+    # Increase verbosity and debugging for the default development environment
+    development:
         LOG_LEVEL: DEBUG
-        DEBUG: TRUE
+        DEBUG: true
         SECRET_KEY: dev
-    # Make sure we're not running DEBUG in production and use standard verbosity.
+    # Enable write authentication when using the production environment
     production:
-        LOG_LEVEL: INFO
-        DEBUG: FALSE
+        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 <https://en.wikipedia.org/wiki/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 <https://github.com/openstack/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
@@ -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: