!!!Upgrading an eXist installation

Notes about things to remember when upgrading an eXist installation used for risten.no. It is assumed that the risten.no-specific files are just linked in to the eXist tree, with a symlink in {{EXIST_HOME/webapp/}} named {{risten}}, pointing to your local copy of {{CVSROOT/termdb/src/db-app/risten/}}.

* make a backup of the db content (easily done with the Java client in eXist, {{EXIST_HOME/bin/client.sh}}), or on the command line. When on the command line, pass argument {{-oindent=yes}} to make the backup indented. Don't know yet how to pass that option in the graphical client. This option is available in 1.0/1.1 onwards.
* diff existing main sitemap with the one in {{db-app/}}, to make sure there are no changes that needs to be checked in - only the one in {{db-app/}} is part of the CVS repo and under version control - the other one will be deleted!
* diff the original {{EXIST_HOME/conf.xml}} with our local copy in {{CVSROOT/termdb/src/db-app/conf.xml}}. Update the local copy as with the sitemap above. Also check that {{CVSROOT/termdb/src/db-app/server-conf.xml}} is in sync - this is the server version of the configuration file, which contains one important addition compared to the developer/local version: a setting for automatically creating binary backups (see the element {{<system-task>}}).
* move the symlink temporarily out of the eXist dir tree
* uninstall eXist - this will delete and remove from the hard disk __everything__ within the eXist directory tree! Make sure once again that all changes and modifications within the eXist dir tree are duplicated or stored outside eXist before doing this!
* install the new version in your preferred location
* move the {{risten}} symlink back into {{EXIST_HOME/webapp/}}
* diff the original {{EXIST_HOME/webapp/sitemap.xmap}} with our local version in {{CVSROOT/termdb/src/db-app/sitemap.xmap}} to check whether there are changes in the original that we want to include; if so, update our local version, and commit the changes. When done, replace the original with our version by copying it over the original.
* redo a similar diff with {{conf.xml}}, propagating new settings to our local copies.
* copy {{CVSROOT/termdb/src/db-app/support/RistennoRequestAction.java}} to {{EXIST_HOME/src/org/exist/cocoon/}}
* rebuild eXist: {{EXIST_HOME/build.sh}}
* start eXist: {{EXIST_HOME/bin/startup.sh}}
* restore the data from the backup, using the graphical Java client
* test that everything in risten.no is working as it should (see separate test document - NOT YET WRITTEN), correct or update our own code as needed, or report new bugs in eXist to the eXist mailing list.


Phew! That should be it. You should now have a fresh eXist installation with all your old data in place. Enjoy the bug fixes and improvements!

!!!Upgrading using svn

If you have an eXist installation from the Subversion repository, the upgrade situation is much easier:

* make a backup using the Java client
* stop all eXist processes (usually client and server)
* cd into the eXist directory
* {{svn up}}
* {{build.sh clean; build.sh}}
* restart eXist
* start the client and restore the backup

That's it!

!!!Upgrading risten.no

Upgrading the installation on the public server is a bit different from both the above scenarios. Here are the steps:

* make a war file: {{build.sh dist-war}}. If the {{risten.no}} content was
  linked in as suggested above, it will be included as real files in the war
  file
* take a backup of the server, using the client
* verify that the backup is fine, no xml errors or other problems (hint: use
  {{xmllint --noout}} on the backed-up files - if no errors, then the xml is ok)
* log into the servlet host, Tomcat, and delete the old eXist webapp, using the
  Tomcat manager (requires username and password, obviously:-)
** __NB!__ This will
  delete all data, and the full risten.no application! It might be a good idea
  to make a copy of the installation before it is installed, in case something
  goes wrong. Using the copy, the previous version can easily be reinstalled. To
  make such a copy, log in to the server using a VPN client, and make a file
  copy in Windows of the whole eXist webapp folder.
* upload the new eXist war file using Tomcat Manager
* use the client to restore the data from the backup
* edit the file TOMCAT/webapps/exist/WEB-INF/web.xml, and change the Cocoon2
  servlet definition, encoding section, such that the container encoding reads
  {{ISO-8859-1}}, __NOT__ {{UTF-8}} (it should be around line 418). This is
  necessary to get non-ASCII chars
  correct through from web page forms - that is, without this change, it is
  impossible to search using Sámi or Norwegian characters!
* make sure that the backup system task (new in eXist 1.2-dev) is properly
  configured - it should run once a day, at 3 AM. It is configured in
  {{conf.xml}}, element {{system-task}} (around line 250), the @cron-trigger
  should have the following content: {{0 0 3 * * ?}}

That's it! Verify that everything is working.


!!!Function replacement
This is a one-time operation when upgrading to 1.0rc/1.1rc-newcore. Info is taken from [http://wiki.exist-db.org/space/Function+Mappings].

||Old Function || New Function
| request:create-session | session:create
| request:encode-url | session:encode-url
| request:get-request-data | request:get-data
| request:get-session-attribute | session:get-attribute
| request:get-session-id | session:get-id
| request:get-uploaded-file | request:get-uploaded-file
| request:get-uploaded-file-name | request:get-uploaded-file-name
| request:invalidate-session | session:invalidate
| request:parameter-names | request:get-parameter-names
| request:redirect-to | response:redirect-to
| request:request-hostname | request:get-hostname
| request:request-parameter | request:get-parameter
| request:request-servername | request:get-server-name
| request:request-serverport | request:get-server-port
| request:request-uri | request:get-uri
| request:request-url | request:get-url
| request:session-attributes | session:get-attribute-names
| request:set-current-user | session:set-current-user
| request:set-date-header | response:set-date-header
| request:set-session-attribute | session:set-attribute
| request:stream-binary | response:stream-binary
| request:unescape-uri | util:unescape-uri
| request:set-response-header | response:set-header
| util:eXist-version | system:get-version