summaryrefslogtreecommitdiff
path: root/configuration-basics.rst
diff options
context:
space:
mode:
authorMarcello Stanisci <marcello.stanisci@inria.fr>2016-09-19 11:52:32 +0200
committerMarcello Stanisci <marcello.stanisci@inria.fr>2016-09-19 11:52:32 +0200
commit9939f9465b72780427897a201a37dcf58bada207 (patch)
tree991e1fb5ba7f1ed06303a30b7f4556e75f09766e /configuration-basics.rst
parent9a8b21ef67497ae49be40c6891f3366b6252be26 (diff)
downloaddocs-9939f9465b72780427897a201a37dcf58bada207.tar.gz
docs-9939f9465b72780427897a201a37dcf58bada207.tar.bz2
docs-9939f9465b72780427897a201a37dcf58bada207.zip
documenting configuration facility
Diffstat (limited to 'configuration-basics.rst')
-rw-r--r--configuration-basics.rst68
1 files changed, 68 insertions, 0 deletions
diff --git a/configuration-basics.rst b/configuration-basics.rst
new file mode 100644
index 00000000..9296a2b4
--- /dev/null
+++ b/configuration-basics.rst
@@ -0,0 +1,68 @@
+..
+ This file is part of GNU TALER.
+ Copyright (C) 2014, 2015, 2016 INRIA
+ TALER is free software; you can redistribute it and/or modify it under the
+ terms of the GNU General Public License as published by the Free Software
+ Foundation; either version 2.1, or (at your option) any later version.
+ TALER is distributed in the hope that it will be useful, but WITHOUT ANY
+ WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
+ A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
+ You should have received a copy of the GNU Lesser General Public License along with
+ TALER; see the file COPYING. If not, see <http://www.gnu.org/licenses/>
+
+ @author Marcello Stanisci
+
+======================
+Configuration in Taler
+======================
+
+In Taler realm, any component obeys to the same pattern to get configuration
+values. According to this pattern, once the component has been installed, the
+installation deploys default values in `${prefix}/share/taler/config.d/`, in
+`.conf` files. In order to override these defaults, the user can write a custom
+`.conf` file and either pass it to the component at execution time, or name it
+`taler.conf` and place it under `$HOME/.config/`.
+
+
+--------------------
+Configuration format
+--------------------
+
+A config file is a text file containing `sections`, and each section contains
+its `values`. The right format follows::
+
+ [section1]
+ value1 = string
+ value2 = 23
+
+ [section2]
+ value21 = string
+ value22 = /path22
+
+Throught any configuration file, it is possible to use ``$``-prefixed variables,
+especially when a value needs a pathname. Some of them are automatically resolved,
+like ``${TALER_DATA_HOME}``, ``${TALER_RUNTIME_DIR}``, or ``${HOME}``. (FIXME: explain
+how/where/when those defaults get resolved) Other variables can be defined under the
+`paths` section. For example::
+
+ [paths]
+ TALER_DEPLOYMENT_SHARED = ${HOME}/shared-data
+ ..
+ [section-x]
+ path-x = ${TALER_DEPLOYMENT_SHARED}/x
+
+The utility ``taler-config``, which gets installed along with the exchange, serves to get and
+set configuration values without directly editing the `.conf`. See ``taler-config --help``.
+
+Note that, in this stage of development, the file ``$HOME/.config/taler.conf``
+can contain sections for *all* the component. For example, both an exchange and
+a bank can read values from it.
+
+The repository ``git://taler.net/deployment`` contains examples of configuration
+file used in our demos. See under ``deployment/config``.
+
+.. note::
+
+ Expectably, some components will not work just by using default values, as their
+ work is often interdependent. For example, a merchant needs to know an exchange
+ URL, or a database name.