CHANGELOG.md

+## [1.1.1](https://gitlab.gwdg.de/fe/technical-reference/compare/v1.1.0...v1.1.1) (2020-07-23)
+
+
+### Bug Fixes
+
+* Correct typos and add crlf after each sentence ([f9fcb0a](https://gitlab.gwdg.de/fe/technical-reference/commit/f9fcb0a86e8b10acccaf731bf5b8685308f55292))
+
 # [1.1.0](https://gitlab.gwdg.de/fe/technical-reference/compare/v1.0.0...v1.1.0) (2020-06-22)
 
 

README.md

@@ -2,14 +2,21 @@
 
 Guidelines and references for software development in RDD
 
-To compile in markdown, use
+To create main markdown document and compile to PDF, use
 
 ```bash
-pandoc --template=rdd.latex rdd-technical-reference.md -o rdd-technical-reference.pdf
+cat technical-reference-main.txt | while read LINE; do cat $LINE >> technical-reference.md ; done
+pandoc --template=rdd.latex technical-reference.md -o technical-reference.pdf
 ```
 
 Inspired by the [EURISE Network Technical Reference](https://github.com/eurise-network/technical-reference).
 
+
+## Sources and PDF
+
+The sources and the PDF of this reference are available continuously with every release here: https://gitlab.gwdg.de/fe/technical-reference/-/releases
+
+
 ## Contributing
 
 Commits have to be made following a certain convention that is defined by the
@@ -25,8 +32,7 @@ npm install
 
 You can now run a commit using commitizen with `git cz`.
 
-To run commitizen on `git commit` rather than on `git cz`, update or create `.git/hooks/prepare-commit-msg` with the
-following code:
+To run commitizen on `git commit` rather than on `git cz`, update or create `.git/hooks/prepare-commit-msg` with the following code:
 
 ```bash
 #!/bin/bash
@@ -41,3 +47,5 @@ that should reflect the extent of your contribution:
 
 These commit types trigger a `patch` or `minor` release when merged into the `master` branch.
 To trigger a `major` release, please consult your fellow contributors and mark one of your commits with a `BREAKING CHANGE`.
+
+The `master` branch is protected for direct commits, so please use feature branches and do merge them into `master`.

chapters/deployment-maintenance.md

@@ -3,21 +3,33 @@
 
 ### Puppet
 
-For server configuration and setup we use puppet for most servers. The main puppet code is provided in GitLab
-<https://gitlab.gwdg.de/dariah-de-puppet>. The DARIAH-DE and TextGrid Repository module (dhrep) is contained in GitHub
-<https://github.com/DARIAH-DE/puppetmodule-dhrep>.
+For server configuration and setup we use puppet for all of our FE maintained servers. The main puppet code is provided in GitLab <https://gitlab.gwdg.de/dariah-de-puppet>. Please see the [project's README file](https://gitlab.gwdg.de/dariah-de-puppet/dariah_de_puppet/-/blob/master/Readme.md) for detailed information.
+
+The DARIAH-DE and TextGrid Repository module (dhrep) is contained in GitHub <https://github.com/DARIAH-DE/puppetmodule-dhrep>.
+
+There is a task force in FE/GWDG for maintaining the Puppet code and related issues, that plans and performs sprints for planning, implementing, and documenting current Puppet issues such as major updates or discussing module usage.
 
 ### Monitoring
 
-- Icinga probes for DARIAH-DE services <https://icinga.de.dariah.eu/icinga>
+#### Icinga
+
+We are using the DARIAH-DE Monitoring system for our RDD server, that is at the moment installed at <https://icinga.de.dariah.eu/icinga>.
+
+Different kinds of probes are implemented, mostly HTTP checks (for external HTTP function monitoring) and NRPE checks (for internal server probes such as memory checks, ping, etcpp), NRPE probes are configured using Puppet.
+
+The configuration is available at <https://projects.gwdg.de/projects/dariah-nagios/repository> and can be accessed by all rdd developers (rdd group settings are updated regularly).
+
+If a new contribution to the config is pushed, the configuration will build every 30 minutes at <https://icinga.de.dariah.eu/jenkins/>, please check the outcome of your configuration changes there every time you contribute. You have to be a member of the DARIAH LDAP group “jenkins-admin“, please use the DARIAH AAI <https://auth.de.dariah.eu> for membership.
+
+Icinga's configuration is roughly build on hosts, service probes, contacts, and contact groups. So the members of the contact group “sub-fe-geobrowser-notify“ will be notified via email, if a service probe this contact group is assigned to fails. The service and host groups are mainly used for visualizing.
+
+The migration to Icinga2 and the CLARIN-D monitoring at <https://monitoring.clarin.eu> is already in progress and will soon take over (planed for Fall 2020).
+
 
 #### Real time statistics / metrics
 
-To view real time metrics from our servers or applications we use [Grafana](https://grafana.com/), which is available
-at <https://metrics.gwdg.de> inside GoeNet.
-Grafana retrieves its data from influxdb. [Telegraf](https://github.com/influxdata/telegraf) can be used to store data
-from the servers in that database. It is easy to enable telegraf on puppet configured servers. Telegraf stores metrics
-from the server in the influxdb.
+To view real time metrics from our servers or applications we use [Grafana](https://grafana.com/), which is available at <https://metrics.gwdg.de> inside GoeNet.
+Grafana retrieves its data from influxdb. [Telegraf](https://github.com/influxdata/telegraf) can be used to store data from the servers in that database. It is easy to enable telegraf on puppet configured servers. Telegraf stores metrics from the server in the influxdb.
 
 Some system statistics monitored by telegraf in our current puppet setup:
 
@@ -25,6 +37,7 @@ Some system statistics monitored by telegraf in our current puppet setup:
 - Memory
 - Space
 - Apache
+- Tomcat usage
 - ...
 
 Telegraf collects statistics with input plugins. A list of plugins is

chapters/documentation.md

@@ -54,11 +54,28 @@ Call diagrams can be useful to follow code and service calls and should be exist
 
 - [Example for Java](https://lab.sub.uni-goettingen.de/self-updating-docs.html)
 
-- Links to callers must not be listed in the documentation, because this info will be deprecated soon. It is strongly
-recommended to use call stacks of tools like Eclipse (Java) and/or Call Graph Module (SADE).
+- Links to callers must not be listed in the documentation, because this info will be deprecated soon.
+It is strongly recommended to use call stacks of tools like Eclipse (Java) and/or Call Graph Module (SADE).
 
-- Document REST-APIs using [openAPI](https://github.com/OAI/OpenAPI-Specification) if possible. OpenAPI docs should be
-located at `/doc/api` on servers.
+- Document REST-APIs using [OpenAPI](https://github.com/OAI/OpenAPI-Specification) if possible.
+OpenAPI doc should be located at `/doc/api` on servers.
+We currently use OpenAPI for RESTXQ and JAX-RS service endpoints.
+
+##### OpenAPI for RESTXQ
+
+For documenting RESTXQ APIs in our eXist-db systems we use the [OpenAPI4RESTXQ](https://gitlab.gwdg.de/subugoe/openapi4restxq) application.
+It simply has to be installed in eXist-db and configured according to the [instructions](https://gitlab.gwdg.de/subugoe/openapi4restxq#use).
+
+##### OpenAPI for CXF Java JAXRS Applications
+
+We have not yet finished the OpenAPI documentation of our Java services, but a few tests with the [OpenAPI Feature of Apache CXF](https://cxf.apache.org/docs/openapifeature.html) have already been implemented.
+
+The outcome of this OpenAPI documentation shall be the automated generation of API doc, to be written directly IN THE CODE as Java Annotation, using the @Operation annotation, see [example](https://github.com/apache/cxf/blob/master/distribution/src/main/release/samples/jax_rs/description_openapi_v3_spring/src/main/java/demo/jaxrs/openapi/server/Sample.java#L65) and then to be read and directly be used from within a HTML page.
+An automatic generation of a [OpenAPI JSON file](https://dev.textgridlab.org/1.0/tgsearch-public/info/openapi.json) should be possible to use it with a [Swagger UI HTML page frontend](https://dev.textgridlab.org/1.0/tgsearch-public/info/api-docs/?url=/1.0/tgsearch-public/info/openapi.json).
+We can deliver that page with every service or we could deploy a central Swagger UI service for all the documentation.
+For every service endpoint an OpenAPI doc could be provided, such as already done for [TG-search](https://dev.textgridlab.org/1.0/tgsearch-public).
+
+We also can combine this OpenAPI doc with our existing Sphinx API documentation (such as the [TG-search Sphinx API documentation](https://textgridlab.org/doc/services/submodules/tg-search/docs/index.html) as you can find [here](https://sphinxcontrib-openapi.readthedocs.io)).
 
 #### CESSDA's Software Maturity Levels in RDD (CA1.3)
 
@@ -115,6 +132,7 @@ This may encompass:
 - guided tour (Bootstrap Tour) as user documentation
 
 - for SADE portal usage (such as Fontane, BdN, Architrave)
+
 - for complex Digital Editions
 
 - screencasts