Merge branch 'f-readme' into 'dev'

DOC: enhance setup documentation

See merge request caosdb/caosdb-server!66

README_SETUP.md

@@ -6,18 +6,18 @@
 * caosdb-mysqlbackend=3.0
 
 ## Third-party Software
-* >=Java 8
-* >=Apache Maven 3.0.4
-* >=Python 3.4
-* >=pip 9.0.1
-* >=git 1.9.1
-* >=Make 3.81
-* >=Screen 4.01
-* >=MySQL 5.5 (better >=5.6) or >=MariaDB 10.1
-* libpam (if PAM authentication is required)
-* unzip
-* openpyxl (for XLS/ODS export)
-* openssl (if a custom TLS certificate is required)
+* `>=Java 8`
+* `>=Apache Maven 3.0.4`
+* `>=Python 3.4`
+* `>=pip 9.0.1`
+* `>=git 1.9.1`
+* `>=Make 3.81`
+* `>=Screen 4.01`
+* `>=MySQL 5.5` (better `>=5.6`) or `>=MariaDB 10.1`
+* `libpam` (if PAM authentication is required)
+* `unzip`
+* `openpyxl` (for XLS/ODS export)
+* `openssl` (if a custom TLS certificate is required)
 
 ### Install the requirements on Debian
 On Debian, the required packages can be installed with:
@@ -30,7 +30,7 @@ versa.
 
 ## System
 
-* >=Linux 4.0.0, x86\_64, e.g. Ubuntu 14.04.1
+* `>=Linux 4.0.0`, `x86_64`, e.g. Ubuntu 18.04
 * Mounted filesytem(s) with enough space
 * Working internet connection (for up-to-date python and java libraries)
 
@@ -81,19 +81,21 @@ server:
    Alternatively, you can create a keystore from certificate files that you already have:
    - `openssl pkcs12 -export -inkey privkey.pem -in fullchain.pem -out all-certs.pkcs12`
    - `keytool -importkeystore -srckeystore all-certs.pkcs12 -srcstoretype PKCS12  -deststoretype pkcs12 -destkeystore caosdb.jks`
-
-3. Copy `conf/core/server.conf` to `conf/ext/server.conf` and change it
+3. Install/configure the MySQL back-end: see the `README_SETUP.md` of the
+   `caosdb-mysqlbackend` repository
+4. Create an authtoken config (e.g. copy `conf/core/authtoken.example.yaml` to `conf/ext/authtoken.yml` and change it)
+5. Copy `conf/core/server.conf` to `conf/ext/server.conf` and change it
    appropriately:
-    * Setup for MySQL back-end: Assuming that the mysql back-end is installed
-      (see the `README_SETUP.md` of the `caosdb-mysqlbackend` repository),
+    * Setup for MySQL back-end:
       specify the fields `MYSQL_USER_NAME`, `MYSQL_USER_PASSWORD`,
-      `MYSQL_DATABASE_NAME`, and `MYSQL_HOST`.
+	  `MYSQL_DATABASE_NAME`, and `MYSQL_HOST`.
     * Choose the ports under which CaosDB will be accessible.
     * Setup the SSL certificate: Assuming that there is an appropriate `Java Key
       Store` file (see above), change the fields `CERTIFICATES_KEY_PASSWORD`,
       `CERTIFICATES_KEY_STORE_PATH`, and `CERTIFICATES_KEY_STORE_PASSWORD`.
       Make sure that the conf file is not readable by other users because the
       certificate passwords are stored in plaintext.
+	- Set the path to the authtoken config (see step 4)
     * Set the file system paths:
       - `FILE_SYSTEM_ROOT`: The root for all the files managed by CaosDB.
       - `DROP_OFF_BOX`: Files can be put here for insertion into CaosDB.
@@ -108,9 +110,11 @@ server:
         include e.g. scripts which are maintained as part of the caosdb-webui
         repository (because they are intended for usage by the webui), you
         should add `./caosdb-webui/sss_bin/` as well.
+      - `INSERT_FILES_IN_DIR_ALLOWED_DIRS`: add mounted filesystems here that
+        shall be accessible by CaosDB
     * Maybe set another `SESSION_TIMEOUT_MS`.
     * See also [README_CONFIGURATION.md](README_CONFIGURATION.md)
-4. Copy `conf/core/usersources.ini.template` to `conf/ext/usersources.ini`.
+6. Copy `conf/core/usersources.ini.template` to `conf/ext/usersources.ini`.
     * Define the users/groups who you want to include/exclude.
     * Assign at least one user the `administration` role.
       * For example, if the admin user is called `caosdb`, there should be the
@@ -123,8 +127,9 @@ server:
       Especially that there are no `properties` (aka `keys`) without a
       `value`. An emtpy value can be represented by `""`. Comments are
       everything from `#` or `;` to the end of the line.
-5. Install the pam caller in `misc/pam_authentication/`. See
-   [the pam authentication README](misc/pam_authentication/README.md)
+7. Possibly install the PAM caller in `misc/pam_authentication/` if you have 
+   not do so already. See above.
+   
 Done!
 
 # Start Server

conf/core/server.conf

@@ -121,7 +121,7 @@ SESSION_TIMEOUT_MS=600000
 # 7days
 ONE_TIME_TOKEN_EXPIRES_MS=604800000
 
-# Path to config file for one time tokens, for example authtoken.yml.
+# Path to config file for one time tokens, see authtoken.example.yml.
 AUTHTOKEN_CONFIG=
 
 # Timeout after which a one-time token expires once it has been first consumed,