Skip to content
Snippets Groups Projects

Compare revisions

Changes are shown as if the source revision was being merged into the target revision. Learn more about comparing revisions.

Source

Select target project
No results found

Target

Select target project
  • arsnova/arsnova-backend
  • pcvl72/arsnova-backend
  • tksl38/arsnova-backend
3 results
Show changes
Hide whitespace changes
Inline Side-by-side
Showing
with 590 additions and 140 deletions
src/main/webapp/error/401.html deleted 100644 → 0
View file @ 47010d58
<!DOCTYPE html>
<html>
<head>
<meta charset="UTF-8">
<title>Not Found</title>
<link href="error/error.css" rel="stylesheet" type="text/css" />
</head>
<body>
<article>
<h1>401 - UNAUTORIZED</h1>
<p>
Sorry, you must be authorized to request this resource
</p>
</article>
</body>
</html>
\ No newline at end of file
src/main/webapp/error/403.html deleted 100644 → 0
View file @ 47010d58
<!DOCTYPE html>
<html>
<head>
<meta charset="UTF-8">
<title>Not Found</title>
<link href="error/error.css" rel="stylesheet" type="text/css" />
</head>
<body>
<article>
<h1>403 - FORBIDDEN</h1>
<p>
Sorry, you are not allowed to request this resource
</p>
</article>
</body>
</html>
\ No newline at end of file
src/main/webapp/error/404.html deleted 100644 → 0
View file @ 47010d58
<!DOCTYPE html>
<html>
<head>
<meta charset="UTF-8">
<title>Not Found</title>
<link href="error/error.css" rel="stylesheet" type="text/css" />
</head>
<body>
<article>
<h1>404 - NOT FOUND</h1>
<p>
Sorry, the resource you are requesting could not be found
</p>
</article>
</body>
</html>
\ No newline at end of file
src/main/webapp/error/500.html deleted 100644 → 0
View file @ 47010d58
<!DOCTYPE html>
<html>
<head>
<meta charset="UTF-8">
<title>Not Found</title>
<link href="error/error.css" rel="stylesheet" type="text/css" />
</head>
<body>
<article>
<h1>500 - INTERNAL SERVER ERROR</h1>
<p>
Sorry, this should not happen.
</p>
</article>
</body>
</html>
\ No newline at end of file
src/main/webapp/error/503.html deleted 100644 → 0
View file @ 47010d58
<!DOCTYPE html>
<html>
<head>
<meta charset="UTF-8">
<title>Not Found</title>
<link href="error/error.css" rel="stylesheet" type="text/css" />
</head>
<body>
<article>
<h1>503 - SERVICE UNAVAILABLE</h1>
<p>
Sorry, this should not happen.
</p>
</article>
</body>
</html>
\ No newline at end of file
src/main/webapp/error/error.css deleted 100644 → 0
View file @ 47010d58
@CHARSET "UTF-8";
body {
background: #eee;
}
article {
background: white url(thm-logo.png) no-repeat 16px 98%;
margin: 16px;
padding: 48px 16px;
border-radius: 4px;
box-shadow: 0 1px 2px #ccc;
text-align: center;
font-weight: bold;
}
article > h1 {
background: url(logo_128.png) no-repeat 50% top;
padding: 140px 48px 48px 48px;
color: #800000;
text-shadow: 0 1px 0 white, 0 2px 1px #ccc;
}
src/main/webapp/error/logo_128.png deleted 100644 → 0
View file @ 47010d58
src/main/webapp/error/logo_128.png

7.94 KiB

src/main/webapp/error/thm-logo.png deleted 100644 → 0
View file @ 47010d58
src/main/webapp/error/thm-logo.png

3.23 KiB

src/site/apt/index.apt deleted 100644 → 0
View file @ 47010d58
-----
ARSnova Landing Page
-----
ARSnova Developers
-----
-----
ARSnova
Das Projekt ARSnova will neue Wege gehen, um auch in großen Veranstaltungen Feedback und Interaktion zwischen Auditorium und Lehrperson zu ermöglichen: ARS = Audience Response System.
* {{{http://en.wikipedia.org/wiki/Audience_response}ARS bei Wikipedia}}
* {{{https://scm.thm.de/redmine/documents/16}Präsentation über ARSnova}}
* {{{https://arsnova.eu/overlay/}Desktop-Widget}}
* {{{http://prezi.com/bkfz1utyaiiw/arsnova/}ARSnova auf Prezi}}
ARSnova ist eine coole, kostenlose und ausbaufähige Open-Source-App, die als HTML5-App auf jedem Smartphone, Tablet-PC oder Laptop läuft.
src/site/markdown/development.md 0 → 100644
View file @ f55cc773
# 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](../../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/>.
You can adjust the amount of debug logging by changing the log levels in [log4j-dev.properties](../../main/resources/log4j-dev.properties).
Additionally, you can enable exception messages in API responses by setting the boolean property `api.expose-error-messages` in `arsnova.properties`.
## 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
* [Roadmap](development/roadmap.md)
* [Caching](development/caching.md)
* [Event System](development/event-system.md)
src/site/markdown/development/caching.md 0 → 100644
View file @ f55cc773
# 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 roomId, String questionVariant, String subject) { ... }
```
Therefore, you should always work with domain objects like `Room`, `Content`, or even your own, newly defined objects:
```java
@Cacheable("verycacheable")
public ResultObject veryCacheable(Room room) { ... }
```
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](event-system.md) 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
-----------|-----|------------
`contentlists`| database id of room | Contains all contents for the specified room irrespective of their variant.
`lecturecontentlists` | database id of room | Contains all "lecture" variant contents for the specified room.
`preparationcontentlists` | database id of room | Contains all "preparation" variant contents for the specified room.
`flashcardcontentlists` | database id of room | Contains all "flashcard" variant contents for the specified room.
`contents` | `Content` entity | Contains single content objects.
`contents` | database id of content | 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 `Content` object might be associated with two different keys.
`answerlists`| database id of content | Contains single answer objects.
`score` | `Room` entity | Contains `CourseScore` objects to calculate the score values for the specified room.
`rooms` | keyword of room | Contains rooms identified by their keywords.
`rooms` | database id of room | 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 `Room` object might be associated with two different keys.
`statistics` | -- | Contains a single, global statistics object.
src/site/markdown/development/event-system.md 0 → 100644
View file @ f55cc773
# 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 `ArsnovaEvent` should be used instead. All of ARSnova's internal events are subtypes of `ArsnovaEvent`.
_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<ArsnovaEvent>` interface. The associated method gets passed in a `ArsnovaEvent`, 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 `ArsnovaEvent` 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 `ArsnovaEvent` or `RoomEvent`. The former is for generic events that are not tied to a specific room, while the latter is for cases where the event only makes sense in the context of a room.
src/site/markdown/development/rabbitmq.md 0 → 100644
View file @ f55cc773
# RabbitMQ
Setup user:
```
rabbitmqctl add_user arsnova arsnova
rabbitmqctl set_user_tags arsnova administrator
rabbitmqctl set_permissions -p / arsnova ".*" ".*" ".*"
```
Enable STOMP:
`rabbitmq-plugins enable rabbitmq_stomp`
[Optional] Enable Management Plugin (localhost:15672):
`rabbitmq-plugins enable rabbitmq_management`
Naming conventions:
- https://rabbitmq.docs.pivotal.io/36/rabbit-web-docs/stomp.html
In short:
- /queue for single subscriber
- /topic for fanout subscription
- only use [a-zA-Z0-9]
src/site/markdown/development/roadmap.md 0 → 100644
View file @ f55cc773
# Roadmap
## 4.0
* Remove API v2 compatibility layer
## 3.1
TBD
## 3.0
Version 3.0 is a rewrite of large parts of the code base with the goal of improving its maintainability.
A new streamlined REST API is developed while the legacy API is still supported through a compatibility layer.
### Beta 2
## Deployment & Operations
* Implement a monitoring endpoint for Prometheus
## Documentation
* Create/update developer documentation
* REST API
* Architecture
* Coding guidelines
* Update installation and upgrade guide
## QA
* Review critical issues detected by static code analysis
### Beta 1
## General architecture
* Implement data validation for entities
* Use better caching implementation (Ehcache, etc.)
* Review and complete caching (annotations, keys, etc.)
* Review and complete authorization handling
* Review event system and unify emitting of events for CRUD operations
* https://spring.io/blog/2015/02/11/better-application-events-in-spring-framework-4-2
* Review and improve error handling
* Exceptions
* HTTP responses
* Logging
* Use modern logging framework (SLF4J with Logback instead of Log4j)
## REST API
* Adjust handling of non-persistent entities for API v3
* Reimplement export and import
## QA
* Increase code coverage for testing
* Implement performance tests (Gattling)
* Ensure Java 11 (LTS) compatibility
* Review blocker issues detected by static code analysis
### Alpha
## General architecture
* Minimize code duplication
* Use generic classes for entity related controllers, services and data repositories
* Prefer constructor injection for required dependencies
* Use setter injection for optional dependencies
* Avoid field injection (it's fine in test classes)
* Use Jackson's JsonViews to define property visibility for API and persistence
* Refactor entities
* Introduce abstract Entity class with common properties
* Improve nomenclature for class and property naming
* Avoid use-case specific names (such as "Peer Instruction" for multiple rounds)
* Session -> Room
* Lecture Question -> Content
* Audience Question -> Comment
* Learning Progress -> Score
* Question Type -> Content Format
* Do not reuse one entity type for multiple domain types
* `Question` -> split up into `Content`, `Comment`
* `Answer` -> split up into `Answer`, `AnswerStatistics`
* Use subclasses to implement different formats for Content and Answer
## Persistence
* Abstract and split up persistence layer with help of Spring Data interfaces
* Get rid of JSON-lib (buggy and unmaintained) and use Jackson for all JSON (de-)serialization
* Use Ektorp instead of CouchDB4J (buggy and unmaintained) for CouchDB handling
* Implement view creation and data migration in Java (replace Setup Tool used for 2.x)
* Merge redundant database views
* Avoid emitting full docs and use `include_docs` instead
## REST API
* Implement support for handling multiple API versions
* Implement API v3
* Stateless: No more `/whoami` or `/myxyz` routes
* Use JWT instead of cookie-based sessions for authentication
* Use generic routes for CRUD
* Implement HTTP PATCH to update properties
* No more `/<entity>/disablexyz`
* Implement a `/<entity type>/find` endpoint
* Provide statistics with non-aggregated combinations of answer choices
* Implement customizable content groups
* They replace predefined content variants
* Relations are stored as part of a room
* They support auto sort (v2 behavior) and user defined ordering
* Implement API live migration layer v2 <-> v3
* v2 controllers convert between v2 and v3 entity types
* Internally (service and persistence layer) only the v3 entity type is used
src/site/markdown/index.md 0 → 100644
View file @ f55cc773
# Introduction
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](showcase.png)
src/site/markdown/installation.md 0 → 100644
View file @ f55cc773
# Installation
This document describes the necessary steps to install ARSnova Backend.
If 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 9 you can enable the backports repository to install Tomcat 9:
# grep -q '^deb .*stretch-backports' /etc/apt/sources.list || echo "deb http://deb.debian.org/debian stretch-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 running ARSnova.
This configuration would support up to 500 users.
## Configuration
You will need to do some configuration work upfront:
Create a copy of
[src/main/resources/arsnova.properties.example](../../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
[src/main/webapp/WEB-INF/spring/spring-main.xml](../../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
* 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 (APR) based Native library for Tomcat" (libapr and libtcnative) for improved performance.
Most of this software can easily be installed on Linux systems using the distribution's package manager:
* Debian/Ubuntu: `# apt-get install libtcnative-1 nginx openjdk-8-jre tomcat9`
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
If you are installing ARSnova for the first time and don't have any data from an older version that needs to be migrated,
you can follow CouchDB's guides to set up CouchDB 2:
* [Installation](https://docs.couchdb.org/en/stable/install/unix.html)
* [Single Node Setup](https://docs.couchdb.org/en/stable/setup/single-node.html)
After CouchDB is installed successfully, [set up an admin user](https://docs.couchdb.org/en/stable/config/auth.html)
with the credentials set before for `couchdb.username` and `couchdb.password`.
We provide a Python script that will set up a new database for ARSnova.
This "Setup Tool" is located at [thm-projects/arsnova-setuptool](https://github.com/thm-projects/arsnova-setuptool).
To set up the database, run:
$ ./tool.py
This will create the database along with all required view documents.
CouchDB is now usable for ARSnova, but there are still a few things that should be setup for performance reasons.
We recommend that you enable scheduled compactions of databases and their views.
Create a new file `99-compactions.ini` in the CouchDB configuration directory (usually located at `/opt/couchdb/etc/local.d`) with the following content:
[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/tomcat9`.
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 to 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 to use a reverse proxy, you should change the configuration so Tomcat only accepts requests from localhost.
Open `/etc/tomcat9/server.xml`, look for `<Connector port="8080" ...>`, and change it to:
<Connector port="8080" address="127.0.0.1" ...>
Additionally, you need to add a
[Remote IP Valve](https://tomcat.apache.org/tomcat-9.0-doc/config/valve.html#Remote_IP_Valve)
to make Tomcat aware of the `X-Forwarded` headers injected by the reverse proxy.
Look for the `<Host name="localhost" ...>` section and add:
<Valve className="org.apache.catalina.valves.RemoteIpValve"
internalProxies="127\.0\.0\.1"
remoteIpHeader="x-forwarded-for"
protocolHeader="x-forwarded-proto" />
If the reverse proxy is not running locally, you need to adjust the regular expression for `internalProxies` accordingly.
### 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 Host $host;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
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";
}
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
RequestHeader set X-Forwarded-Proto %{REQUEST_SCHEME}
</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
## Docker
If you want to run ARSnova in a containerized environment, you can use our Docker images.
Have a look at our [deployment instructions](https://github.com/thm-projects/arsnova-docker) for Docker.
src/site/markdown/upgrade.md 0 → 100644
View file @ f55cc773
# Upgrading ARSnova
This document describes the necessary steps to upgrade ARSnova Backend.
If 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, for example.
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](../../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.
src/site/resources/arsnova.png
View replaced file @ 47010d58 View file @ f55cc773
src/site/resources/arsnova.png

24.5 KiB | W: 0px | H: 0px

src/site/resources/arsnova.png

8.53 KiB | W: 0px | H: 0px

src/site/resources/arsnova.png
src/site/resources/arsnova.png
src/site/resources/arsnova.png
src/site/resources/arsnova.png
  • 2-up
  • Swipe
  • Onion skin
src/site/resources/showcase.png
View replaced file @ 47010d58 View file @ f55cc773
src/site/resources/showcase.png

143 KiB | W: 0px | H: 0px

src/site/resources/showcase.png

120 KiB | W: 0px | H: 0px

src/site/resources/showcase.png
src/site/resources/showcase.png
src/site/resources/showcase.png
src/site/resources/showcase.png
  • 2-up
  • Swipe
  • Onion skin
src/site/site.xml
View file @ f55cc773
<?xml version="1.0" encoding="ISO-8859-1"?> <?xml version="1.0" encoding="UTF-8"?>
<project name="ARSnova" xmlns="http://maven.apache.org/DECORATION/1.0.0" <project name="ARSnova" xmlns="http://maven.apache.org/DECORATION/1.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
...@@ -7,7 +7,7 @@ ...@@ -7,7 +7,7 @@
<skin> <skin>
<groupId>org.apache.maven.skins</groupId> <groupId>org.apache.maven.skins</groupId>
<artifactId>maven-fluido-skin</artifactId> <artifactId>maven-fluido-skin</artifactId>
<version>1.2.1</version> <version>1.7</version>
</skin> </skin>
<custom> <custom>
...@@ -22,8 +22,6 @@ ...@@ -22,8 +22,6 @@
<projectId>arsnova</projectId> <projectId>arsnova</projectId>
<widget>stats</widget> <widget>stats</widget>
</ohloh> </ohloh>
<facebookLike />
<googlePlusOne />
</fluidoSkin> </fluidoSkin>
</custom> </custom>
...@@ -39,30 +37,30 @@ ...@@ -39,30 +37,30 @@
<body> <body>
<head> <head>
<![CDATA[
<link rel="stylesheet" type="text/css" href="css/thm-theme.css" /> <link rel="stylesheet" type="text/css" href="css/thm-theme.css" />
]]>
</head> </head>
<links> <links>
<item name="THM" href="http://www.thm.de/" /> <item name="THM" href="https://www.thm.de/" />
</links> </links>
<menu name="Overview"> <menu name="Overview">
<item name="Introduction" href="index.html" /> <item name="Introduction" href="index.html" />
<item name="License" href="license.html" /> <item name="License" href="licenses.html" />
<item name="The Team" href="team-list.html" /> <item name="The Team" href="team.html" />
</menu> </menu>
<menu name="Documentation"> <menu name="Documentation">
<item name="Installation" href="https://github.com/thm-projects/arsnova-war#production-use" /> <item name="Installation" href="installation.html" />
<item name="Development" href="https://github.com/thm-projects/arsnova-war#development" /> <item name="Upgrading" href="upgrade.html" />
<item name="Development" href="development.html" />
<item name="Dependencies" href="dependencies.html" /> <item name="Dependencies" href="dependencies.html" />
<item name="API Docs" href="apidocs/index.html" /> <item name="API Docs" href="apidocs/index.html" />
</menu> </menu>
<menu name="Further Information"> <menu name="Further Information">
<item name="Gitorious" href="https://scm.thm.de/arsnova" /> <item name="Source Repository" href="scm.html" />
<item name="Issue Tracking" href="issue-tracking.html" /> <item name="Issue Tracking" href="issue-management.html" />
<item name="Sonar" href="https://scm.thm.de/sonar/dashboard/index/de.thm.arsnova:arsnova-war" /> <item name="SonarQube Metrics" href="https://scm.thm.de/sonar/dashboard/index/de.thm.arsnova:arsnova-backend" />
<item name="Continuous Integration" href="integration.html" /> <item name="Continuous Integration" href="ci-management.html" />
<item name="Source Repository" href="source-repository.html" />
<item name="Metrics" href="cobertura/index.html" />
</menu> </menu>
</body> </body>
</project> </project>