diff --git a/README_SETUP.md b/README_SETUP.md
index 896ee67ed03a493379c182ef617f0654a18f3ae4..7f2fbdd7769618da573745321546214599c3548e 100644
--- a/README_SETUP.md
+++ b/README_SETUP.md
@@ -1,21 +1,141 @@
-# Installation
-python3.6 is required.
-pip install . --user
-pip install tox --user
+# Getting started with pycaosdb #
-# Run Unit Tests
+## Installation ##
+
+### Requirements ###
+
+Pycaosdb needs at least Python 3.6. Additionally, the following packages are required (they will
+typically be installed automatically):
+
+- `lxml`
+- `PyYaml`
+- `PySocks`
+
+### How to install ###
+
+#### Linux ####
+
+Make sure that Python (at least version 3.6) and pip is installed, using your system tools and
+documentation.
+
+Then open a terminal and continue in the [Generic installation](#generic-installation) section.
+
+#### Windows ####
+
+If a Python distribution is not yet installed, we recommend Anaconda Python, which you can download
+for free from [https://www.anaconda.com](https://www.anaconda.com). The "Anaconda Individual Edition" provides most of all
+packages you will ever need out of the box. If you prefer, you may also install the leaner
+"Miniconda" installer, which allows you to install packages as you need them.
+
+After installation, open an Anaconda prompt from the Windows menu and continue in the [Generic
+installation](#generic-installation) section.
+
+#### Generic installation ####
+
+To install pycaosdb locally, use `pip3` (also called `pip` on some systems):
+
+```sh
+pip3 install --user caosdb
+```
+
+---
+
+Alternatively, obtain the sources from GitLab and install from there (`git` must be installed for
+this option):
+
+```sh
+git clone https://gitlab.com/caosdb/caosdb-pylib
+cd caosdb-pylib
+pip3 install --user .
+```
+
+## 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/master/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/master/examples/pycaosdb.ini) in
+the examples folder of the source code.
+
+## Try it out ##
+
+Start Python and check whether the you can access the database. (You will be asked for the
+password):
+
+```python
+In [1]: import caosdb as db
+In [2]: db.Info()
+Please enter the password: # It's `caosdb` for the demo server.
+Out[2]: Connection to CaosDB with 501 Records.
+```
+
+Note: This setup will ask you for your password whenever a new connection is created. If you do not
+like this, check out the "Authentication" section in the [configuration documentation](configuration.md).
+
+Now would be a good time to continue with the [tutorials](tutorials.html).
+
+## Run Unit Tests
tox
-# Code Formatting
+## Code Formatting
autopep8 -i -r ./
-# Documentation #
+## Documentation #
Build documentation in `build/` with `make doc`.
-## Requirements ##
+### Requirements ##
-- sphinx
-- sphinx-autoapi
-- recommonmark
+- `sphinx`
+- `sphinx-autoapi`
+- `recommonmark`
diff --git a/examples/pycaosdb.ini b/examples/pycaosdb.ini
index b5d7defc9d9125d300a12c4b1cb0b1015c073b73..edc32195fbb364bb355d67b8733e8c7bccbb0d34 100644
--- a/examples/pycaosdb.ini
+++ b/examples/pycaosdb.ini
@@ -54,6 +54,11 @@
# corresponding attribute in the Python ssl module.
# ssl_version=PROTOCOL_TLS
+# The debug key allows control the verbosity. Set it to 1 or 2 in case you
+# want to see debugging output or if you want to learn more about
+# the internals of the protocol. 0 disables debugging output.
+# debug=0
+
# You can define a socket proxy to be used.
# This is for the case that the server sits behind a firewall which is being
# tunnelled with a socket proxy (SOCKS4 or SOCKS5) (e.g. via ssh's -D option or
diff --git a/src/doc/README_SETUP.md b/src/doc/README_SETUP.md
new file mode 120000
index 0000000000000000000000000000000000000000..88332e357f5e06f3de522768ccdcd9e513c15f62
--- /dev/null
+++ b/src/doc/README_SETUP.md
@@ -0,0 +1 @@
+../../README_SETUP.md
\ No newline at end of file
diff --git a/src/doc/getting_started.md b/src/doc/getting_started.md
deleted file mode 100644
index 3af60d4c05027a3a0879aa2fea51b8d98c75fed8..0000000000000000000000000000000000000000
--- a/src/doc/getting_started.md
+++ /dev/null
@@ -1,78 +0,0 @@
-# Getting started with pycaosdb #
-
-## Installation ##
-
-### Requirements ###
-
-Pycaosdb needs at least Python 3.6. Additionally, the following packages are required (they will
-typically be installed automatically):
-
-- `lxml`
-- `PyYaml`
-- `PySocks`
-
-### How to install ###
-
-#### Linux ####
-
-Make sure that Python (at least version 3.6) and pip is installed, using your system tools and
-documentation.
-
-Then open a terminal and continue in the [Generic installation](#generic-installation) section.
-
-#### Windows ####
-
-If a Python distribution is not yet installed, we recommend Anaconda Python, which you can download
-for free from [https://www.anaconda.com](https://www.anaconda.com). The "Anaconda Individual Edition" provides most of all
-packages you will ever need out of the box. If you prefer, you may also install the leaner
-"Miniconda" installer, which allows you to install packages as you need them.
-
-After installation, open an Anaconda prompt from the Windows menu and continue in the [Generic
-installation](#generic-installation) section.
-
-#### Generic installation ####
-
-To install pycaosdb locally, use `pip3` (also called `pip` on some systems):
-
-```sh
-pip3 install --user caosdb
-```
-
----
-
-Alternatively, obtain the sources from GitLab and install from there (`git` must be installed for
-this option):
-
-```sh
-git clone https://gitlab.com/caosdb/caosdb-pylib
-cd caosdb-pylib
-pip3 install --user .
-```
-
-## Configuration ##
-
-Download [the sample configuration file](https://gitlab.com/caosdb/caosdb-pylib/-/raw/dev/examples/pycaosdb.ini) and save it as `.pycaosdb.ini` in your home directory or
-as `pycaosdb.ini` in your current working directory.
-
-Now, change 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 demo instances like https://demo.indiscale.com, `admin`
-and `caosdb` often works).
-
-More information about the configuration is available [in this documentation](configuration.md) as well.
-
-## Try it out ##
-
-Start Python and check whether the you can access the database. (You will be asked for the
-password):
-
-```python
-In [1]: import caosdb as db
-In [2]: db.Info()
-Please enter the password: # It's `caosdb` for the demo server.
-Out[2]: Connection to CaosDB with 501 Records.
-```
-
-Note: This setup will ask you for your password whenever a new connection is created. If you do not
-like this, check out the "Authentication" section in the [configuration documentation](configuration.md).
-
-Now would be a good time to continue with the [tutorials](tutorials.html).
diff --git a/src/doc/index.rst b/src/doc/index.rst
index 7d988c68557eed525b437ff36beeae14b181b2e5..c56d2f1330db838cc89935731b7194def1e45662 100644
--- a/src/doc/index.rst
+++ b/src/doc/index.rst
@@ -7,7 +7,7 @@ Welcome to pycaosdb's documentation!
:caption: Contents:
:hidden:
- Getting started <getting_started>
+ Getting started <README_SETUP>
tutorials/index
Concepts <concepts>
Configuration <configuration>