Snippets Groups Projects

Split up and rewrite documentation · d59d07aa

Daniel Gerhardt authored 8 years ago

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

d59d07aa

upgrade.md 2.51 KiB

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 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 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.