upgrade.md

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