diff --git a/README.md b/README.md
index 361bc83e5ff1b55d41e2dab2c1a85643bb4f6188..aaca9232db4c3f89ff4ae66a77f66e56ae01c527 100644
--- a/README.md
+++ b/README.md
@@ -1,259 +1,19 @@
# ARSnova
-ARSnova is a modern approach to Audience Response Systems (ARS). It is released
-under the GPLv3 license, and is offered as a Software as a Service free of
-charge. Head over to [arsnova.eu](https://arsnova.eu/) to see it in action.
+ARSnova is a modern approach to Audience Response Systems (ARS).
+It is released under the GPLv3 license, and is offered as a Software as a Service free of charge.
+Head over to [arsnova.eu](https://arsnova.eu/) to see it in action.
-ARSnova consists of two projects: the mobile frontend and the backend. This
-repository contains the backend code. You will find the frontend at
-thm-projects/arsnova-mobile. However, you do not need to download both
-repositories in order to get started.
+ARSnova consists of two projects: the mobile frontend and the backend.
+This repository contains the backend code.
+You will find the frontend at thm-projects/arsnova-mobile.
+However, you do not need to download both repositories in order to get started.
[](https://travis-ci.org/thm-projects/arsnova-backend)
-## Getting Started
-
-The most convenient way to get started developing ARSnova is by using our
-[Vagrant](http://www.vagrantup.com/) environment, found at
-[thm-projects/arsnova-vagrant](https://github.com/thm-projects/arsnova-vagrant).
-Use your IDE on your host machine to make changes to ARSnova, while the build
-process is completely handled by the Vagrant box. You will not need to install
-any development tools.
-
-[arsnova-vagrant](https://github.com/thm-projects/arsnova-vagrant) sets up a
-virtual machine for both development and production use. The basic usage is
-`vagrant up`, which will start the development environment. If you wish to start
-production as well, use `vagrant up production`.
-
-Once any machine has been started, all required ARSnova repositories are
-automatically cloned from GitHub, so that you can start coding immediately.
-
-To connect to your development machine, type `vagrant ssh`. After that, you can
-start ARSnova inside the machine by running `./start.sh`. You can then access
-ARSnova from your host machine by opening http://localhost:8080.
-
-### QA Private Build
-
-[arsnova-vagrant](https://github.com/thm-projects/arsnova-vagrant) also sets up
-the build environment we use internally at THM, which consists of
-[Jenkins](http://jenkins-ci.org/) and [SonarQube](http://www.sonarqube.org/).
-The former provides a QA pipeline that builds, tests, analyzes, and finally
-deploys ARSnova to the production environment. SonarQube is used for the
-analyzation phase and provides a drill-down into many quality aspects, including
-[technical debt](https://en.wikipedia.org/wiki/Technical_debt).
-
-While the development environment is running, Jenkins and SonarQube are
-available at:
-
-- http://localhost:9000 (SonarQube)
-- http://localhost:9090 (Jenkins)
-
-### QA Public Build
-
-We also leverage the cloud provided by [Travis CI](https://travis-ci.org/) and
-[Sauce Labs](https://saucelabs.com/) to build and test ARSnova. Travis first
-builds and unit tests the software, then it instructs Sauce Labs to run smoke
-tests on different browsers and operating systems. This ensures that the basic
-features of ARSnova work across browsers and platforms. See
-[this example](https://saucelabs.com/tests/4beecf8c754f418da0b75259c039c077) to
-get an idea.
-
-Our official build status provided by Travis CI:
-
-- [](https://travis-ci.org/thm-projects/arsnova-backend) for ARSnova Backend
-- [](https://travis-ci.org/thm-projects/arsnova-mobile) for ARSnova Mobile
-
-## Development
-
-This is ARSnova's main repository. Almost all dependencies are managed for you
-by Maven.
-
-### Download
-
-If you have no intention in contributing, you might want to consider downloading
-one of our pre-built WAR archives. You will find them on our
-[GitHub releases page](https://github.com/thm-projects/arsnova-backend/releases).
-
-### Building
-
-ARSnova consists of two main projects: ARSnova Backend (this repository) and
-ARSnova Mobile.
-
-Because all dependencies are handled by Maven, a complete build is done with:
-
- mvn install
-
-*Note:* Java 1.8 JDK is required and must be installed prior to building
-ARSnova.
-
-### Requirements
-
-You need three things to get started developing ARSnova:
-
-1. the configuration file,
-2. a CouchDB database including several view documents,
-3. and a development server.
-
-We will cover all three in the following sections.
-
-#### Configuration
-
-You will need to do some configuration work upfront: add a new directory
-"arsnova" in `/etc`, and create a copy of
-[arsnova.properties.example](src/main/resources/arsnova.properties.example) named
-`arsnova.properties` in this directory. Then change the settings to match your
-environment, e.g. you might want to change the URLs.
-
-Also, don't forget to change all properties starting with `couchdb`, if you do
-not want to use our defaults. The properties are used in the next section.
-
-*A note to Windows users*: our settings are based on Linux and Mac environments.
-We do not officially support Windows, so you have to do some extra steps. The
-property file's path is hard coded in
-[spring-main.xml](src/main/webapp/WEB-INF/spring/spring-main.xml) and in the
-"Setup Tool" (see next section). You want to change the paths to make them match
-your environment.
-
-#### Database
-
-We provide a Python script that will set up all database essentials. This "Setup
-Tool" is located at
-[thm-projects/arsnova-setuptool](https://github.com/thm-projects/arsnova-setuptool).
-Make sure you have configured your database credentials inside the ARSnova
-configuration file (see previous section): you will need to have the entries
-`couchdb.username` and `couchdb.password`.
-
-To set up the database, run:
-
- python tool.py
-
-This will create the database along with all required view documents. Note that
-this script requires Python 2 and will not run with Python 3.
-
-#### Developer Mode
-
-The easiest way to deploy ARSnova is via Jetty:
-
- mvn jetty:run -Dmobile.path=
-
-This will work out of the box. ARSnova will be located at
-<http://localhost:8080/>.
-
-If you're wondering what that `-Dmobile.path=` thing is doing, this is a special
-override property for Jetty. By default, this property points to a local version
-of ARSnova mobile located at `../arsnova-mobile` — relative to the
-location of this project. If you happen to have downloaded ARSnova mobile to
-this location, you may skip the override, and just use:
-
- mvn jetty:run
-
-### Further Documentation
-
-Please see our [Wiki][Wiki] for an in-depth look at development topics such as [Caching][Caching] and [ARSnova's event system][Event-System].
-
-[Wiki]: https://github.com/thm-projects/arsnova-backend/wiki
-[Caching]: https://github.com/thm-projects/arsnova-backend/wiki/Caching
-[Event-System]: https://github.com/thm-projects/arsnova-backend/wiki/Event-System
-
-## Production Use
-
-If you intend to use ARSnova in productive environments, you will have to do
-some additional configuration work.
-
-### Server
-
-In order to build up a full featured server installation containing ARSnova and
-CouchDB you have to install at least the following services:
-
- * Apache Tomcat 7 (or newer)
- * Apache Webserver 2.2 or newer with builtin modules `mod_proxy`,
-`mod_proxy_ajp` and `mod_proxy_http`
- * Apache CouchDB
-
-Make sure all services are installed. Next step is to configure the Apache
-Webserver. Find the configuration file or create a new one for use with a
-virtual host. This depends on your needs. At least you should have a
-configuration containing these settings:
-
- <Location />
- ProxyPass ajp://127.0.0.1:8009/
- ProxyPassReverse ajp://127.0.0.1:8009/
- </Location>
-
-All requests will be sent to your Apache Tomcat servlet container, using AJP
-running on port 8009.
-
-To enable the required Apache Webserver modules simply type:
-
- # a2enmod proxy
- # a2enmod proxy_ajp
- # a2enmod proxy_http
-
-The configuration is ready for development usage. Finally, you should (re)start
-all services. ARSnova is now listening on HTTP port 80.
-
-### Session Persistence
-
-Look for your Tomcat configuration directory and change the file "context.xml"
-to match this example:
-
- <Context>
- <Manager pathname="/path/to/tomcat/sessions/arsnova.ser"/>
- </Context>
-
-This will enable session persistence across restarts as described
-[here](http://tomcat.apache.org/tomcat-7.0-doc/config/manager.html#Special_Features).
-
-### HTTPS
-
-To protect requests and responses you should use HTTPS and configure your Apache
-Webserver installation to redirect all traffic according to this
- [example](http://wiki.apache.org/httpd/RedirectSSL).
-
-Finally you should (re)start all services. ARSnova is now listening on HTTP port
-80 and 443.
-
-### Securing Your Web Socket Connection
-
-To provide SSL websocket encryption, you have to provide the servers SSL key and
-certificate in a Java keystore. The following steps will guide you through this
-process.
-
-Use your webserver certificate, private key and certificate chain to create a
-PKCS12 keystore:
-
- openssl pkcs12 -export -in <servercert>.crt \
- -inkey <serverkey>.key \
- -out keystore.p12 -name 1 \
- -certfile <your_cert_chain_file>
-
-You will be asked for a password for your PKCS12 keystore. This password must be
-used for importing this keystore into your java keystore. The import can be done
-using this command:
-
- keytool -importkeystore \
- -deststorepass <your_java_keystore_password> \
- -destkeypass <your_java_keystore_password> \
- -destkeystore arsnova.jks \
- -srckeystore keystore.p12 \
- -srcstoretype PKCS12 \
- -srcstorepass <your_pkcs12_keystore_password> \
- -alias 1
-
-Be sure to provide the correct certificate and key file names and to use the
-correct passwords for your keystore.
-
-The last step is to find your ARSnova configuration file (see step
- "Configuration" above), setup the location of your Java keystore and its
- password.
-
- security.ssl=true
- security.keystore=<your keystore location>
- security.storepass=<your keystore password>
## Credits
-ARSnova is powered by Technische Hochschule Mittelhessen - University of Applied
-Sciences.
+ARSnova is powered by Technische Hochschule Mittelhessen - University of Applied Sciences.
diff --git a/src/site/markdown/development.md b/src/site/markdown/development.md
new file mode 100644
index 0000000000000000000000000000000000000000..431f1cb4a428059dadd9975600cd601e70b093bd
--- /dev/null
+++ b/src/site/markdown/development.md
@@ -0,0 +1,68 @@
+# Development
+
+## Preparations
+
+Before you can get started developing ARSnova you need to make sure the following software is installed to build ARSnova Backend:
+
+* Java 8 JDK
+* Apache Maven 3.x
+
+And additionally if you want to run ARSnova locally:
+
+* Apache CouchDB 1.x
+* Python 2.7
+* [ARSnova Setup Tool](https://github.com/thm-projects/arsnova-setuptool)
+
+Next, you need to setup an ARSnova configuration file.
+Create a copy of [arsnova.properties.example](src/main/resources/arsnova.properties.example) at `/etc/arsnova/arsnova.properties`.
+Afterwards, initialize the database by running the `tool.py` python script from the Setup Tool.
+
+
+## Building
+
+ARSnova Backend uses Maven for builds and dependency management.
+You do not need to download any framework or library dependencies - Maven handles this for you.
+
+You can create a web archive (`.war` file) by running a single command:
+
+ $ mvn package
+
+
+## Running
+
+ARSnova builds are setup up to automatically download the Java Servlet container Jetty for development.
+Run the following command to download the dependencies and startup the backend with Jetty:
+
+ $ mvn jetty:run
+
+After a few seconds the ARSnova API will be accessible at <http://localhost:8080/>.
+
+
+## Continuous Integration
+
+Our code repositories are located on a [GitLab server](https://git.thm.de/arsnova) for internal development.
+They are automatically mirrored to [GitHub](https://github.com/thm-projects) on code changes.
+
+Apart from mirroring GitLab CI triggers various jobs to:
+
+* check the code quality (static code analysis with SonarQube)
+* build a web archive
+* execute unit tests
+* deploy to our staging/production servers
+
+In addition to GitLab CI for our internal repositories we use Travis CI which is able to run against merge requests on GitHub.
+Travis CI only runs unit tests for the backend.
+
+The current build status for the master branch:
+
+* [](https://travis-ci.org/thm-projects/arsnova-backend) for ARSnova Backend
+* [](https://travis-ci.org/thm-projects/arsnova-mobile) for ARSnova Mobile
+
+
+## Further Documentation
+
+Please see our [Wiki][Wiki] for an in-depth look at development topics such as [Caching][Caching] and [ARSnova's event system][Event-System].
+
+[Wiki]: https://github.com/thm-projects/arsnova-backend/wiki
+[Caching]: https://github.com/thm-projects/arsnova-backend/wiki/Caching
+[Event-System]: https://github.com/thm-projects/arsnova-backend/wiki/Event-System
diff --git a/src/site/markdown/installation.md b/src/site/markdown/installation.md
new file mode 100644
index 0000000000000000000000000000000000000000..42d67f753964329fe68528d0a6c5551a687796d9
--- /dev/null
+++ b/src/site/markdown/installation.md
@@ -0,0 +1,194 @@
+# Installation
+
+This document describes the necessary steps to install ARSnova Backend.
+In case you are viewing this file from the repository please make sure you are on the corresponding `x.y-stable` branch for the target version.
+
+
+## Requirements
+
+### Operating System
+
+While ARSnova should be able to run on any Linux distribution, we officially only support Debian and Ubuntu systems on which we test the installation procedure regularly.
+We recommend to use the latest (LTS) versions of the distributions.
+
+For Debian 8 you need to enable the backports repository to install Java 8:
+
+ # grep '^deb .*jessie-backports' -q /etc/apt/sources.list || echo "deb http://ftp.fh-giessen.de/debian/ jessie-backports main" >> /etc/apt/sources.list
+
+
+### Hardware
+
+While the hardware requirements highly depend on the number of simultaneous users we suggest to provide at least 2 CPU cores and 4 GiB memory to the system ARSnova will be running.
+This configuration would support up to 500 users.
+
+
+## Configuration
+
+You will need to do some configuration work upfront:
+Create a copy of [arsnova.properties.example](src/main/resources/arsnova.properties.example) at `/etc/arsnova/arsnova.properties`.
+Then change the settings to match your environment.
+
+You need to change at least the following configuration properties:
+
+* `root-url`: The public URL (without backend path) at which ARSnova will be accessible to clients.
+* `couchdb.user` and `couchdb.password`: These credentials will be used later when the database is setup.
+
+*A note to Windows users*: our settings are based on Linux and Mac environments.
+We do not officially support Windows, so you have to do some extra steps.
+The property file's path is hard coded in
+[spring-main.xml](src/main/webapp/WEB-INF/spring/spring-main.xml) and in the "Setup Tool" (see "Database Setup").
+You want to change the paths to make them match your environment.
+
+
+## Server Software
+
+In order to build up a full featured server installation you have to install at least the following software:
+
+* Oracle Java SE 8 or OpenJDK 8 (or newer)
+* Apache Tomcat 8 (or newer)
+* Apache CouchDB 1.x (1.2 or newer recommended)
+* One of the following webservers acting as a reverse proxy:
+ * Nginx 1.3 (or newer), 1.9.5 (or newer) recommended for HTTP/2 support
+ * Apache HTTP Server 2.4.5 (or newer) with builtin modules `mod_proxy`, `mod_proxy_http`, `mod_proxy_wstunnel` and `mod_rewrite`
+
+Additionally, you need Python 2.7 (3.0 or newer will not work) to run the "Setup Tool".
+We further recommend installing the "Apache Portable Runtime Library" (libapr1) for improved performance.
+
+Most of this software can easily be installed on Linux systems using the distribution's package manager:
+* Debian: `# apt-get install -t jessie-backports nginx openjdk-8-jre && apt-get install libapr1 tomcat8`
+* Ubuntu: `# sudo apt-get install couchdb libapr1 nginx openjdk-8-jre tomcat8`
+
+While running ARSnova without a reverse proxy is possible we do not recommend to do so.
+A reverse proxy significantly simplifies the setup of HTTPS and allows running Websocket connections over the default HTTP(S) port.
+
+
+### CouchDB
+
+Install CouchDB:
+Depending on your operation system or distribution you might need to compile CouchDB from source code.
+In this case follow the CouchDB's
+[installation guide](http://docs.couchdb.org/en/1.6.1/install/index.html).
+
+Before you proceed, make sure that CouchDB is up and running:
+
+ $ curl locahost:5984
+
+CouchDB should respond with version information.
+
+Use the values you set for `couchdb.username` and `couchdb.password` before to set the database credentials with the following command:
+
+ $ curl -X PUT -d '"<password>"' localhost:5984/_config/admins/<username>
+
+We provide a Python script that will set up all database essentials.
+This "Setup Tool" is located at [thm-projects/arsnova-setuptool](https://github.com/thm-projects/arsnova-setuptool).
+
+To set up the database, run:
+
+ $ python tool.py
+
+This will create the database along with all required view documents.
+
+CouchDB is now usable for ARSnova but there a still a few things that should be setup for security and performance reasons.
+We recommend that you make the following adjustments to the CouchDB configuration `local.ini` which is usually located in either `/etc/couchdb` or `/usr/local/etc/couchdb` depending on the installation method.
+First make sure the CouchDB daemon only listens to local connections by setting `bind_address` in the `httpd` section to `127.0.0.1`.
+Next, append the following section which instructs CouchDB to cleanup at night.
+
+ [compactions]
+ _default = [{db_fragmentation, "70%"}, {view_fragmentation, "60%"}, {from, "01:00"}, {to, "05:00"}]
+
+To make compaction effective you need to reduce the number of revisions saved per document.
+As long as CouchDB is not clustered you can significantly reduce storage usage by setting a limit of 5.
+
+ $ curl -X PUT -d "5" http://localhost:5984/arsnova/_revs_limit
+
+
+### Java & Tomcat
+
+To make sure ARSnova has access to the memory provided by the system you need adjust the Java settings for Tomcat.
+Increase the initial and maximum heap sizes by adding `-Xms3072m -Xmx3072m` to the Java start up parameters used by Tomcat.
+On Debian-based systems this is done by appending
+
+ JAVA_OPTS="$JAVA_OPTS -Xms3072m -Xmx3072m"
+
+to `/etc/default/tomcat8`.
+For most other distributions append this to `setenv.sh` in Tomcat's `bin` directory.
+Adjust the values based on the memory available to the system but make sure reserve 1 GiB for the operating system, web server and database system.
+
+By default, Tomcat listens on a public interface.
+If you follow our recommendation and use a reverse proxy you should change the configuration so Tomcat only accepts requests from localhost.
+Open `/etc/tomcat8/server.xml` and look for `<Connector port="8080" ...>` and change it to:
+
+ <Connector port="8080" address="127.0.0.1" ...>
+
+
+### Web Application
+
+The ARSnova Backend application is contained in a single file: the web archive (`.war file`).
+You can download the latest version from our
+[GitHub releases page](https://github.com/thm-projects/arsnova-backend/releases).
+
+To deploy the backend on the Tomcat Servlet container, copy the file to Tomcat's webapp directory and name it `api.war`.
+
+Check that the application is deployed correctly by sending a HTTP request:
+
+ $ curl -H "Accept: application/json" localhost:8080/api/
+
+The backend should respond with version information.
+
+
+### Nginx
+
+Create a new site configuration file `arsnova` in `/etc/nginx/sites-available` based on the default site configuration.
+Add the following lines to the `server` section of the file:
+
+ location = / { return 301 <path to ARSnova frontend>; }
+ location = /arsnova-config { proxy_pass http://localhost:8080/api/configuration/; }
+ location /api {
+ proxy_pass http://localhost:8080;
+ proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+ proxy_set_header X-Forwarded-Host $host;
+ proxy_set_header X-Forwarded-Port $server_port;
+ proxy_set_header X-Forwarded-Proto $scheme;
+ }
+ location /socket.io/ {
+ proxy_pass http://localhost:8090;
+ proxy_http_version 1.1;
+ proxy_set_header Upgrade $http_upgrade;
+ proxy_set_header Connection "upgrade";
+ proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+ proxy_set_header Host $host;
+ }
+
+Create a symbolic link in `/etc/nginx/sites-enabled` to the `arsnova` site configuration file.
+Delete a link to the default site configuration if it exists.
+
+
+### Apache HTTP Server
+
+Create a new site configuration file `arsnova` in `/etc/apache2/sites-available` based on the default site configuration.
+Add the following lines to the `VirtualHost` section of the file:
+
+ RewriteEngine On
+ RewriteRule ^/$ <path to ARSnova frontend> [R=301,L]
+ RewriteRule ^/arsnova-config$ /api/configuration/ [PT,L]
+ <Location /api/>
+ ProxyPass http://localhost:8080/api/
+ ProxyPassReverse http://localhost:8080/api/
+ ProxyPreserveHost On
+ </Location>
+ <Location /socket.io/>
+ ProxyPass ws://localhost:8090/socket.io/
+ ProxyPassReverse ws://localhost:8090/socket.io/
+ </Location>
+
+To enable the required Apache HTTP Server modules simply type:
+
+ # a2enmod proxy
+ # a2enmod proxy_http
+ # a2enmod proxy_wstunnel
+ # a2enmod rewrite
+
+At last, disable the default site configuration and enable the newly created one:
+
+ # a2dissite default
+ # a2ensite arsnova
diff --git a/src/site/markdown/upgrade.md b/src/site/markdown/upgrade.md
new file mode 100644
index 0000000000000000000000000000000000000000..c6aef44dc3885037ebbec46e783c94bf6065b2d1
--- /dev/null
+++ b/src/site/markdown/upgrade.md
@@ -0,0 +1,58 @@
+# Upgrading ARSnova
+
+This document describes the necessary steps to upgrade ARSnova Backend.
+In case you are viewing this file from the Repository please make sure you are on the corresponding `x.y-stable` branch for the target version.
+
+
+## Database Backup
+
+To be able to revert to the previous installed version you should backup your CouchDB database.
+All data is stored in `arsnova.couch` which is usually located either in `/var/lib/couchdb` or `/usr/local/var/lib/couchdb`.
+Optionally, you can backup the whole directory which will require significantly more space.
+Otherwise, this additional data can be regenerated by CouchDB.
+
+
+## Database Migration
+
+Most ARSnova minor releases require modifications to the database.
+We provide the [ARSnova Setup Tool](https://github.com/thm-projects/arsnova-setuptool/releases) to handle these changes.
+Please make sure you download the corresponding release for the target version.
+Usually, there are no database modifications for patch releases so you can use Setup Tool version 2.5.0 for Backend 2.5.1.
+
+Unpack the downloaded archive and run the following commands in the extracted directory:
+
+ $ python tool.py
+ $ python migration.py
+
+
+## Configuration Changes
+
+New ARSnova releases might introduce new configuration options or modify existing ones.
+We suggest you review the corresponding [arsnova.properties.example](src/main/resources/arsnova.properties.example) for your target version and adjust `/etc/arsnova.properties` accordingly.
+
+
+## Backend Upgrade
+
+Copy the web archive (`.war` file) for the new backend version into Tomcat's `webapps` directory.
+It is usually located at either `/var/lib/tomcatX/webapps` or `/opt/tomcatX/webapps`.
+Make sure you use the same name you chose when installing ARSnova (we suggest `api.war`) and override the existing file.
+By default, Tomcat automatically deploys the updated application but nevertheless we recommend restarting Tomcat to make sure no unnecessary data is kept in memory.
+
+
+## Frontend Upgrade
+
+While we try to keep compatibility breaking changes to the API to a minimum we suggest to always use a version of Mobile corresponding to the backend's version.
+
+
+## Final Steps
+
+The new version of the backend should now be up and running.
+As a quick test you can run the following `curl` commands:
+
+ $ curl -H "Accept: application/json" http://localhost:8080/api/
+
+The backend should return the new version.
+
+ $ curl http://localhost:8080/api/statistics
+
+The backend should respond with data statistics which implies that the connection to the database is working.