Daisy documentation
Book Index

Daisy documentation

Table of Contents

1 Documentation Home

These pages contain the Daisy documentation of the Daisy 1.5 release. The main Daisy site can be found here.

The documentation is also available published as a Daisy-book.

For an end-user introduction to Daisy, have a look at the video tutorials.

2 Installation

2.1 Downloading Daisy

Packaged versions of Daisy can be found in the distribution area (Sourceforge). This includes everything required to run Daisy, except for:

If you don't have these already, the installation of these will be covered further on.

Consider subscribing to the Daisy mailing list to ask questions and talk with fellow Daisy users and developers.

There is also information available about the source code.

2.2 Installation Overview

Daisy is a multi-tier application, consisting of a repository server and a publication layer. Next to those, a database server (MySQL) is required. All together, this means three processes, which can run on the same server or on different servers.

The Daisy binary distribution packs most of the needed software together, the only additional things you'll need is a Java Virtual Machine for your platform, and MySQL. All libraries and applications shipped with Daisy are the original, unmodified distributions that will be configured as part of the installation. We've only grouped them in one download for your convenience.

If you follow the instructions in this document, you can have Daisy up and running in less than an hour.

The diagram below gives an overview of the the setup. All shown port numbers are configurable of course.

2.2.1 Platform Requirements

We have tested the Daisy installation on Windows 2000/XP, GNU/Linux and MacOSX. Other unixes like Solaris should also work, though we don't test that ourselves.

2.2.2 Memory Requirements

By default, the Daisy Wiki and Daisy Repository Server are started with a maximum heap size of 128 MB each. To this you need to add some overhead of the JVMs themselves, and then some memory for MySQL, the OS and its (filesystem) caches. This doesn't mean all this memory will be used, that will depend on usage intensity.

2.2.3 Required knowledge

These installation instructions assume you're comfortable with installing software, editing configuration (XML) files, running applications from the command line, setting environment variables, and that sort of stuff.

2.2.4 Can I use Oracle, PostgreSQL, MS-SQL, ... instead of MySQL? Websphere, Weblogic, Tomcat, ... instead of Jetty? What is this Merlin thing?

Daisy contains the necessary abstractions to support different database engines, though we currently only support MySQL. Users are welcome to contribute and maintain different databases (ask on the mailing list how to get started).

The Daisy Wiki webapp should be able to run in any servlet container (at least one that can run unpacked webapps, and as far as there aren't any Cocoon-specific issues), but we ship Jetty by default. For example, using Tomcat instead of Jetty is very simple and is described on this page.

The Daisy Repository Server runs on top of a component runtime platform called Merlin. Generally you won't be aware of this, but if you see "merlin" popping up in process names, that means it is basically the same as the Daisy Repository Server.

2.3 Installing a Java Virtual Machine

Daisy requires either the Java SDK 1.4.2 or the Java JDK 5.0.

You can download the Java JDK 5.0 from here on the Sun site (take the JDK, not the JRE). Install it now if you don't have it already.

After installation, make sure the JAVA_HOME environment variable is defined and points to the correct location (i.e., the directory where Java is installed). To verify this, open a command prompt or shell and enter:

For Windows:
%JAVA_HOME%/bin/java -version

For Linux:
$JAVA_HOME/bin/java -version

This should print out something like:

java version "1.4.2_xx"

or

java version "1.5.0"

2.3.1 Installing JAI (Java Advanced Imaging) -- optional

If you want images (especially PNG) to appear in PDFs, it is highly advisable to install JAI, which you can download from the JAI homepage. Just take the "JDK Install" option, this will make JAI support globally available.

2.4 Installing MySQL

Daisy requires one of the following MySQL versions:

MySQL can be downloaded from mysql.com. Install it now, and start it (often done automatically by the install).

Windows users can take the "Windows Essentials" package. During installation and the configuration wizard, you can leave most things to their defaults. In particular, be sure to leave the "Database Usage" to "Multifunctional Database", and leave the TCP/IP Networking enabled (on port 3306). When it asks for Windows options, check the option "Include Bin Directory In Windows Path".

Linux users: install the "MySQL server" and "MySQL client" packages. Installing the MySQL server RPM will automatically initialize and start the MySQL server.

2.4.1 Creating MySQL databases and users

MySQL is used by both the Daisy Repository Server and JMS (ActiveMQ). Therefore, we are now going to create two databases and two users.

Open a command prompt, and start the MySQL client as root user:

mysql -uroot -pYourRootPassword

On some systems, the root user has no password, in which case you can drop the -p parameter.

Now create the necessary databases, users and access rights by entering (or copy-paste) the commands below in the mysql client. What follows behind the IDENTIFIED BY is the password for the user, which you can change if you wish. The daisy@localhost entries are necessary because otherwise the default access rights for anonymous users @localhost will take precedence. If you'll run MySQL on the same machine as the Daisy Repository Server, you only need the @localhost entries.

CREATE DATABASE daisyrepository CHARACTER SET 'utf8';
GRANT ALL ON daisyrepository.* TO daisy@'%' IDENTIFIED BY 'daisy';
GRANT ALL ON daisyrepository.* TO daisy@localhost IDENTIFIED BY 'daisy';
CREATE DATABASE activemq CHARACTER SET 'utf8';
GRANT ALL ON activemq.* TO activemq@'%' IDENTIFIED BY 'activemq';
GRANT ALL ON activemq.* TO activemq@localhost IDENTIFIED BY 'activemq';

2.5 Extract the Daisy download

Extract the Daisy download. On Linux/Unix you can extract the .tar.gz file as follows:

tar xvzf daisy-<version>.tar.gz

On non-Linux unixes (Solaris notably), use the GNU tar version if you experience problems extracting.

On Windows, use the .zip download, which you can extract using a tool like WinZip.

After extraction, you will get a directory called daisy-<version>. This directory is what we will call from now on the DAISY_HOME directory. You may set a global environment variable pointing to that location, or you can do it each time in the command prompt when needed.

2.6 Daisy Repository Server

2.6.1 Initialising and configuring the Daisy Repository

Open a command prompt or shell and set an environment variable DAISY_HOME, pointing to the directory where Daisy is installed.

Windows:
set DAISY_HOME=c:\daisy-1.5

Linux:
export DAISY_HOME=/home/daisy_user/daisy-1.5

Then go to the directory <DAISY_HOME>/install, and execute: 

daisy-repository-init

Follow the instructions on screen. The installation will (1) initialise the database tables for the repository server and (2) create a Daisy data directory containing customized configuration files.

Make sure that name of the path that you provide for the Daisy data directory does not contain spaces, otherwise the startup of the repository server will fail.

2.6.2 Starting the Daisy Repository Server

Still in the same command prompt (or in a new one, but make sure DAISY_HOME is set), go to the directory <DAISY_HOME>/repository-server/bin, and execute:

daisy-repository-server <location-of-daisy-data-dir>

In which you replace <location-of-daisy-data-dir> with the location of the daisy data directory created in the previous step.

The start-up can take a few seconds, though nothing special is printed to the screen to indicate it is completely started (the prompt will not return).

2.7 Daisy Wiki

2.7.1 Initialising the Daisy Wiki

Before you can run the Daisy Wiki, the repository needs to be initialised with some document types, a "guest" user, a default ACL configuration, etc.

Open a command prompt or shell, make sure DAISY_HOME is set, go to the directory <DAISY_HOME>/install, and execute:

daisy-wiki-init

The program will start by asking a login and password, enter here the user created during the execution of daisy-repository-init (the default was testuser/testuser). It will also ask for the URL where the repository is listening, you can simply press enter here.

If everything goes according to plan, the program will now print out some informational messages and end with "Finished.".

2.7.2 Creating a "wikidata" directory

Similar to the data directory of the Daisy repository server, the Daisy Wiki also has its own data directory (which we call the "wikidata directory").

To set up this directory, open a command prompt or shell, make sure DAISY_HOME is set, go to the directory <DAISY_HOME>/install, and execute:

daisy-wikidata-init

and follow the instructions on-screen.

Since the Daisy Wiki and the Daisy repository server are two separate applications (which might be deployed on different servers), each has its own data directory.

2.7.3 Creating a Daisy Wiki Site

The Daisy Wiki has the concept of multiple sites, these are multiple views on top of the same repository. You need at least one site to do something useful with the Daisy Wiki, so we are now going to create one.

Open a command prompt or shell, make sure DAISY_HOME is set, go to the directory <DAISY_HOME>/install, and execute:

daisy-wiki-add-site <location of wikidata directory>

The application starts by asking the same parameters as for daisy-wiki-init.

Then it will ask a name for the site. This should be a name without spaces. If you're inspirationless, enter something like "test" or "main".

Then it will ask for the sites directory location, for which the presented default should be OK, so just press enter.

2.7.4 Starting the Daisy Wiki

Open a command prompt or shell and make sure DAISY_HOME is set.

Go to the directory <DAISY_HOME>/daisywiki/bin, and execute: 

daisy-wiki <location of wikidata directory>

Background info: this will start Jetty (a servlet container) with the webapp found in <DAISY_HOME>/daisywiki/webapp.

2.8 Finished!

Now you can point your web browser to:

http://localhost:8888/daisy/

(Note the final slash on the end)

To be able to create or edit documents, you will have to change the login, you can use the user you created for yourself while running daisy-repository-init (the default was testuser/testuser).

To start the Daisy repository server and Daisy Wiki after the initial installation, see the summary here, or even better, set up service (init) scripts to easily/automatically start and stop Daisy.

2.9 1.4 to 1.5-M1 upgrade

Daisy 1.5-M1 was released on March 22, 2006.

2.9.1 Changes

2.9.1.1 Features

2.9.1.2 Non-features

2.9.1.3 Bug fixes

2.9.2 Compatibility

2.9.2.1 Document type specific stylesheet

There is small difference in the output of the publisher requests which influences the document type specific stylesheets. Don't worry, it is a very minor change, depending on how your stylesheets are written they might even require no change at all.

Where the input previously contained this element hierarchy:

document > d:document

it has now become:

document > p:publisherResponse > d:document

Where "p:" is the publisher namespace, thus bound as:

xmlns:p="http://outerx.org/daisy/1.0#publisher"

If you want to have stylesheets that work with both releases, you can write them so that they first test for the presence of document/d:document and if not available use document/p:publisherResponse/d:document

2.9.2.2 Custom styling: attributes on links

The links in document content were previously annotated with the attributes daisyDocumentName, daisyFileName and daisyNavigationPath. These have been removed in favour of a more powerful system, as explained in this mail.

If you have custom document type specific XSLs or book publication types, you might want to do a search for @daisyDocumentName used in XPath expressions, and replace it by p:linkInfo/@documentName, the p prefix should be declared as:

xmlns:p="http://outerx.org/daisy/1.0#publisher"

2.9.2.3 Auto-redirecting between sites

The Daisy Wiki now has the ability to automatically redirect to another site if a document is better suited to be displayed over there. This is enabled by default, and can be disabled by adding the following element in the skinconf.xml of each site for which you want to disable this:

<siteSwitching mode="stay"/>

2.9.2.4 Field type in HTTP interface

A small change has been done to the field type XML. If you have any programs making direct use of the HTTP interface, you'll need to adjust them.

Where you previously had a <d:selectionList> element for specifying a static selection list, the <d:selectionList> element now contains an extra <d:staticSelectionList> element which then contains the elements previously contained in <d:selectionList>. This change was done to allow for alternative selection list implementations.

2.9.2.5 Publisher XML Beans generated classes

Applies when using custom publisher requests build up via the Java objects (instead of written in XML).

The structure of the XML Schema for the publisher requests has changed a little bit, which has caused some small changes in the nesting of the classes generated by XMLBeans for this XML Schema. Adjusting your code for this is straightforward.

2.9.3 Upgrading

2.9.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.

2.9.3.2 Upgrade blobstore to hierarchical format

The blobstore structure has changed from being flat to being hierarchical, therefore a conversion must be made.  Luckily 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>

This should be quite a painless procedure but seeing the delicate nature of this operation it might be wise to create a backup first.

2.9.3.3 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.9.3.4 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.9.3.5 Add headless option for repository server

If you are using the service wrapper or another custom startup script, you should add the java.awt.headless parameter, e.g. in dsy_repo_wrapper.conf the line:

wrapper.java.additional.4=-Djava.awt.headless=true

If you don't do this, image thumbnail generation will fail.

2.9.3.6 Update classpath for Jetty 5

If you are using the service wrapper or another custom startup script for the Daisy Wiki, note that Daisy now ships with Jetty 5. For the wrapper, this means the classpath has changed. See the updated dsy_wiki_wrapper.conf file.

2.9.3.7 Copy over the old configuration

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

2.9.3.8 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.

2.9.3.9 Upgrade Daisy Wiki schema

Run the daisy-wiki-init script to update the Daisy Wiki schema types:

cd <DAISY_HOME>/install
daisy-wiki-init

Run daisy-wiki-init (for ImageThumbnail etc.)

2.9.3.10 [optional] Image thumbnail generation

Daisy 1.5 can generate image thumbnails and extract their width and height to store them in fields of the Image document type. If you want to do this for all your current images, you can do so by running a document task. For this, first make sure you're logged in as Administrator, then go to the Document Tasks screen (the link is in the user menu) and create a new document task. Select the documents using the query:

select name where documentType = 'Image'

You might first want to try this with one document to see if everything is OK.

Then go to the next screen, and use the following script:

var document = repository.getDocument(variantKey, true);
document.setField("ImageWidth", new java.lang.Long(0));
document.save();

This script "touches" the document by setting a field to a dummy value. Otherwise, the document wouldn't be changed and no save will be performed.

2.10 1.5-M1 to 1.5-M2 upgrade

Daisy 1.5 Milestone 2 was released on June 21, 2006.

2.10.1 Changes

2.10.1.1 Important changes: read this section!

2.10.1.2 Other new features

2.10.1.3 Bug fixes & minor improvements

2.10.2 Compatibility notes

2.10.2.1 Skins

[todo: add helpful notes here on updating custom skins based on the old default skin]

2.10.2.2 Custom book publication types

If you made custom book publication types or document type specific XSLs for use in books, they might need some small changes due to the introduction of the wikidata directory.

In the query-styling.xsl of the publication type, if you want to import the default query styling XSL, the include should now be:

<xsl:include href="wikidata:books/publicationtypes/common/default-query-styling.xsl"/>

If in the custom document type specific XSL you included the default book-document-to-html.xsl file, the import should now be:

<xsl:include href="wikidata:books/publicationtypes/common/book-document-to-html.xsl"/>

2.10.2.3 Databases

MySQL 4.0 is not supported anymore. You might still be able to get it to work, but it wasn't worth the effort anymore for us to support it in the default configuration.

2.10.2.4 JmsClient API

If you were using the remote Java API and constructing a JmsClientImpl to enable remote cache invalidation through JMS, you'll notice the constructor has changed: it takes a new parameter clientID (the JMS client ID, which is a string of your choice, but should be different for each client), and the topicConnectionFactory and queueConnectionFactory parameters have merged into just one connectionFactory argument (since we're now using JMS 1.1 APIs internally, as a result of the switch to ActiveMQ).

2.10.3 Upgrading

Important: these are instructions for upgrading from Daisy 1.5-M1. To upgrade from older releases, e.g. Daisy 1.4, please follow the aggregated instructions for upgrading from 1.4 to 1.5-final, which can be found here.

2.10.3.1 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.10.3.2 Switching from OpenJMS to ActiveMQ

2.10.3.2.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:

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

2.10.3.2.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.10.3.2.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.10.3.3 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.10.3.4 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.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.10.3.5 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.

2.10.4 Start repository server

At this point, start the repository server, as this is needed for the remainder of the upgrade.

It is not needed anymore to start OpenJMS.

2.10.5 Create wikidata directory

From now on, configurations parameters, skins, doctype XSLs, the book publication types and book store, the wiki log files, in short all 'wiki-instance-specific' stuff is stored in a separate "wikidata directory" (not to be confused with the daisydata directory, which performs a similar role but then for the repository server).

We will now create such a directory and copy your existing configuration to it.

To create the wikidata directory, go to <DAISY_HOME>/install and execute:

daisy-wikidata-init

The program will ask you for a location for this directory. Just choose some location for this, for example put it next to (but not inside) the repository daisydata directory.

The program will also ask for the location of the repository daisydata directory, as it will take some configuration values from there (internal & jms user password) and put them in the wiki config.

It will also try to create the registrar user, but since you're doing an upgrade that user will already exist so it will simply skip that. However, you will need to enter the password for the registrar user. This can be found in <OLD_DAISY_HOME>/daisywiki/webapp/WEB-INF/cocoon.xconf, and look there for something like:

<registrarUser login="registrar" password="b6f84c35249a08d11ad6fa8279e2f9"/>

Just copy-and-paste that password to the input prompt.

Once the daisy-wikidata-init script has ended, we can copy over the remaining things:

If you made any configuration changes to the repository manager, JMS client or registrar component which were previously in the cocoon.xconf, then you can now find these in <wikidata dir>/daisy.xconf.

2.10.5.1 Updating wrapper configuration for the Daisy Wiki

Similarly as in the previous section, the Daisy Wiki needs the following additional parameter in dsy_wiki_wrapper.conf (see also the full script):

wrapper.java.additional.7=-Ddaisywiki.data=%DAISYWIKI_DATADIR%

The DAISYWIKI_DATADIR environment variable has to be declared in the shell script (dsy_wiki.sh or equivalent):

#! /bin/sh

DAISY_HOME=/home/daisy/daisy ; export DAISY_HOME
JETTY_HOME=$DAISY_HOME/daisywiki/jetty ; export JETTY_HOME
DAISYWIKI_DATADIR=/path/to/your/daisywikidata ; export DAISYWIKI_DATADIR

[.....]

2.10.6 Start the Daisy Wiki

Now you can also start the Daisy Wiki.

2.10.7 After-upgrade notes

2.10.7.1 OpenJMS cleanup

Since OpenJMS is not used anymore, some cleanup you might want to to:

2.10.7.2 ActiveMQ authentication

With the procedure we followed above, ActiveMQ still uses default passwords. If the ActiveMQ port is publicly accessible, it is of course very much recommended to change these. Here is how. The password needs to be changed in the following locations:

Original setting:

In  this file:
<datadir>/conf/users.properties

in this line:
admin=jmsadmin

For the connection made by the Repository Server:

In this file:
<datadir>/conf/myconfig.xml

in this line:
<credentials username="admin" password="jmsadmin"/>

For the connection made by the Daisy Wiki:

In this file:
<wikidata dir>/daisy.xconf

in this line:
<credentials username="admin" password="jmsadmin"/>

After making these changes, stop both the Daisy Wiki and the Repository Server, and then restart them (first the repository, then the wiki).

2.11 1.5-M2 to 1.5 final upgrade

2.11.1 Changes

Only some small changes and bug fixes in this release:

2.11.2 Upgrading

Nothing special needs to be done to upgrade from Daisy 1.5-M2 to this release.

Just stop the repository and wiki servers, extract the new release, adjust DAISY_HOME or move the old Daisy install out of the way, and restart the servers.

2.12 1.4 to 1.5 upgrade

Daisy 1.5 was released on August 16, 2006.

Read this document carefully, especially the upgrading instructions. Take your time to do the upgrade. This release contains various changes that will make future updates a lot easier.

2.12.1 Changes

Some important changes that affect deployment or compatibility: READ THIS SECTION

Other changes:

To also see bug fixes or some non-functional changes, check the change lists for each individual 1.5 Milestone release.

2.12.2 Compatibility

2.12.2.1 Document type specific stylesheet

There is small difference in the output of the publisher requests which influences the document type specific stylesheets. Don't worry, it is a very minor change, depending on how your stylesheets are written they might even require no change at all.

Where the input previously contained this element hierarchy:

document > d:document

it has now become:

document > p:publisherResponse > d:document

Where "p:" is the publisher namespace, thus bound as:

xmlns:p="http://outerx.org/daisy/1.0#publisher"

If you want to have stylesheets that work with both releases, you can write them so that they first test for the presence of document/d:document and if not available use document/p:publisherResponse/d:document

2.12.2.2 Custom styling: attributes on links

The links in document content were previously annotated with the attributes daisyDocumentName, daisyFileName and daisyNavigationPath. These have been removed in favour of a more powerful system, as explained in this mail.

If you have custom document type specific XSLs or book publication types, you might want to do a search for @daisyDocumentName used in XPath expressions, and replace it by p:linkInfo/@documentName, the p prefix should be declared as:

xmlns:p="http://outerx.org/daisy/1.0#publisher"

2.12.2.3 Auto-redirecting between sites

The Daisy Wiki now has the ability to automatically redirect to another site if a document is better suited to be displayed over there. This is enabled by default, and can be disabled by adding the following element in the siteconf.xml of each site for which you want to disable this:

<siteSwitching mode="stay"/>

2.12.2.4 Field type in HTTP interface

A small change has been done to the field type XML. If you have any programs making direct use of the HTTP interface, you'll need to adjust them.

Where you previously had a <d:selectionList> element for specifying a static selection list, the <d:selectionList> element now contains an extra <d:staticSelectionList> element which then contains the elements previously contained in <d:selectionList>. This change was done to allow for alternative selection list implementations.

2.12.2.5 Publisher XML Beans generated classes

Applies when using custom publisher requests build up via the Java objects (instead of written in XML).

The structure of the XML Schema for the publisher requests has changed a little bit, which has caused some small changes in the nesting of the classes generated by XMLBeans for this XML Schema. Adjusting your code for this is straightforward.

2.12.2.6 Skins

[todo: add helpful notes here on updating custom skins based on the old default skin]

2.12.2.7 Custom book publication types

If you made custom book publication types or document type specific XSLs for use in books, they might need some small changes due to the introduction of the wikidata directory.

In the query-styling.xsl of the publication type, if you want to import the default query styling XSL, the include should now be:

<xsl:include href="wikidata:books/publicationtypes/common/default-query-styling.xsl"/>

If in the custom document type specific XSL you included the default book-document-to-html.xsl file, the import should now be:

<xsl:include href="wikidata:books/publicationtypes/common/book-document-to-html.xsl"/>

2.12.2.8 Databases

MySQL 4.0 is not supported anymore. You might still be able to get it to work, but it wasn't worth the effort anymore for us to support it in the default configuration.

2.12.2.9 JmsClient API

If you were using the remote Java API and constructing a JmsClientImpl to enable remote cache invalidation through JMS, you'll notice the constructor has changed: it takes a new parameter clientID (the JMS client ID, which is a string of your choice, but should be different for each client), and the topicConnectionFactory and queueConnectionFactory parameters have merged into just one connectionFactory argument (since we're now using JMS 1.1 APIs internally, as a result of the switch to ActiveMQ).

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:

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.

2.12.4 Start repository server

At this point, start the repository server, as this is needed for the remainder of the upgrade.

It is not needed anymore to start OpenJMS.

2.12.5 Upgrade Daisy Wiki schema

Run the daisy-wiki-init script to update the Daisy Wiki schema types:

cd <DAISY_HOME>/install
daisy-wiki-init

2.12.6 Create wikidata directory

From now on, configurations parameters, skins, doctype XSLs, the book publication types and book store, the wiki log files, in short all 'wiki-instance-specific' stuff is stored in a separate "wikidata directory" (not to be confused with the daisydata directory, which performs a similar role but for the repository server).

We will now create such a directory and copy your existing configuration to it.

To create the wikidata directory, go to <DAISY_HOME>/install and execute:

daisy-wikidata-init

The program will ask you for a location for this directory. Just choose some location for this, for example put it next to (but not inside) the repository daisydata directory.

The program will also ask for the location of the repository daisydata directory, as it will take some configuration values from there (internal & jms user password) and put them in the wiki config.

It will also try to create the registrar user, but since you're doing an upgrade that user will already exist so it will simply skip that. However, you will need to enter the password for the registrar user. This can be found in <OLD_DAISY_HOME>/daisywiki/webapp/WEB-INF/cocoon.xconf, and look there for something like:

<registrarUser login="registrar" password="b6f84c35249a08d11ad6fa8279e2f9"/>

Just copy-and-paste that password to the input prompt.

Once the daisy-wikidata-init script has ended, we can copy over the remaining things:

If you made any configuration changes to the repository manager, JMS client or registrar component which were previously in the cocoon.xconf, then you can now find these in <wikidata dir>/daisy.xconf.

2.12.6.1 Updating wrapper configuration for the Daisy Wiki

If you are using the service wrapper script to launch the Daisy Wiki, you need to adjust the dsy_wiki_wrapper.conf to include the following parameter (see also the full script):

wrapper.java.additional.7=-Ddaisywiki.data=%DAISYWIKI_DATADIR%

Daisy now ships with Jetty 5, which means that the classpath definition in the dsy_wiki_wrapper.conf needs to be updated. Just replace the existing wrapper.java.classpath entries with the new ones found in the updated dsy_wiki_wrapper.conf file.

The DAISYWIKI_DATADIR environment variable has to be declared in the shell script (dsy_wiki.sh or equivalent):

#! /bin/sh

DAISY_HOME=/home/daisy/daisy ; export DAISY_HOME
JETTY_HOME=$DAISY_HOME/daisywiki/jetty ; export JETTY_HOME
DAISYWIKI_DATADIR=/path/to/your/daisywikidata ; export DAISYWIKI_DATADIR

[.....]

2.12.7 Start the Daisy Wiki

Now you can also start the Daisy Wiki.

2.12.8 After-upgrade notes

2.12.8.1 [optional] Image thumbnail generation

Daisy 1.5 can generate image thumbnails and extract their width and height to store them in fields of the Image document type. If you want to do this for all your current images, you can do so by running a document task. For this, first make sure you're logged in as Administrator, then go to the Document Tasks screen (the link is in the user menu) and create a new document task. Select the documents using the query:

select name where documentType = 'Image'

You might first want to try this with one document to see if everything is OK.

Then go to the next screen, and use the following script:

var document = repository.getDocument(variantKey, true);
document.setField("ImageWidth", new java.lang.Long(0));
document.save();

This script "touches" the document by setting a field to a dummy value. Otherwise, the document wouldn't be changed and no save will be performed.

2.12.8.2 OpenJMS cleanup

Since OpenJMS is not used anymore, some cleanup you might want to to:

2.12.8.3 ActiveMQ authentication

With the procedure we followed above, ActiveMQ still uses default passwords. If the ActiveMQ port is publicly accessible, it is of course very much recommended to change these. Here is how. The password needs to be changed in the following locations:

Original setting:

In  this file:
<datadir>/conf/users.properties

in this line:
admin=jmsadmin

For the connection made by the Repository Server:

In this file:
<datadir>/conf/myconfig.xml

in this line:
<credentials username="admin" password="jmsadmin"/>

For the connection made by the Daisy Wiki:

In this file:
<wikidata dir>/daisy.xconf

in this line:
<credentials username="admin" password="jmsadmin"/>

After making these changes, stop both the Daisy Wiki and the Repository Server, and then restart them (first the repository, then the wiki).

2.12.8.4 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 u