diff --git a/README_SETUP.md b/README_SETUP.md index afc63592e7797adafa8cd58df37d0aff0a8d5b15..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: @@ -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.