Merge branch 'f-doc-troubleshooting' into 'dev'

DOC: section for troubleshooting and offline installation in setup readme

See merge request !17

README_SETUP.md

 # Getting Started with the CaosDB Server
-Here, you find information on requirements, the installation, configuration and more.
+
+Here, you find information on requirements, the installation, configuration and
+more.
 
 ## Requirements
 
@@ -9,6 +11,7 @@ Here, you find information on requirements, the installation, configuration and
 * caosdb-mysqlbackend=3.0
 
 ### Third-party Software
+
 * `>=Java 8`
 * `>=Apache Maven 3.0.4`
 * `>=Python 3.4`
@@ -24,6 +27,7 @@ Here, you find information on requirements, the installation, configuration and
 - `easy-units` >= 0.0.1    https://gitlab.com/timm.fitschen/easy-units
 
 #### Install the requirements on Debian
+
 On Debian, the required packages can be installed with:
 
     apt-get install git make mariadb-server maven openjdk-11-jdk-headless \
@@ -80,7 +84,8 @@ server:
      Replace `localhost` by your host name, if you want.
    - `keytool -importkeystore -srckeystore caosdb.jks -destkeystore caosdb.p12 -deststoretype PKCS12 -srcalias selfsigned`
    - Export the public part only: `openssl pkcs12 -in caosdb.p12 -nokeys -out cert.pem`.
-     The resulting `cert.pem` can safely be given to users to allow ssl verification.
+     The resulting `cert.pem` can safely be given to users to allow ssl
+     verification.
    - You can check the content of the certificate with `openssl x509 -in cert.pem -text`
 
    Alternatively, you can create a keystore from certificate files that you already have:
@@ -88,7 +93,8 @@ server:
    - `keytool -importkeystore -srckeystore all-certs.pkcs12 -srcstoretype PKCS12  -deststoretype pkcs12 -destkeystore caosdb.jks`
 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)
+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:
@@ -213,3 +219,60 @@ cd javasphinx
 git checkout 659209069603a
 pip3 install .
 ```
+
+## Installation under special conditions
+
+### Installation without or with restricted internet connection on the host system
+
+It is of course possible to install CaosDB on servers which do not have an
+internet connection or only have limited access to the internet.
+However, maven, which is used to build the CaosDB server, typically accesses
+the internet very often, and some reconfiguration might be necessary to prevent
+timeout issues and similar headache.
+
+A recommendation to proceed is:
+- Clone the repositories (caosdb-server, caosdb-mysqlbackend and subrepository
+  caosdb-webui) on a second machine that has internet connection.
+- Run `make install` and `make run` in the caosdb-server repository. This will
+  download all required dependencies and setup all maven-related artifacts in
+  a folder called `.m2` typically located in the home directory.
+- In addition to copying over the repositories for the server, mysqlbackend and
+  webui to the target host machine, also copy the complete `.m2` folder to the
+  **home directory of the user that is running the CaosDB server**.
+- On the host machine, open the file `pom.xml` in the server repository.
+- Look for the section `<repositories>`. There should be a `<respository>` with
+  `<id>local-maven-repo</id>`. It should be moved on top of the list of
+  repositories, so that the xml block appears directly after `<repositories>`
+  and before the repository maven-central.
+
+## Troubleshooting / FAQ
+
+### I set up and run the server, but I get an error that XSLT parsing failed in the WebUI
+
+You probably forgot to `make` the webui.
+
+Make sure that you:
+- Installed the WebUI according to the section [Web UI]
+- Run `make install` in the webui sub folder
+
+### How can I run the CaosDB server using ports 443 and 80?
+
+On standard linux setups, ports 443 and 80 cannot be opened by non-root processes.
+
+There are multiple solutions for this problem:
+- Use iptables to redirect a low port to a high port.
+- Use `CAP_NET_BIND_SERVICE`.
+- Use authbind.
+
+Here are some resources to read about these options:
+- [Question on Stackoverflow](https://stackoverflow.com/questions/413807/is-there-a-way-for-non-root-processes-to-bind-to-privileged-ports-on-linux)
+- [Questoin on Superuser](https://superuser.com/questions/710253/allow-non-root-process-to-bind-to-port-80-and-443)
+- [iptables tutorial](https://www.frozentux.net/iptables-tutorial/iptables-tutorial.html#REDIRECTTARGET)
+
+Using authbind is a simple solution that is briefly described here:
+- Install the package authbind
+- Create (empty) files `/etc/authbind/byport/80` (and `.../443`), e.g. using `touch`
+- Grant execution permissions for the user who runs the server to the new files.
+- Run the CaosDB server using authbind with the `--deep` option:
+  `authbind --deep make run`. The `--deep` option is necessary because the
+  server starts a subprocess which actually opens the ports.