Upgrading from umlaut 2.x

There is no automated migration tool for moving from Umlaut 2.x to Umlaut 3.x.

You will just have to install Umlaut 3.x following the Installation instructions, and then re-apply your local customizations. This should hopefully not be too hard.

Some differences:

• Umlaut is a gem now, your local Rails app is solely your own code, all shared Umlaut code is contained in the gem, not scattered about the rails app file structure.

• The service configuration that was in ./config/umlaut_config/services.yml and institutions.yml is now combined in one file in ./config/umlaut_services.yml. In a slightly different form.

• Configuration which before was recommended in initializers in ./config/umlaut_config/initializers now takes place in ./app/controllers/umlaut_controller.rb. The methods for adding configuration paramters have changed (we now use confstruct behind the scene), and some config key names have changed.

Umlaut 3.x should have a new database created for it, it has somewhat different schema than Umlaut 2.x, and you should not try to share databases.

One thing you WILL want to do before transitioning to Umlaut 3.x in production is move all your saved permalinks over to the new database, so permalinks created under Umlaut 2.x still work. See below.

See also Customizing

Migrating Permalinks

If you already have an Umlaut 2.x installation, when you move over to Umlaut 3.x, you'll want to migrate your Permalinks from the old database, so they keep resolving properly.

We provide a rake task to do that. It's a bit hacky. It also takes a long time to run -- on my system, around an hour for 4 million permalinks (you probably don't have as many). (You could decide to only keep recent permalinks if you want, but Umlaut 2.x does not track when a permalink was last actually accessed).

1. Set up a connection in config/database.yml called umlaut2_source pointing to your Umlaut 2.x database. (This can be removed when you are done migrating)
2. Add activerecord-import to your Gemfile, and bundle install.
3. Run RAILS_ENV=production rake umlaut:migrate_permalinks (to migrate to your new production db)

This will take a while, and it may take a lot of CPU/memory. Test it first in a non-production scenario. Note: If you include 'activerecord-import' in your Gemfile, this task will use that gem, and it will result in faster import -- if you have a huge number of permalinks to import highly recommended. It's still a time consuming process though -- for me, with about 5 million permalinks, it took about an hour.

Because it takes a while, we also provide a facility to only migrate permalinks after some pk id. So you can run the whole thing once, with Umlaut 2.x in production. Then, bring Umlaut 2.x down, run the task again to get any more recent permalinks, and bring Umlaut 3.x up in production.

RAILS_ENV=production rake umlaut:migrate_permalinks FROM_ID=40000232

for instance. The task always outputs on completion the highest id migrated, so you can use that to migrate only more recent ones the next time. You could use this feature to intentionally only migrate a more recent portion of your umlaut 2.x permalinks instead of all of them, too.

If you temporarily have an Umlaut instance up for testing, public to users, that wont' have it's permalinks database ultimately kept, you may want to set config create_permalinks to false in UmlautController, to suppress creation of permalinks at all, that won't be persisted long term.