--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/src/source/config.rst	Mon Mar 05 10:40:40 2018 +0100
@@ -0,0 +1,83 @@
+.. _config:
+
+PyAMS configuration
+===================
+
+PyAMS application configuration is done via several complementary ways:
+
+- via Pyramid's configuration files located in 'etc/' folder
+
+- via settings applied to local utilities defined into ZODB
+
+- via ZCML files.
+
+
+Pyramid's configuration files
+-----------------------------
+
+PyAMS is using default Pyramid's configuration files to define settings. When using default PyAMS scaffold, these
+INI files are stored into *etc* folder. Two files are created by scaffold: a development file (*development.ini*) and
+a production file (*production.ini*) which contain nearly the same directives, except for debug toolbar (activated only
+in development), Fanstatic configuration and logging.
+
+These files are actually documented, but here are a few important directives:
+
+- **zodbconn.uri**:
+
+- **pyams.application_factory**:
+
+- **pyams.application_name**:
+
+- **pyams_xxx.tcp_handler** and **pyams_xxx.start_handler**:
+
+- **pyams_content.config.tools_name**:
+
+- **pyams_content.config.xxx_tool_factory** and **pyams_content.config.xxx_tool_name**:
+
+
+Local registry utilities
+------------------------
+
+When the ZODB is created, PyAMS automatically create and register several utilities into the *local registry* (see
+:ref:`zca`). These utilities are created with default values which can be modified through management interface when
+the application is started.
+
+Some important utilities include:
+
+- a **catalog**: the catalog has the responsibility to index every content properties which are required to make quick
+  and efficient searches. Catalog indexes are automatically created on database upgrade; management interface
+  allows administrator to get indexes properties, to get the number of indexed objects and values for a given index, and
+  to delete an index before recreating it by running the database upgrade script another time (see :ref:`scripts`).
+
+- an **internal IDs** utility:
+
+- a **language negotiator**:
+
+- a **portal templates** container:
+
+- a **security manager**:
+
+- a **sequential IDs** utility:
+
+- a **server timezone** utility:
+
+- a **user profiles** container:
+
+
+Optional utilities can also include:
+
+- an **Elasticsearch content indexer**:
+
+- a **maps manager**:
+
+- a **medias converter**:
+
+- a **tasks scheduler**:
+
+
+ZCML configuration files
+------------------------
+
+Adding more ZCML configuration directives is not mandatory in any way but can be useful in several use cases. For
+example, templates can't be overriden via Python annotations without creating a new subclass; this can be done
+easily via ZCML.