Daisy documentation
 PreviousHomeNext 
2.9 1.5 to 2.0 upgradeBook Index2.9.3 Installing the daisy wrapper scripts

2.9.2 Upgrading daisy repository and wiki

These instructions will guide you through upgrading an existing Daisy 1.5 or 1.5.1 install to Daisy 2.0.1.

Carefully follow the complete update instructions, don't skip things, then the upgrading should be painless. Take your time to do the upgrade.

Important: these are instructions for upgrading from Daisy 1.5 or 1.5.1. To upgrade from older releases, e.g. Daisy 1.4, you first need to follow the instruction to upgrade to 1.5, and then these instructions.

If you get stuck during the upgrade (e.g. there's a part of the instructions you don't understand), you can always ask for help on the Daisy mailing list. If you'd like someone else to do the upgrade for you, professional services are available.

2.9.2.1 Daisy installation review

In case you have not been much involved with Daisy since its installation, or maybe did not do the original installation yourself, it is helpful to identify the main parts involved. The following picture illustrates these.

There is the application directory, which is simply the extracted Daisy download, and doesn't contain any data (to be safe don't remove it yet though).

Next to this, there are 3 locations where data (and configuration) is stored: the relational database (MySQL), the repository data directory, and the wiki data directory. The Daisy repository and the Daisy Wiki are two independent applications, therefore each has its own data directory.

The text between the angle brackets (< and >) is the way we will refer to these directories further on in this document. Note that <DAISY_HOME> is the new extracted download (see later on), not the old one.

2.9.2.2 While you still have your existing Daisy running

2.9.2.2.1 Make a "workflow" user

In order to use the new workflow functionality in Daisy 2, you need to create a special workflow user. This is done as follows:

Be sure to remember or write down the selected user login and password.

2.9.2.2.2 Make backups

Making a backup is very important, you might loose all your data if you don't.

You can use the backup tool for this.

Alternatively:

2.9.2.3 Stop your existing Daisy

Stop your existing Daisy, both the repository server and the Daisy Wiki.

2.9.2.4 Check you are using Java 1.5

Daisy 2 requires at least Java 1.5. You can check you are using Java 1.5 by executing:

[Windows]
%JAVA_HOME%\bin\java -version

[Unix]
$JAVA_HOME/bin/java -version

In case you would still be using Java 1.4, install Java 1.5 or 1.6 first. Make sure the JAVA_HOME environment variable afterwards points to the new Java installation, e.g. by executing the above command again.

At the time of this writing, the current 1.5 version is build 1.5.0_11. In case you would lag much behind that revision, now might be a good time to update.

2.9.2.5 Download and extract Daisy 2.0.1

Download Daisy 2.0.1 from the distribution area (Sourceforge). For Windows, download the zip or autoextract.exe (not the installer!). For Unix-based systems, the .tar.gz is recommended. The difference is that the .zip contains text files with DOS line endings, while the .tar.gz contains text files with unix line endings. When using non-Linux unixes such as Solaris, be sure to use GNU tar to extract the archive.

Extract the download at a location of your choice. Extract it next to your existing Daisy installation, do not copy it over your existing installation.

If you upgrade an installation that was obtained by using the windows installer, please be aware that you should keep your existing top level Daisy installation directory (usually: C:\Program Files\Daisy-1.5.1) and replace the directory daisyhome inside this directory only . So extract your downloaded archive file to something like C:\Program Files\Daisy-1.5.1\daisyhome-2.0  and point your DAISY_HOME variable to that directory. Do not discard the top level directory of your daisy installation! If you want to rename your top level directory to C:\Program Files\Daisy-2.0.1 please make sure to adjust all Daisy related environment variables set by the installer. You may also adjust the various shortcuts used in Programs - Daisy 1.5 to invoke Daisy related activities.

2.9.2.6 Update environment variables

Make sure the DAISY_HOME environment variable points to the just-extracted Daisy 2.0.1 directory.

How this is done depends a bit on your system and personal preferences:

2.9.2.7 Decide upon a repository namespace

Daisy 2 uses namespaced document IDs, meaning that the simple numeric document IDs are now suffixed with a namespace string. Namespaced document IDs avoid ID conflicts when exchanging documents with other Daisy repositories (that have different namespaces).

You need to decide what namespace to use. If you don't care, you can use the default "DSY".

Here are some rules and recommendations to help you choose a namespace:

We'll need the namespace in the next step.

2.9.2.8 Update myconfig.xml file

Open the myconfig.xml file in a text editor. This file can be found at:

<daisydata dir>/conf/myconfig.xml

As child of the root element, add the following somewhere (the order does not matter, you can e.g. add it at the end before the closing </targets> tag):

  <target path="/daisy/repository/repository-manager">
    <configuration>
      <!-- Namespace of this repository server. Should preferably be different
           from other repository servers you control, at least to be able
           to do export/import between them.
           The namespace name should conform to the regexp [a-zA-Z0-9_]{1,200}
           -->
      <namespace>DSY</namespace>
    </configuration>
  </target>

  <target path="/daisy/extensions/workflow/workflow-manager">
    <configuration>
      <jbpm>
        <hibernate>
          <properties>
            <entry key="hibernate.dialect">org.hibernate.dialect.MySQLInnoDBDialect</entry>
          </properties>
        </hibernate>
      </jbpm>

      <workflowUser login="workflow" password="defaultpwd"/>

      <!-- Where to look for workflow mail templates -->
      <mailTemplates>
        <!-- built-in templates (loaded from the classpath) -->
        <location>resource:/org/outerj/daisy/workflow/serverimpl/mailtemplates/</location>
        <!-- custom templates in the datadir -->
        <location>${daisy.datadir}/templates/workflow/</location>
      </mailTemplates>
      <taskURL>http://localhost:8888/daisy/${siteName}/workflow/performTask?taskId=${taskId}</taskURL>
   </configuration>
  </target>

Change the following values, marked as bold in the above listing:

Also in the myconfig.xml, add the jms.dispatchAsync parameter to the JMS provider URL (the whole URL should be on one line, it is split in multiple lines here for readability):

<target path="/daisy/jmsclient/jmsclient">
  <configuration>
    <jmsConnection>
      <clientId>daisy-repository</clientId>
      <credentials password="..." username="admin"/>
      <initialContext>
        <property name="java.naming.provider.url"
          value="vm://DaisyJMS?brokerConfig=${double-url-encode:xbean:${file-to-uri:${daisy.datadir}
                 /conf/activemq-conf.xml}}&amp;jms.dispatchAsync=true"/>
        <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>
</target>

If you upgrade from an installation that was obtained by using the windows installer you also have to apply the change of myconfig.xml described below. If you did not use the windows installer, you may skip this section and directly jump to "Update the ActiveMQ configuration".

Look for the following element inside your myconfig.xml

<target path="/daisy/driverregistrar/driverregistrar">
  <configuration>
    <drivers>
      <driver>
        <classname>com.mysql.jdbc.Driver</classname>
        <classpath>C:/Program Files/Daisy-1.5.1/daisyhome/lib/mysql/jars/mysql-connector-java-3.1.12-bin.jar</classpath>
      </driver>
    </drivers>
  </configuration>
</target>

Erroneously, the classpath was hardcoded inside the configuration file. Replace the classpath element with the following line:

<classpath>${daisy.home}/lib/mysql/jars/mysql-connector-java-3.1.12-bin.jar</classpath>

2.9.2.9 Update the ActiveMQ configuration

Open the file <daisydata dir>/conf/activemq-conf.xml in a text editor. At the beginning of the file you will find this:

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://activemq.org/config/1.0">
  <broker useJmx="true" brokerName="DaisyJMS" useShutdownHook="false">
    <plugins>
...

Move the XML namespace declaration from the beans element to the broker element. Also add the dataDirectory attribute.

<?xml version="1.0" encoding="UTF-8"?>
<beans>
  <broker useJmx="true" brokerName="DaisyJMS" useShutdownHook="false"
          dataDirectory="file:${daisy.datadir}/activemq-data"
          xmlns="http://activemq.org/config/1.0">
    <plugins>
...

In case you're wondering about the dataDirectory attribute: ActiveMQ is configured to only store data in the database, but it still insists on having this data directory.

Also in the activemq-conf.xml file, add the element memoryManager as child of the broker element, as shown here:

<beans>

  <broker useJmx="true" brokerName="DaisyJMS" useShutdownHook="false" xmlns="http://activemq.org/config/1.0"
      dataDirectory="file:${daisy.datadir}/activemq-data">

    <memoryManager>
      <usageManager id="memory-manager" limit="0 MB"/>
    </memoryManager>
...

Remove the poolPreparedStatements property from the datasource config:

  <bean id="dataSource" class="org.apache.commons.dbcp.BasicDataSource" destroy-method="close">    
    <property name="url" value="jdbc:mysql://localhost/activemq?..."/>
    <property name="username" value="activemq"/>
    <property name="password" value="activemq"/>
    <property name="defaultTransactionIsolation" value="2"/>
    <property name="poolPreparedStatements" value="true"/>
  </bean>

2.9.2.10 Updating the repository SQL database

If you have not selected DSY as the namespace, then first open the database upgrade script in a text editor:

<DAISY_HOME>/misc/daisy-1_5-to-2_0_M1.sql

Near the top of that file you'll see the following line:

set @daisynamespace = 'DSY';

Change DSY with the namespace you have selected. This should be exactly the same value as configured in the myconfig.xml file.

Now execute the database upgrade script:

cd <DAISY_HOME>/misc
mysql -Ddaisyrepository -udaisy -ppassword < daisy-1_5-to-2_0_M1.sql

On many MySQL installations you can use "root" as user (thus specify -uroot instead of -udaisy) without password, thus without the -p option.

The version number 2_0_M1 in the sql script name might be confusing, but is correct.

2.9.2.11 Daisy Wiki tmp dir

Create an empty directory called tmp in the wikidata directory:

[Windows]
cd <wikidata dir>
md tmp

[Linux]
cd <wikidata dir>
mkdir tmp

2.9.2.12 Updating the daisy.xconf file

Open the daisy.xconf file, located at:

<wikidata dir>/daisy.xconf
2.9.2.12.1 Workflow

Add the following tag inside the <extensions> element:

<extension name="WorkflowManager"
           class="org.outerj.daisy.workflow.clientimpl.RemoteWorkflowManagerProvider"/>
2.9.2.12.2 JMS

To make sure JMS events are captured correctly by the Wiki the JMS Client component must be moved to the top of the configuration file. Find the element with role attribute org.outerj.daisy.jms.JmsClient. It starts with these lines.

<component
    class="org.outerj.daisy.jms.impl.JmsClientImpl"
    role="org.outerj.daisy.jms.JmsClient"
    logger="daisy.jmsclient">
    <jmsConnection>

    [...]

</component>

Move the whole component element (thus up to the closing </component> tag) to the top of the file as the first child of the cocoon element. This is what the result should look like.

<cocoon>
  <component
    class="org.outerj.daisy.jms.impl.JmsClientImpl"
    role="org.outerj.daisy.jms.JmsClient"
    logger="daisy.jmsclient">
    <jmsConnection>

    [...]

  </component>

  [...]
</cocoon>

To assure the JMS Client is available, it is (optionally) possible to add a configuration option to the RemoteRepositoryManager, like this:

<component
    class="org.outerj.daisy.repository.clientimpl.RemoteRepositoryManager"
    role="daisy-repository-manager"
    logger="daisy.repositorymanager" >
  <repository-server-base-url>http://localhost:9263</repository-server-base-url>
  <jmsTopic>daisy</jmsTopic>
  <!-- Lets RemoteRepositoryManager fail in absense of JMS client -->
  <requireJms>true</requireJms>
  ...

2.9.2.13 Adding "daisy/" to URL path

Daisy 2 by default does not have "daisy/" at the start of the URL anymore. When upgrading an existing installation, you'll likely want to re-add the "daisy/" to avoid breaking existing URLs (unless of course you previously modified Daisy to remove the "daisy/").

This is done as follows.

Check if you have the following file:

<wikidata dir>/jetty-daisywiki.xml

If not, create it now by copying the default:

[Windows]
copy %DAISY_HOME%\daisywiki\conf\jetty-daisywiki.xml <wikidata dir>\jetty-daisywiki.xml

[Linux]
cp $DAISY_HOME/daisywiki/conf/jetty-daisywiki.xml <wikidata dir>/jetty-daisywiki.xml

Next, edit this file (thus <wikidata dir>/jetty-daisywiki.xml), look for this part:

  <Call name="addWebApplication">
    <Arg>/</Arg>
    <Arg><SystemProperty name="daisywiki.home"/>/webapp</Arg>
    <Set name="defaultsDescriptor"><SystemProperty name="daisywiki.home"/>/conf/jetty-daisywiki-defaults.xml</Set>
  </Call>

and change the value of the first <Arg> as indicated in bold below:

  <Call name="addWebApplication">
    <Arg>daisy</Arg>
    <Arg><SystemProperty name="daisywiki.home"/>/webapp</Arg>
    <Set name="defaultsDescriptor"><SystemProperty name="daisywiki.home"/>/conf/jetty-daisywiki-defaults.xml</Set>
  </Call>

2.9.2.14 Empty JMS queues

The JMS queues should be empty, i.e. all messages should be processed by the durable subscribers, which are the fulltext-indexer and the email notifier. Since JMS messages are normally processed very quickly, the queues are likely empty. However, we've noticed problems with the JMS system (ActiveMQ) in Daisy 1.5 leaving messages in the database. Therefore, just to be sure we'll clean out the JMS event tables as follows:

mysql -Dactivemq -uactivemq -ppassword

[on the MySQL prompt]
delete from ACTIVEMQ_MSGS;
delete from ACTIVEMQ_ACKS;

[exit mysql client]

mysql -Ddaisyrepository -udaisy -ppassword

[on the MySQL prompt]
delete from events;

On many MySQL installations you can use "root" as user (thus specify -uroot instead of -udaisy) without password, thus without the -p option.

2.9.2.15 Remove full text index files

Due to the change to namespaced document IDs, the fulltext index will need to be rebuild. Therefore, we'll now do the first step: drop the current index. You can do this by removing all files in the following directory (but not the directory itself!):

<daisy data dir>/indexstore

This can be done like this:

[Windows]
cd <daisydata dir>\indexstore
del *.* 

[Unix]
cd <daisydata dir>/indexstore
rm -f *

2.9.2.16 Start the servers

Make sure the DAISY_HOME environment variable points to the new Daisy 2.0.1 directory (you might want to rename the old directory to avoid it is still used by accident).

Then start the repository server:

[Windows]
cd <DAISY_HOME>\repository-server\bin
daisy-repository-server <daisydata dir>

[Unix]
cd <DAISY_HOME>/repository-server/bin
./daisy-repository-server <daisydata dir>

Starting the repository server the first time will take a bit longer than usual, since the workflow database schema is created upon first start. Once finished, the message "Daisy repository server started" will be printed on the screen.

Once the repository server is started, start the Daisy Wiki:

[Windows]
cd <DAISY_HOME>\daisywiki\bin
daisy-wiki <wikidata dir>

[Unix]
cd <DAISY_HOME>/daisywiki/bin
./daisy-wiki <wikidata dir>

2.9.2.17 Rebuild full text indexes

Triggering the rebuild of the fulltext index is done through the JMX console.

First, you need to know the username and password to access the JMX console. You can look this up in the following file:

<daisydata dir>/conf/myconfig.xml

In that file, look for this element:

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

Note the values of the username and password attributes.

Now use your webbrowser to go to the following URL:

http://localhost:9264/

(if needed, replace localhost with the name of the server on which the Daisy repository is running)

You will be prompted to login, use the username and password we just looked up.

In the JMX console, click on the following link:

Daisy:name=FullTextIndexUpdater

On the next screen, look for the line with "reIndexAllDocuments", and press the "Invoke" button that is located on the same line.

If you have a lot of documents in the repository, see the instructions in the documentation for how to follow up the re-indexing progress.

2.9.2.18 Update the default repository schema

It is recommended to update the default Daisy Wiki schema (the default document, part and field types). In this release, there are no essential changes except for updated translations, and the auto-assigned fields and parts of the Image document type are now marked as non-editable.

The schema can be updated by running the daisy-wiki-init script:

[Windows]
cd <DAISY_HOME>\install
daisy-wiki-init

[Linux]
cd <DAISY_HOME>/install
./daisy-wiki-init

2.9.2.19 Upgrade document IDs in existing documents to namespaced format

We have written a tool which converts the document IDs present in document content (e.g. href attributes of links, but also document IDs in the navigation and book definitions) to the new document ID format.

Strictly speaking, doing this update is optional, as the old ID format is still supported (IDs without namespace are presumed to be in the repository's own namespace).

Doing this update is however required if you want to make use of export/import. So just to be ready for that, and to 'go with the flow', it is very strongly recommended to do this update.

To perform the update, execute the following command:

Read this section to the end before executing this command.

<DAISY_HOME>/bin/daisy-docid-convertor
     -l http://localhost:9263
     -u testuser
     -p testuser
     -c <DAISY_HOME>/daisywiki/webapp/daisy/resources/conf/htmlcleaner.xml
  > convertlog.txt

(the whole command should be entered on one line)

in which you of course make some changes to match your setup:

Replace <DAISY_HOME> with the path to your Daisy installation.

The -l parameter indicates the URL of the HTTP interface of the repository server. If it is running on the same machine as this upgrade tool, the presented default is OK. If not, adjust it.

The -u and -p parameters specify the user to be used to connect to the repository server. This should by preference be a user with the Administrator role (it doesn't have to be the user's default role), so that all documents are accessible and writable.

Note that changes to documents are of course saved as new versions, so this user will then appear in the version history of the documents. If a document does not require any updates, it will not be saved and hence no new version will be created.

The tool will print out a log of everything it is doing. If it fails on some document it will print the full exception information and go on to the following document. Therefore it is recommended to capture the output of the tool to some file, which is exactly what is done with the "> convertlog.txt" part of the command. When the tool finishes, it also prints how much documents were processed successfully, and how much failed.

The tool can be re-run as often as needed (e.g. if it is interrupted for some reason).

Please note that these updates will also cause e-mail notifications to be sent, if you are using that feature. It is however possible to disable this. In order to do this, log in to the JMX console, in the same way as described in the previous section for updating the fulltext index. In the JMX console, choose the link Daisy:name=EmailNotifier, on the next screen look for the line "addIgnoreUser".  Enter the name of the user passed to the daisy-docid-convertor tool (e.g.. testuser) in the textbox  and press the invoke button. From now on, for updates caused by that user, no email notifications will be send. Afterwards you can disable this again with the removeIgnoreUser option. This setting will also be forgotten after restarting the repository server.

 PreviousHomeNext 
2.9 1.5 to 2.0 upgrade2.9.3 Installing the daisy wrapper scripts