Upgrading an ANNIS Server installation
These instructions are a guideline for upgrading the installation of ANNIS on a UNIX-like server. If you use the ANNIS Kickstarter version just download the new version and re-initialize the database. Please read the installation instructions first if you haven't done so yet.
Upgrading the ANNIS service is more complex than deploying the user interface WAR file. Therefore a Python script is available for an automatic upgrade. This script needs as least Python 3.2.
- Download the latest version of the script.
- Download the new ANNIS release files (
- Run the script
If the new release uses a new database schema the update might take some time. Thus it might be better to execute the script in the background:
python3 upgrade_service.py --cleanup-data <installation-directory> annis-service-<VERSION>.tar.gz
nohup python3 upgrade_service.py --cleanup-data <installation-directory> annis-service-<VERSION>.tar.gz & tail -f nohup.out
- If successful undeploy the old WAR file and deploy the new one.
In case the upgrade script needed to update the database (it will tell you so), you should delete the old schema from your PostgreSQL database by running the following command in your PostgreSQL-Client:
DROP SCHEMA <oldschema>;
Note: To learn more about the (additional) parameters of the script run:
python3 upgrade_service.py --help
When Python is not available it is still possible to execute the steps of the upgrade process manually. The upgrade path described here tries to have a minimum downtime.
Upgrade for minor version updates
For minor version updates, e.g. from 3.1.0 to 3.1.1 (thus only the last version number changes) you can use the database from the older version without any modifications. Thus an upgrade only consists of the following steps
- backup the old installation files
- download the files of the new version
- backup the
conf/database.propertiesfile of the ANNIS service
- if you made any manual adjustments to the file
conf/annis-service.propertiesalso backup it
- stop the old ANNIS service
- overwrite the files of the old ANNIS service installation with the new version
- overwrite the
conf/database.propertiesfile with the backup
- apply the changes you made to the
conf/annis-service.propertieson the new version (e.g. set the port number)
- start the ANNIS service again
- undeploy the old WAR file and deploy the new WAR file
Whenever the first or second number of the version changes you have to re-import the corpora into a newly initialized database.
Download both the
annis-service-<VERSION>.tar.gz and the
to a folder of your choice, e.g.
2. Install the new service
Unzip the annis service to a new directory (don't delete or stop the old service)
and install it.
These steps are similiar to how to [install a new ANNIS service](@ref admin-install-server).
tar xvzf /tmp/annis-service-
conf/annis-service.properties file copy
the changes to the new installation.
Then initialize the the database for the new installation.
annis-admin.sh init -u
conf/database.properties file of the old installation).
--schema allows you to define a new PostgreSQL schema
which will be used for the new installation.
A good name could be something like "v32" if the version is 3.2.0.
3. Copy old corpora
With the command
nohup to make sure
the process will continue to run in the background even if the connection is interrupted.
nohup annis-admin.sh copy
Additionally copy the "user_config" and "url_shortener" tables from the
old installation, e.g. with the PostgreSQL
4. Switch service
Stop the old service and start the
new service. Remember to set the
ANNIS_HOME variable to the right value in
both cases before you call
annis-service.sh start/stop command.
5. Upgrade front-end
Undeploy the old WAR file and deploy the new WAR file.
If everything works as expected you can delete the old installation files. You should also remove the contents of the old database by deleting the schema from the PostgreSQL client:
DROP SCHEMA <oldschema>;
To delete all unused external data files execute
\warning This will delete all data files not known to the current instance of ANNIS.
If you have multiple parallel installations and did not use different values for
annis.external-data-path variable in the
the data files of the other installations will be lost.