diff --git a/README_SETUP.md b/README_SETUP.md
index f9ba2a93e82ac6ca5673cada28f6c706c802dd02..0de7b12b500cf4f9addeb52bb14ed19a38f560ee 100644
--- a/README_SETUP.md
+++ b/README_SETUP.md
@@ -1,5 +1,7 @@
# 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:
@@ -218,17 +224,26 @@ pip3 install .
### 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, that 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.
+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 server, mysqlbackend and webui to the host machine, also copy the complete `.m2` folder to the **home directory of the user that is running the CaosDB server**.
+- 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.
+- 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
@@ -242,12 +257,12 @@ Make sure that you:
### How can I run the CaosDB server using ports 443 and 80?
-On standard linux setups, ports 443 and 80 must not be opened by non-root processes.
+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
+- 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)
@@ -257,6 +272,7 @@ Here are some resources to read about these options:
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`
-- Set permissions of these files to 777
+- 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`
+ `authbind --deep make run`. The `--deep` option is necessary because the
+ server starts a subprocess which actually opens the ports.