add INSTALLATION.md

Author: Alexander Ben Nasrallah

README.md

@@ -6,15 +6,9 @@ for a verinice database. The verinice REST service is a [Spring
 Boot](http://projects.spring.io/spring-boot/) application build with
 [Maven](https://maven.apache.org/).
 
-## Run
-
-call e.g.
-
-	mvn spring-boot:run -Dlogging.level.org.springframework=TRACE -Drun.arguments="--server.port=8081"
-
 ## Modules
 
-The project consist of several modules to seperate concerns. This section
+The project consist of several modules to separate concerns. This section
 describes the modules of the project.
 
 ### verinice-interface
@@ -41,7 +35,9 @@ To build the application run
 
 	mvn install
 
-If want to start SpringBoot you can then run
+you can then install the *./verinice-rest/target/verinice-rest-xxx.jar*.
+
+If want to start SpringBoot in development you can then run
 
 	mvn -pl verinice-rest spring-boot:run
 
@@ -51,21 +47,22 @@ assuming you have proper database setup up, see [application.properties](verinic
 Integration tests are written in python using [Requests][]
 and standard python [unittest][py-unittest].
 
-Since no maven plugin has been found wich could start spring-boot and run the
+Since no maven plugin has been found which could start spring-boot and run the
 test against a custom database a shell script has been written to batch several
 steps. To run the integration tests execute
 
 	./integration-test
 
 The script uses the following variables
 
-- `VERINICEDB` The database name to connect to at localhost.
-- `VERINICEUSER` The user which spring should use for the database. Has to exists.
-- `VERINICEPASSWORD` The password for the database `$VERINICEUSER`.
-- `VERINICEDUMP` The location to a database dumb which shall be used to recreate the `$VERINICEDB`.
-- `SPRINGDELAY`  Time to sleep before running the tests to give spring time to boot.
+- `VERINICEDBSERVER` the database server URL
+- `VERINICEDB` the database name to connect to at $VERINICEDBSERVER
+- `VERINICEUSER` the user which spring should use for the database (has to exists)
+- `VERINICEPASSWORD` the password for the database `$VERINICEUSER`
+- `VERINICEDUMP` the location to a database dumb which shall be used to recreate the `$VERINICEDB`
+- `SPRINGDELAY`  time to sleep before running the tests to give spring time to boot
 
-i.e. to run the test against a custom database with a special user run
+i. e. to run the test against a custom database with a special user run
 
 	VERINICEDB=databasename VERINICEUSER=user VERINICEPASSWORD=password ./integration-test
 
@@ -135,25 +132,7 @@ To release a new version (here 0.1 is assumed) of the project, you should
 		git merge --no-ff release/0.1
 		git push origin develop
 
-## Logging
-Logging can be change and start time by setting the environment variable family
-`logging.level.*`
-
-### Received Requests
-
-	-Dlogging.level.org.springframework.web.servlet=DEBUG
-
-### verinice specific logging
-
-	-Dlogging.level.org.verinice=TRACE
-
-## Misc
-To run the created jar with customizations run, e. g.
-
-	java -jar verinice-rest-0.1.0.jar --spring.datasource.url=jdbc:postgresql://127.0.0.1:5432/verinicedb --server.port=8888
-
 ## Troubleshooting
-
 ### Could not resolve dependencies
 If you get an error like this
 

USERGUIDE.md

@@ -1,12 +1,71 @@
-# verinice.REST Userguide
-
-## REST
-Die verinice.REST-Schnittstelle kann Daten in der verinice-Datenbank lesen
-und schreiben. Dabei wird das Rechtesystem von verinice berücksichtigt.
-Es wird empfohlen einen technischen Nutzer für die REST-Aufrufe in
-verinice anzulegen.
-
-## verinice
-Damit Daten von externen Tools über die REST-Schnittstelle bearbeiten
-werden können, ist es wichtig darauf zu achten, dass dem technischen
-Nutzer Lese- und Schreibrechte auf den entsprechenden Scopes geben werden.
+# verinice.REST-Userguide
+This document describes how to customize and run the verinice.REST.
+See [README.md](README.md) for how to build the verinice.REST.  You can
+also retrieve the complete JAR from the [release page](https://github.com/SerNet/verinice.REST/releases)
+
+## Run the verinice.REST
+verinice.REST comes as a self-contained jar, i. e. no further
+dependencies are required except a JRE-8 or later and a running
+[verinice](https://verinice.com/) installation.
+
+You can run verinice.REST by calling
+
+	java -jar verinice-rest-XXX.jar
+
+Replace XXX with the proper version string.
+
+## Configuration
+The default configuration for verinice.REST is stored in
+[application.properties](verinice-rest/src/main/resources/application.properties)
+
+Every property can be overwritten by passing it as a option to the Java call,
+e. g.
+
+	java -jar verinice-rest-XXX.jar \
+		--server.port=8888 \
+		--spring.datasource.url=jdbc:postgresql://verinicedb.local.example:5432/customdb \
+		--spring.datasource.username=verinice-rest \
+		--spring.datasource.password=********
+		--veriniceserver.url=https://verinice.local.example:84577 \
+
+tells verinice.REST to listen to port *8888*. It then open a database
+connection to *verinicedb.local.example:5432/customdb* authenticating as
+*verinice-rest* using the given password.
+
+*veriniceserver.url=https://verinice.local.example:84577* is the URL to your
+verinice intallation and is only needed if you intend to create links.
+verinice.REST uses this address to retrieve information (SNCA.xml) from
+verinice to validate data. Creating links requires a verinice 1.20 or later.
+
+**NOTE** It is highly recommended to create a technical user, e. g.
+*verinice-rest*, which has to be configured, s. a. This user has to be given
+reas and write access to scopes within verinice, in order to change them via
+verinice.REST.
+
+## Logging
+Logging can be change and start time by setting the environment variable family
+`logging.level.*`. For example you can set the logging level for every
+component to `DEBUG` by running verinice.REST with the following
+argument:
+
+	java -jar verinice-rest-XXX.jar -Dlogging.level=DEBUG
+
+Possible levels include
+
+- `DEBUG`
+- `INFO`
+- `WARN`
+- `ERROR`
+- `FATAL`
+- `TRACE`
+
+The next sections give some examples of logging components.
+
+### Received Requests
+
+	-Dlogging.level.org.springframework.web.servlet=DEBUG
+
+### verinice specific logging
+
+	-Dlogging.level.org.verinice=TRACE
+