diff --git a/README.md b/README.md
index 361bc83e5ff1b55d41e2dab2c1a85643bb4f6188..86cbcb4eb4e28d8ed89fbe1379ee631a7ed182a0 100644
--- a/README.md
+++ b/README.md
@@ -1,259 +1,30 @@
# 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.
+## Documentation
-[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`.
+We provide separate documentations for lectures and students, administrators and developers:
-Once any machine has been started, all required ARSnova repositories are
-automatically cloned from GitHub, so that you can start coding immediately.
+* [For end-users](https://arsnova.thm.de/blog/en/arsnova-manual/)
+* For admins
+ * [Installation](src/site/markdown/installation.md)
+ * [Upgrading](src/site/markdown/upgrade.md)
+* [For developers](src/site/markdown/development.md)
-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..8aee947e0c48f297330c3330e11a448720fd7bff
--- /dev/null
+++ b/src/site/markdown/development.md
@@ -0,0 +1,65 @@
+# 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
+
+* [Caching](development/caching.md)
+* [Event System](development/event-system.md)
diff --git a/src/site/markdown/development/caching.md b/src/site/markdown/development/caching.md
new file mode 100644
index 0000000000000000000000000000000000000000..01d4a81ccd8fe2d9230e10c5cd4dfa10f2a89433
--- /dev/null
+++ b/src/site/markdown/development/caching.md
@@ -0,0 +1,59 @@
+# Caching
+
+Please read about Spring Framework's [Cache Abstraction](http://docs.spring.io/spring/docs/current/spring-framework-reference/html/cache.html) first.
+
+
+## What should get cached?
+
+The short answer: All data that is written once and read multiple times. In ARSnova, there is an inherent `1:n` relationship between teachers and students. This makes everything the teacher creates a candidate for caching. But there are more opportunities, like students' answers which are mostly written once and cannot be changed afterwards. Be aware though that in this case, once a new answer comes in, the cache has to be invalidated. With many students answering questions at the same time the effects of caching go away since the cache is invalidated all the time.
+
+While caching provides an opportunity to greatly speed up the execution of various requests, it does come with a price: You have to think of all cases were the cached data might become stale.
+
+
+## How to design your objects
+
+Caching should only be used with domain objects, where the `hashCode` and `equals` methods are provided. This makes it easy to update or delete cache entries. As you recall from the documentation, cache keys are based on a method's parameters. If you use base objects like `String` or `Integer`, you will have to manually provide a key through the Spring Expression Language (SpEL). As you can see from the following example, such keys can become quite complicated:
+
+```java
+@Cacheable(value = "notverycacheable", key = "#p0.concat('-').concat(#p1).concat('-').concat(#p2)")
+public ResultObject notVeryCacheable(String sessionId, String questionVariant, String subject) { ... }
+```
+
+Therefore, you should always work with domain objects like `Session`, `Question`, or even your own, newly defined objects:
+
+```java
+@Cacheable("verycacheable")
+public ResultObject veryCacheable(Session session) { ... }
+```
+
+Be aware though that you need to carefully choose the fields which should be part of the `equals`/`hashCode`: In case of CouchDB, for example, it is not a good idea to use a document's `rev` field. Every time a document is updated, it gets a new `rev` which will make it _unequal_ to all its previous versions, making cache updates using `@CachePut` impossible.
+
+[ARSnova's event system](https://github.com/thm-projects/arsnova-backend/wiki/Event-System) provides a useful way for fine-grained cache updates because the events contain all relevant domain objects. If you need to clear or update a cache based on one of ARSnova's events, you can use the `CacheBuster` class to add your annotations.
+
+
+## Issues
+
+Caching requires the use of Spring Proxies. This means that methods invoked using `this` ignore all caching annotations! They only work across object boundaries because Spring is only able to intercept calls if they are going through a Spring Proxy. This could only be solved using AOP, but we have no intention to support this in the near future.
+
+There is one exception: Since the `databaseDao` bean needs to call several methods on the same object, we implemented a workaround that allows access to the bean's proxy. When `getDatabaseDao()` is called within the bean, its proxy is returned that should be used instead of `this`.
+
+One last word of caution: Your code should not rely on the cache's existence, and you should keep expensive calls to a minimum: Do not hit the database multiple times even though you think further calls are served by the cache.
+
+
+## List of cache entries and associated keys
+
+Here is a list of all caches, their keys, and a short description.
+
+Cache name | Key | Description
+-----------|-----|------------
+`skillquestions`| `Session` entity | Contains all questions for the specified session irrespective of their variant.
+`lecturequestions` | `Session` entity | Contains all "lecture" variant questions for the specified session.
+`preparationquestions` | `Session` entity | Contains all "preparation" variant questions for the specified session.
+`flashcardquestions` | `Session` entity | Contains all "flashcard" variant questions for the specified session.
+`questions` | `Question` entity | Contains single question objects.
+`questions` | database id of question | Although it shares the name of the previously mentioned cache, it is in essence a different cache because the keys are different. This means that the same `Question` object might be associated with two different keys.
+`answers`| `Question` entity | Contains single answer objects.
+`learningprogress` | `Session` entity | Contains `CourseScore` objects to calculate the learning progress values for the specified session.
+`sessions` | keyword of session | Contains sessions identified by their keywords.
+`sessions` | database id of session | Although it shares the name of the previously mentioned cache, it is in essence a different cache because the keys are different. This means that the same `Session` object might be associated with two different keys.
+`statistics` | -- | Contains a single, global statistics object.
diff --git a/src/site/markdown/development/event-system.md b/src/site/markdown/development/event-system.md
new file mode 100644
index 0000000000000000000000000000000000000000..d9f4459a1066df3a0ba403feeafd9fe9dcc77dd0
--- /dev/null
+++ b/src/site/markdown/development/event-system.md
@@ -0,0 +1,28 @@
+# Event System
+
+ARSnova's event system allows objects to act upon changes to any of ARSnova's data structures. For example, if a new question is created, a `NewQuestionEvent` is sent out and any object that is interested can receive the question itself along with meta data such as the relevant `Session`. Among other use cases, the event is used to notify clients via Web Socket.
+
+Events offer a way to dynamically update data without the need to poll the database for changes. For instance, if clients are interested in the number of currently available questions, the respective Bean could initialize the number using the database, while keeping it up to date using events.
+
+
+## How to send events?
+
+A class is able to send events by implementing the `ApplicationEventPublisherAware` interface. It consists of one method to inject an `ApplicationEventPublisher`, which can then be used to send the events like so:
+```java
+publisher.publishEvent(theEvent);
+```
+where `theEvent` is an object of type `ApplicationEvent`. For ARSnova, the base class `NovaEvent` should be used instead. All of ARSnova's internal events are subtypes of `NovaEvent`.
+
+_Note_: Events are sent and received on the same thread, i.e., it is a synchronous operation.
+
+
+## How to receive events?
+
+Events are received by implementing the `ApplicationListener<NovaEvent>` interface. The associated method gets passed in a `NovaEvent`, which is the base class of all of ARSnova's events. However, this type itself is not very useful. The real type can be revealed using double dispatch, which is the basis of the Visitor pattern. Therefore, the event should be forwarded to a class that implements the `NovaEventVisitor` interface. This could be the same class that received the event.
+
+_Note_: If the class implementing the Visitor needs to have some of Spring's annotations on the event methods, like, for example, to cache some values using `@Cacheable`, the Listener and the Visitor must be different objects.
+
+
+## How to create custom events?
+
+Subclass either `NovaEvent` or `SessionEvent`. The former is for generic events that are not tied to a specific session, while the latter is for cases where the event only makes sense in the context of a session.
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.
diff --git a/src/site/resources/showcase.png b/src/site/resources/showcase.png
index 509dc91444d9ea1ddcadcf4a7460faa7d2d7e4a8..87c519fe51845f70502d1840c9014855c571c45d 100644
Binary files a/src/site/resources/showcase.png and b/src/site/resources/showcase.png differ