2.12.3 Upgrading

Important: these are instructions for upgrading from Daisy 1.4 (or 1.4.1). To upgrade from older releases, e.g. Daisy 1.3, you first need to follow the instructions to upgrade to 1.4, and then these instructions (you don't need to actually download or install 1.4, just follow the instructions). To upgrade from Daisy 1.5-M1, follow the instructions for upgrading to 1.5-M2 (from 1.5-M2 to 1.5-final, there are no additional instructions). To upgrade from Daisy 1.5-M2, see the instructions (basically, nothing).

2.12.3.1 Before starting

Shutdown Daisy (the Repository Server, the Daisy Wiki, and the OpenJMS server)

Make backups! More specifically:

daisy-backup-tool -b -d $DAISYDATA_DIR -l $DAISY_BACKUP_DIR -o $DAISY_HOME/openjms -a additional-entries.xml

The '-a additional-entries.xml' is not required to make a backup, but if specified you can backup daisywiki specific files.  If you want to backup these files you must first create the addition-entries.xml file, an example can be found in the backup documentation.

If you can't get the backup tool to work (it was buggy in Daisy 1.4 on Windows), you can also do a manual backup:

• make a copy of the daisy data directory
• do a dump of the database:
  mysqldump daisyrepository -uuser -ppassword > daisyrepo.sql
• make a copy of at least daisy/daisywiki/webapp/WEB-INF/cocoon.xconf, and daisy/daisywiki/webapp/daisy/sites, preferably keep a copy of the whole daisy/daisywiki/webapp untill you have successfully upgraded and moved over all config.

2.12.3.2 Download and extract installation files

1. Rename your existing <DAISY_HOME> directory. During these instructions, we will refer to this location as <OLD_DAISY_HOME>.
2. Download the Daisy 1.5 installation files from here.
3. Extract the installation archive. Make sure that  your <DAISY_HOME> variable points to that newly created directory, if necessary, move or rename that directory (or adapt your <DAISY_HOME> environment variable).

2.12.3.3 Switching from OpenJMS to ActiveMQ

2.12.3.3.1 Make sure no messages are left in OpenJMS

Before moving to ActiveMQ, it is a good idea to check if there are no messages waiting to be processed in OpenJMS's queues. Usually JMS messages in Daisy are processed quickly, so unless you have had high activity right before shutting down the Daisy repository, there will normally be no more messages waiting to be processed.

To be sure, you can do a quick check like this:

1. start OpenJMS
2. go to OPENJMS_HOME/bin, and execute the "admin" script. This will launch a GUI window. In its menu, choose Actions, Connections, Online. It will ask for a username and password. The username is normally "admin", the password can be found in the file OPENJMS_HOME/config/openjms.xml (look for <User name="admin" password="something"/>). Once connected, you see the topics with their durable subscribers, and the queues. Next to them a number is displayed, they should all be zero.

If there would still be messages, just start the repostory server again, and wait till they have all been processed.

2.12.3.3.2 Creating a database for ActiveMQ

Start the MySQL client:

mysql -uroot

and execute:

CREATE DATABASE activemq;
GRANT ALL ON activemq.* TO activemq@'%' IDENTIFIED BY 'activemq';
GRANT ALL ON activemq.* TO activemq@localhost IDENTIFIED BY 'activemq';

ActiveMQ will automatically create its database tables the first time the repository server is launched.

2.12.3.3.3 ActiveMQ configuration

Create the ActiveMQ configuration :

cp <DAISY_HOME>/repository-server/conf/activemq-conf.xml.template <DAISY_DATA>/conf/activemq-conf.xml
cp <DAISY_HOME>/repository-server/conf/login.config <DAISY_DATA>/conf/
cp <DAISY_HOME>/repository-server/conf/users.properties <DAISY_DATA>/conf/
cp <DAISY_HOME>/repository-server/conf/groups.properties <DAISY_DATA>/conf/

Update myconfig.xml (<DAISY_DATA>/conf/myconfig.xml):

Look for the following element:

<target path="/daisy/jmsclient/jmsclient">

and replace the <configuration> element inside it with:

<configuration>
  <jmsConnection>
    <clientId>daisy-repository</clientId>
    <credentials username="admin" password="jmsadmin"/>
    <initialContext>
      <property name="java.naming.provider.url" value="vm://DaisyJMS?brokerConfig=xbean:file:${daisy.datadir}/conf/activemq-conf.xml"/>
      <property name="java.naming.factory.initial" value="org.apache.activemq.jndi.ActiveMQInitialContextFactory"/>
      <property name="queue.fullTextIndexerJobs" value="fullTextIndexerJobs"/>
      <property name="topic.daisy" value="daisy"/>
    </initialContext>
    <connectionFactoryName>ConnectionFactory</connectionFactoryName>
  </jmsConnection>
</configuration>

If you are using MySQL 5 (thus not 4.1), then you need to edit <DAISY_DATA>/conf/activemq-conf.xml. Look for the following line (here split on two lines for readability):

<property name="url" value="jdbc:mysql://localhost/activemq?relaxAutoCommit=true&amp;
                         useServerPrepStmts=false&amp;sessionVariables=storage_engine=InnoDB"/>

In this, you should remove the "useServerPrepStmts=false&amp;", so that it becomes:

<property name="url" value="jdbc:mysql://localhost/activemq
          ?relaxAutoCommit=true&amp;sessionVariables=storage_engine=InnoDB"/>

2.12.3.4 Configuring the Driver Registrar component

This new component registers JDBC drivers that are used by datasources in the repository-server.

Background info: previously, the JDBC drivers were configured as part of the datasource, but since JDBC connections are now needed by multiple datasources in the same VM (both the repository server and ActiveMQ), their registration is now moved into a specific component.

Edit <DAISY_DATA>/conf/myconfig.xml, and add a new target :

<target path="/daisy/driverregistrar/driverregistrar">
  <configuration>
    <drivers>
      <driver>
        <classpath>${daisy.home}/lib/mysql/jars/mysql-connector-java-3.1.12-bin.jar</classpath>
      	<classname>com.mysql.jdbc.Driver</classname>
      </driver>
    </drivers>
  </configuration>
</target>

Notice the upgrade from mysql-connector 3.1.7 to mysql-connector 3.1.12

You may now also remove the references to JDBC drives from the datasource component.  In the same file look for "/daisy/datasource/datasource".  In the configuration of this component look for the "driverClasspath" and "driverClassName" elements.  You may simply remove both these elements like this :

<target path="/daisy/datasource/datasource">
    <configuration>
      <username>daisy</username>
      <password>daisy</password>
      <url>jdbc:mysql://localhost/daisyrepository?useServerPrepStmts=false</url>
      <driverClasspath>REMOVE THIS LINE</driverClasspath>
      <driverClassName>REMOVE THIS LINE</driverClassName>
      <maxActive>20</maxActive>
      <maxIdle>8</maxIdle>
      <minIdle>0</minIdle>
      <maxWait>5000</maxWait>
    </configuration>
  </target>

2.12.3.5 Upgrade blobstore to hierarchical format

The blobstore directory structure has changed from being flat to being hierarchical, therefore a conversion must be made.  There is a tool that will convert your existing data to the correct format.  It can be executed by running the following command :

<DAISY_HOME>/bin/daisy-blobstore-convertor <path-to-blobstore>

The <path-to-blobstore> is normally <daisy data dir>/blobstore

The tool will print lines like:

Upgrading 1014764c672c25335146498e33393b30642a4207

for each processed file. If the tool outputs nothing, then either something is wrong (you give the incorrect path to the blobstore), or your blobstore is empty (very unlikely, impossible if you've installed the wiki).

2.12.3.6 Run database upgrade script

cd <DAISY_HOME>/misc
mysql -Ddaisyrepository -udaisy -p<password>
[then on the mysql prompt]
\. daisy-1_4-to-1_5_M1.sql

2.12.3.7 Create pubreqs directory and update myconfig.xml

In the daisy data directory, create a new empty subdirectory called pubreqs (all lowercase). This directory becomes thus a sibling of the blobstore, indexstore, conf and logs directories.

Then open the following file in a text editor:

<daisy data dir>/conf/myconfig.xml

And add the following as a child of the root <targets> element (the order of this and the other <target> elements does not matter)

  <target path="/daisy/extensions/publisher/publisher">
    <configuration>
      <repositoryUser login="internal" password="defaultpwd"/>
      <publisherRequestDirectory>/somewhere/pubreqs</publisherRequestDirectory>
    </configuration>
  </target>

Change the value of the password attribute to the same value as the password attribute on the other <repositoryUser> elements in the same file.

Change the content of the <publisherRequestDirectory> to contain the absolute path to the new pubreqs directory you just created.

2.12.3.8 Updating wrapper configuration for the Repository Server

If you are using the service wrapper (or custom startup scripts) to start the repository server, then you will need to upgrade the configuration/scripts to pass some additional parameters. In dsy_repo_wrapper.conf, these have to be added (see also the full script):

wrapper.java.additional.4=-Djava.awt.headless=true
wrapper.java.additional.5=-Dorg.apache.commons.logging.Log=org.outerj.daisy.logging.DaisyLog
wrapper.java.additional.6=-Djava.security.auth.login.config=%DAISY_DATADIR%/conf/login.config
wrapper.java.additional.7=-Ddaisy.datadir=%DAISY_DATADIR%
wrapper.java.additional.8=-Ddaisy.home=%DAISY_HOME%

2.12.3.9 Optional: remove absolute paths in myconfig.xml

Daisy now allows to use properties in the myconfig.xml to avoid absolute paths. If you want, you can update your myconfig.xml and change absolute references to the daisy data directory and daisy home directory by ${daisy.datadir} and ${daisy.home} respectively. Doing this will allow to move your data directory around without changing the myconfig.xml.