Migration guide

This guide explains how to prepare your Apollo 2.x instance, and to migrate data from previous Web Apollo versions into 2.0.

In all cases you will need to follow the guide for setting up your 2.x instance.

Migration from Evaluation to Production:

If you are running your evaluation/development version using ./apollo run-local when you setup your production instance, any prior annotations will use a separate database.

If you are using the same production instance you can use scripts to delete all annotations and preferences:


or just the annotations:


If you want to start from scratch (including reloading organisms and users), you can just drop the database (when the server is not running) and the proper tables will be recreated on startup.

Migration from 2.0.X to 2.0.Y on production:

  • Backup your database (to be safe).
  • Use your old apollo-config.groovy to create a new war file.
  • Turn off tomcat and remove the old apollo directory in the webapps folder.
  • Copy in new .war file with the same name.
  • Restart tomcat and you are ready to go.

Migration from 1.0 to 2.0:

We provide examples in the form of migration scripts in the docs/web_services/examples directory. These tools are also described in the command line tools section.

We have written many of the command line tools examples using the groovy language, but mostly any language will work (Perl, shell/curl, Python, etc.).

Migrate Annotations

We provide a migration script that connects to a single Web Apollo 1 instance and populates the annotations for an organism for a set of sequences / (confusingly called tracks as well). It would be best to develop your script on a development instance of Apollo2 for restricted sequences.

To get the scripts working properly, you'll need to provide the list of sequences (or tracks) to migrate for each organism. You can get the list of tracks by either using the database (select * from tracks ;) or looking in the Web Apollo annotations directory

ls -1 /opt/apollo/annotations/ | grep Annotations | grep -v history | paste -s -d"," -

Migrate Users

You have to add users de novo using something like the add_users.groovy script. In this case you create a csv file with the email, name, password, and role ('user' or 'admin'). This is passed into the add_users.groovy script and users are added.

From Web Apollo 1, you should be able to pull user names out of the database select * from users ;, but there is not much overlap between users in Web Apollo1.x and Apollo2.x.

If you have only a few users, however, just adding them manually on the users will likely be easier.

Add Organisms

If possible adding organisms on the organisms tab is the easiest option if you only have a handful of organisms.

The add_organism.groovy script can help automate this process if you have a large number of migrations to handle.