Skip to content
Snippets Groups Projects
Commit d59d07aa authored by Daniel Gerhardt's avatar Daniel Gerhardt
Browse files

Split up and rewrite documentation 

The README file has been split up into separate files for installation
and development. A new documentation for the upgrade process has been
added.

The following changes have been made regarding content:
* Removed outdated Vagrant section
* Replaced unnecessary session persistance section
* Use simple HTTP proxy module instead of AJP for Apache httpd
* Nginx as alternative for Apache httpd
* Use Websocket proxy which makes HTTPS configuration on the Java side
  obsolete
* Additional configuration steps for server software
* Added requirements section
* Added upgrading instructions
parent 2d3456b7
Branches
Tags
1 merge request!44Split up and rewrite documentation
Hide whitespace changes
Inline Side-by-side
README.md
+ 8
− 248
View file @ d59d07aa
# ARSnova # ARSnova
ARSnova is a modern approach to Audience Response Systems (ARS). It is released ARSnova is a modern approach to Audience Response Systems (ARS).
under the GPLv3 license, and is offered as a Software as a Service free of It is released under the GPLv3 license, and is offered as a Software as a Service free of charge.
charge. Head over to [arsnova.eu](https://arsnova.eu/) to see it in action. Head over to [arsnova.eu](https://arsnova.eu/) to see it in action.
![ARSnova](src/site/resources/showcase.png) ![ARSnova](src/site/resources/showcase.png)
ARSnova consists of two projects: the mobile frontend and the backend. This ARSnova consists of two projects: the mobile frontend and the backend.
repository contains the backend code. You will find the frontend at This repository contains the backend code.
thm-projects/arsnova-mobile. However, you do not need to download both You will find the frontend at thm-projects/arsnova-mobile.
repositories in order to get started. However, you do not need to download both repositories in order to get started.
[![Build Status](https://travis-ci.org/thm-projects/arsnova-backend.svg?branch=master)](https://travis-ci.org/thm-projects/arsnova-backend) [![Build Status](https://travis-ci.org/thm-projects/arsnova-backend.svg?branch=master)](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:
- [![Build Status](https://travis-ci.org/thm-projects/arsnova-backend.svg?branch=master)](https://travis-ci.org/thm-projects/arsnova-backend) for ARSnova Backend
- [![Build Status](https://travis-ci.org/thm-projects/arsnova-mobile.svg?branch=master)](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` &mdash; 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 ## Credits
ARSnova is powered by Technische Hochschule Mittelhessen - University of Applied ARSnova is powered by Technische Hochschule Mittelhessen - University of Applied Sciences.
Sciences.
src/site/markdown/development.md 0 → 100644
+ 68
− 0
View file @ d59d07aa
# 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:
* [![Build Status](https://travis-ci.org/thm-projects/arsnova-backend.svg?branch=master)](https://travis-ci.org/thm-projects/arsnova-backend) for ARSnova Backend
* [![Build Status](https://travis-ci.org/thm-projects/arsnova-mobile.svg?branch=master)](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
src/site/markdown/installation.md 0 → 100644
+ 194
− 0
View file @ d59d07aa
# 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
src/site/markdown/upgrade.md 0 → 100644
+ 58
− 0
View file @ d59d07aa
# 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.
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment