1.3 TO 1.4 UPGRADE

Changes

To get a full overview of all changes in Daisy 1.4, have a look at the notes of the various Milestone releases. Some highlights:

  • "book" publication functionality (the major new feature of this release)
  • A backup mechanism and accompanying backup tool
  • Various improvements to the editor
  • Other miscellaneous improvements and bug fixes

Compatability

Skin compatability

To check what has changed to the default skin, and possibly adjust your own skin for these changes, you can look at the skins directory in SVN and check the changes between revision 2219 (Daisy 1.3.1) and revision 2609 (Daisy 1.4). It will be easier to spot which files have changed by looking at the trunk.

Upgrading

FOLLOW THESE INSTRUCTIONS CAREFULY! Take your time to perform the upgrade.

These instructions are for upgrading from Daisy 1.3, 1.3.1, 1.4-M1 or 1.4-M2. To upgrade from earlier releases, first check the upgrade instructions for the earlier releases to run any required database updates or to perform the required configuration changes.

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

Run the database upgrade script

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

(There were only database changes between Milestone 2 and 3, that's why the script is named the way it is)

MySQL configuration change for MySQL 4.0.x

If you are using MySQL 4.0.x (only MySQL 4.0, not MySQL 4.1 or 5), then a change must be made to the configuration of the database server. More specifically, the parameter 'sql_mode' must be set to 'ANSI_QUOTES'. The easiest way to do this is by adding it to the my.cnf file. Therefore, open the my.cnf file in a text editor (on unix typically located at /var/lib/mysql/my.cnf), and in the section [mysqld] add the following line:

sql_mode = ANSI_QUOTES

Restart the MySQL server after making this change.

Make a change to the myconfig.xml

Open the following file in a text editor:

<daisy-data-dir>/conf/myconfig.xml

Somewhere in that file you will see a few lines like this:

  <target path="/daisy/jmx/mbeanserver">
    <configuration>
      <httpAdaptor port="9264" host="localhost" authenticationMethod="basic" username="daisyjmx" password="daisyjmx"/>
    </configuration>
  </target>

Inside the <configuration> element, add the following, but change the value of the "password" attribute to something of your choice (it doesn't need to be something easy to remember):

<xmlHttpAdaptor port="9265" host="localhost" authenticationMethod="basic" username="daisyjmx" password="daisyjmx"/>

So the final result should be similar to this:

  <target path="/daisy/jmx/mbeanserver">
    <configuration>
      <httpAdaptor port="9264" host="localhost" authenticationMethod="basic" username="daisyjmx" password="daisyjmx"/>
      <xmlHttpAdaptor port="9265" host="localhost" authenticationMethod="basic" username="daisyjmx" password="daisyjmx"/>
    </configuration>
  </target>

When using a custom startup script for the Wiki

If, for starting the Wiki, you are not using the standard scripts in Daisy but custom scripts (e.g. the service wrapper mechanism), then make sure the java command that starts the Wiki gets the following additional parameter (for the service wrapper this is dsy_wiki_wrapper.conf):

-Dorg.mortbay.util.URI.charset=UTF-8

See also the updated dsy_wiki_wrapper.conf.

This parameter is specific to Jetty, so if you are running the Wiki in another servlet container, ignore this.

Also, in the service wrapper file for the Daisy Wiki (dsy_wiki_wrapper.conf) the following parameter was missing, which should be added:

wrapper.java.additional.4=-Djava.endorsed.dirs=%DAISY_HOME%/daisywiki/endorsedlibs

When running the Wiki in Tomcat

If you deploy the Daisy Wiki on Tomcat, edit the file TOMCAT_HOME/conf/server.xml, search for the element <Connector port="8080" ...  (or equivalent) and add to it the attribute URIEncoding="UTF-8".

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. Same applies for other resources (e.g. skins).
  • If modified, copy <OLD_DAISY_HOME>/daisywiki/webapp/daisy/external-include-rules.xml to <NEW_DAISY_HOME>/daisywiki/webapp/daisy/external-include-rules.xml

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.1.7-bin.jar

Note that this is a different version of the MySQL jar file than in earlier Daisy versions!

If instead you use the service wrapper to start OpenJMS, then you need to update dsy_openjms_wrapper.conf and update the driver path over there:

wrapper.java.classpath.2=%DAISY_HOME%/lib/mysql/jars/mysql-connector-java-3.1.7-bin.jar

Update MySQL JDBC jar

This version of Daisy ships with a new version of the MySQL JDBC jar which fixes some issues, especially when using MySQL 5.

Therefore, you need to make the following configuration changes.

Open the following file in a text editor:

<daisy-data-dir>/conf/myconfig.xml

Search for the <driverClasspath> tag, which will look similar to this:

<driverClasspath>/home/meneerpatat/daisy/lib/mysql/jars/mysql-connector-java-3.0.15-ga-bin.jar</driverClasspath>

Change the file name of the jar file to:

mysql-connector-java-3.1.7-bin.jar

(also update the directory location if you are installing the new version of Daisy in another location)

Changes to be done only for MySQL 4.x, not for MySQL 5

The following changes should (and must) be done when using MySQL 4.x, but must not be done when using MySQL 5.

One or two lines above the line containing the <driverClasspath> tag, you will see a tag <url>. The url needs the following appended to it: ?useServerPrepStmts=false, so that it becomes (for example):

<url>jdbc:mysql://localhost/daisyrepository?useServerPrepStmts=false</url>

Now open the following file in a text editor:

<daisy-home>/openjms/config/openjms.xml

Somewhere in that file you will see a line like this:

<DatabaseConfiguration><RdbmsDatabaseConfiguration
     driver="com.mysql.jdbc.Driver"
     url="jdbc:mysql://localhost/openjms" (...)

As before, append ?useServerPrepStmts=false to the the url:

<DatabaseConfiguration><RdbmsDatabaseConfiguration
     driver="com.mysql.jdbc.Driver"
     url="jdbc:mysql://localhost/openjms?useServerPrepStmts=false" (...)

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.

Update repository schema

To install the new "MultiMediaObject" document type and the new document types for the books functionality, run the daisy-wiki-init application from the <DAISY_HOME>/install directory. No restart of the servers is needed after this.

Note about static resources and caching

Since static resources are cached for about 5 hours by your browser, you might need to clear the browsers' cache.

In Firefox, this is done using Edit -> Preferences -> Privacy -> press the "Clear" button next to Cache

Internet Explorer users, see here.

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.