From dd86fe37f2298a8414104a6cad3cb8a9a850d275 Mon Sep 17 00:00:00 2001 From: Daniel <d.hornung@indiscale.com> Date: Mon, 4 Apr 2022 18:37:09 +0200 Subject: [PATCH] DOC: Merged configuration sections of the documentation. --- README_SETUP.md | 56 ++-------------------------------------- src/doc/configuration.md | 16 +++++++++++- 2 files changed, 17 insertions(+), 55 deletions(-) diff --git a/README_SETUP.md b/README_SETUP.md index e58f934c..374ea306 100644 --- a/README_SETUP.md +++ b/README_SETUP.md @@ -82,60 +82,8 @@ pip3 install --user .[jsonschema] ## Configuration ## -The configuration is done using `ini` configuration files. -PyCaosDB tries to read from the inifile specified in the environment variable `PYCAOSDBINI` or -alternatively in `~/.pycaosdb.ini` upon import. After that, the ini file `pycaosdb.ini` in the -current working directory will be read additionally, if it exists. - -Here, we will look at the most common configuration options. For a full and -comprehensive description please check out -[pycaosdb.ini file](https://gitlab.com/caosdb/caosdb-pylib/-/blob/main/examples/pycaosdb.ini) -You can download this file and use it as a starting point. - - -Typically, you need to change at least the `url` and `username` fields as required. -(Ask your CaosDB administrator or IT crowd if -you do not know what to put there, but for the demo instances https://demo.indiscale.com, `username=admin` -and `password=caosdb` should work). - -### Authentication ### - -The default configuration (that your are asked for your password when ever a connection is created -can be changed by setting `password_method`: - -* with `password_method=input` password (and possibly user) will be queried on demand (**default**) -* use the password manager [pass](https://www.passwordstore.org) by using `pass` as value, see also the [ArchWiki - entry](https://wiki.archlinux.org/index.php/Pass#Basic_usage). This also requires `password_identifier` which refers to the identifier within pass - for the desired password. -* install the python package [keyring](https://pypi.org/project/keyring), to use the system keyring/wallet (macOS, GNOME, KDE, - Windows). The password will be queried on first usage. -* with `password_method=plain` (**strongly discouraged**) - -The following illustrates the recommended options: - -```ini -[Connection] -# using "pass" password manager -#password_method=pass -#password_identifier=... - -# using the system keyring/wallet (macOS, GNOME, KDE, Windows) -#password_method=keyring -``` - -### SSL Certificate ### -In some cases (especially if you are testing CaosDB) you might need to supply -an SSL certificate to allow SSL encryption. - -```ini -[Connection] -cacert=/path/to/caosdb.ca.pem -``` - -### Further Settings ### -As mentioned above, a complete list of options can be found in the -[pycaosdb.ini file](https://gitlab.com/caosdb/caosdb-pylib/-/blob/main/examples/pycaosdb.ini) in -the examples folder of the source code. +The configuration is done using `ini` configuration files. The content of these configuration files +is described in detail in the [configuration section of the documentation](https://docs.indiscale.com/caosdb-pylib/configuration.html). ## Try it out ## diff --git a/src/doc/configuration.md b/src/doc/configuration.md index 802da4e9..02cbbd7b 100644 --- a/src/doc/configuration.md +++ b/src/doc/configuration.md @@ -4,6 +4,15 @@ PyCaosDB tries to read from the inifile specified in the environment variable `P alternatively in `~/.pycaosdb.ini` upon import. After that, the ini file `pycaosdb.ini` in the current working directory will be read additionally, if it exists. +Here, we will look at the most common configuration options. For a full and comprehensive +description please check out the [example pycaosdb.ini file](https://gitlab.com/caosdb/caosdb-pylib/-/blob/main/examples/pycaosdb.ini). You can download this file and use +it as a starting point. + + +Typically, you need to change at least the `url` and `username` fields as required. (Ask your +CaosDB administrator or IT crowd if you do not know what to put there, but for the demo instance at +https://demo.indiscale.com, `username=admin` and `password=caosdb` should work). + ## Authentication ## The default configuration (that your are asked for your password when ever a connection is created @@ -17,6 +26,8 @@ can be changed by setting `password_method`: Windows). The password will be queried on first usage. * with `password_method=plain` (**strongly discouraged**) +The following illustrates the recommended options: + ```ini [Connection] username=YOUR_USERNAME @@ -35,7 +46,10 @@ username=YOUR_USERNAME ## SSL Certificate ## -You can set the pass to the ssl certificate to be used: +In some cases (especially if you are testing CaosDB) you might need to supply an SSL certificate to +allow SSL encryption. + +The `cacert` option sets the path to the ssl certificate for the connection: ```ini [Connection] -- GitLab