1.2 TO 1.3 UPGRADE

These instructions are for upgrading from Daisy 1.2 to Daisy 1.3. If you are running a 1.3 milestone release, please see the documents describing the upgrade procedures for going from one milestone release to the next. If you are running an older milestone release then 1.3-M3, for example 1.3-M1, then you need to follow the instructions for upgrading to each in-between milestone release (but you don't need to download all these releases, just apply the required database and configurations updates, if any).

What's new

For an overview of changes in each release, I'll just point to the documents of the individual pre-releases:

Also pay attention to the 1.3-M3 compatibility notes.

Upgrading

Before starting

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

Make backups! More specifically:

  • make a copy of the daisy data directory
  • do a dump of the database:
    mysqldump daisyrepository -uuser -ppassword > daisyrepo.sql
  • make a copy of daisy/daisywiki/webapp/WEB-INF/cocoon.xconf, and daisy/daisywiki/webapp/daisy/sites

Update database schema

There have been a few changes to the database schema. To upgrade it, perform the following steps in a command prompt or shell:

Daisy 1.3 has a new feature called language variants that allows to have multiple language versions of the same document. By default, after migrating the repository, all documents will belong to a language called "default". If all the documents in your current repository are in the same language, and you want them to be classified under a more specific langauge then "default", then see the instructions at the top of the file misc/daisy-1_2-to-1_3_M1.sql

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

(thus the upgrade is split over 3 scripts)

Update OpenJMS configuration

Starting with Daisy 1.3-M1, the installation configures OpenJMS to use TCP instead of RMI as transport protocol, which has the advantage that is more firewall-friendly since it uses a fixed port number.

Therefore, perform the following steps:

  1. copy <OLD_DAISY_HOME>/openjms/config/openjms.xml to <NEW_DAISY_HOME>/openjms/config/openjms.xml
  2. Open the file <NEW_DAISY_HOME>/openjms/config/openjms.xml in a text editor
  3. Inside the <Connectors> element, add the following:
        <Connector scheme="tcp">
          <ConnectionFactories>
            <QueueConnectionFactory name="TCPQueueConnectionFactory"/>
            <TopicConnectionFactory name="TCPTopicConnectionFactory"/>
          </ConnectionFactories>
        </Connector>
  4. Add the following element somewhere as a child of the root element (for example, before the </Configuration> closing tag):
    <TcpConfiguration port="3030" jndiPort="3035"/>
  5. open the file <DAISY_DATA>/conf/myconfig.xml in a text editor. Look for the following line:
    <target path="/daisy/jmsclient/jmsclient">

    and replace the content of the <configuration> element following it with the following, but be sure to keep the old password on the credentials element:

    <configuration>
      <jmsConnection>
        <credentials username="admin" password="openjms"/>
        <initialContext>
          <property name="java.naming.provider.url" value="tcp://localhost:3035/"/>
          <property name="java.naming.factory.initial"
                    value="org.exolab.jms.jndi.InitialContextFactory"/>
        </initialContext>
        <topicConnectionFactoryName>TCPTopicConnectionFactory</topicConnectionFactoryName>
        <queueConnectionFactoryName>TCPQueueConnectionFactory</queueConnectionFactoryName>
      </jmsConnection>
    </configuration>

Copy over the old configuration

  • Copy <OLD_DAISY_HOME>/openjms/config/openjms.xml to <NEW_DAISY_HOME>/openjms/config/openjms.xml
  • Copy <OLD_DAISY_HOME>/daisywiki/webapp/daisy/sites/* to <NEW_DAISY_HOME>/daisywiki/webapp/daisy/sites
  • In <NEW_DAISY_HOME>/daisywiki/webapp/WEB-INF/cocoon.xconf, adjust the following passwords with the values you can find in <OLD_DAISY_HOME>/daisywiki/webapp/WEB-INF/cocoon.xconf:
    • Adjust the password for openjms user (if not left to default): <credentials password="openjms" username="admin"/>
    • Adjust the password for "internal' user: <cacheUser login="internal" password="defaultpwd"/>
    • Adjust the password for the "registrar" user: <registrarUser login="registrar" password="defaultpwd"/>
  • If you created any document type-specific stylesheets, you can copy them over also (see also the compatibilty notes!)
  • If you developed a custom skin, then you'll have to update it to work with the new version (see also the compatibility notes).

Edit <DAISY_HOME>/openjms/bin/setenv.(sh|bat), uncomment the line defining the CLASSPATH and put the MySQL driver in the CLASSPATH, which can be found at (substitute DAISY_HOME by its actual location):

DAISY_HOME/lib/mysql/jars/mysql-connector-java-3.0.15-ga-bin.jar

Erase Full Text Indexer files

Because of the introduction of the document variants feature, the format of the full text index files has changed. Therefore, delete all the files in the directory <DAISY_DATA>/indexstore.

Start the servers

Start OpenJMS, the Daisy Repository Server, and the Daisy Wiki.

If necessary, first update the DAISY_HOME and OPENJMS_HOME variables to point to the location of the new Daisy version.

Trigger full text index updating

Recreating the full text index can be done via the JMX console. Open a webbrowser and surf to http://localhost:9264.

If this prompts for a password and you don't know it, look in the file <DAISY_DATA>/conf/myconfig.xml for a line like:

<httpAdaptor authenticationMethod="none" host="localhost"
             password="daisyjmx" port="9264" username="daisyjmx"/>

and use the username and password mentioned there.

By default, the JMX console only allows connection from localhost. Change the host attribute on the above configuration element if needed. You need to restart the Daisy Repository Server for this change to take effect.

In the JMX web interface, follow the link that says "Daisy:name=FullTextIndexUpdater". Then press the Invoke button on the line that starts with "reIndexAllDocuments". Press this button only once, depending on the number of documents you have this can take a little while.

Note about static resources and caching

Since static resources are cached for about 5 hours by your browser, you might need to do a full reload (shift + reload button on the browsers' toolbar). Also when opening the editor for the first time do a shift + reload.

If these instructions or unclear to you, or if you find an error in them, please share them with us on the Daisy mailing list or by leaving a comment.