INSTALLATION

These instructions only apply to Daisy 1.2. For Daisy 1.3, see here.

Downloading Daisy

Packaged versions of Daisy, which include Cocoon, OpenJMS and Merlin can be found in the distribution area. Daisy also requires a recent installation of the MySQL database server (>= version 4.0.20). Daisy has been tested to install on Linux (Suse and Debian), MacOSX and Windows XP. The latest version is 1.2.0.

Sources can be obtained through SVN, instructions for setting up a development environment with Daisy (which is slightly different from using the packaged version) are included in the README.txt's in the source tree. For anonymous, read-only access to Daisy SVN, use the following command:

svn co http://svn.cocoondev.org/repos/daisy/trunk/daisy

This will give the latest development code (the "trunk"). To get the source code of a specific release, use a command like this:

svn co http://svn.cocoondev.org/repos/daisy/tags/RELEASE_1_2_0 daisy

No authentication is required for anonymous access. If you're behind a (transparant) proxy, you might want to verify whether your proxy supports the extended HTTP WebDAV methods. Also, consider subscribing to the Daisy mailing list to ask questions and talk with fellow Daisy users and developers.

Installation Overview

Daisy is a multi-tier application, consisting of a repository server and a publication layer. Next to those, a JMS server (OpenJMS) and a database server (MySQL) are required. All together, this means four 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 you'll still need to configure yourself as explained in these installation instructions. 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.

Daisy Deployment
Click to enlarge

Platform Requirements

The installation instructions in this document have been tested on Windows and Linux, but other platforms (other unixes, MacOS X) are likely to work too.

Memory Requirements

By default, the Daisy Wiki and Daisy Repository Server are started with a maximum heap size of 128 MB each, OpenJMS uses the JVM default (64 MB). 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 consumed, that will depend on usage intensity.

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.

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

Daisy was originally designed to work with MySQL/InnoDB. With the 1.2 release, we abstracted any Database specific stuff (mostly the installation procedure and setting the correct transaction isolation levels) and added PostgreSQL support. However, currently these installation instructions only contain information on using MySQL, so if you want to use PostgreSQL instead you need to figure out the PostgreSQL-equivalents yourself. If unsure about what database to use, we recommend MySQL since that's the one that has got the most testing by us.

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.

Installing a Java Virtual Machine

Daisy requires the Java SDK 1.4.2. Java 1.5 is not yet supported (it does not work).

You can download the Java SDK from here on the Sun site. 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 (ie, 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"

Installing JAI (Java Advanced Imaging) -- optional

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

Installing MySQL

Daisy requires MySQL version 4.0.20 or a newer version from the 4.0.x series ( we're not making this number up: there have been various bug fixes or improvements between versions 4.0.0 and 4.0.20 on which Daisy depends), or MySQL version 4.1.7 or a newer version from the 4.1.x series.. The MySQL needs support for InnoDB tables (which is included by default).

The 4.1 version of MySQL has the advantage that it supports UTF-8. However, this is not activated by default, see the MySQL documentation for how you can switch your MySQL server to use UTF-8.

MySQL can be obtained from mysql.com. Install it now, and start it.

Creating MySQL databases and users

MySQL is used by both the Daisy Repository Server and OpenJMS. Therefore, we're 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 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 OpenJMS and the Daisy Repository Server, you only need the @localhost entries.

CREATE DATABASE daisyrepository;
GRANT ALL ON daisyrepository.* TO daisy@"%" IDENTIFIED BY "daisy";
GRANT ALL ON daisyrepository.* TO daisy@localhost IDENTIFIED BY "daisy";
CREATE DATABASE openjms;
GRANT ALL ON openjms.* TO openjms@"%" IDENTIFIED BY "openjms";
GRANT ALL ON openjms.* TO openjms@localhost IDENTIFIED BY "openjms";

Extract the Daisy download

Extract the Daisy download in some location by using:

tar xvzf daisy-<version>.tar.gz

On Windows, you can use a tool like WinZip to extract the download. On non-Linux unixes, use the GNU tar version if you experience problems extracting.

Make sure that wherever you extract the download, none of the parent directories contains spaces in their names. For example, on Windows, do not extract Daisy inside your c:\Program Files directory. [There also appear to be problems with Java itself being installed in a directory with spaces, still need to check and fix this, patches welcome.]

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.

OpenJMS configuration

Set OPENJMS_HOME

Define an environment variable OPENJMS_HOME pointing to the OpenJMS installation directory, which is DAISY_HOME/openjms.

Put JDBC driver in CLASSPATH

Edit the file OPENJMS_HOME/bin/setenv.sh (Unix) or setenv.bat (Windows). Close to the top of the file you will see the following:

(in the setenv.sh)
# Configure the JDBC driver
#
#    CLASSPATH=<insert path to JDBC driver here>

(in the setenv.bat)
rem Configure the JDBC driver
rem
rem    set CLASSPATH=<insert path to JDBC driver here>

Uncomment the line to set the CLASSPATH variable and change its value to point to the location of the MySQL JDBC driver. This is included in the Daisy download at:

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

(change <DAISY_HOME> by the actual location of the Daisy directory)

Adjust openjms.xml

Edit the file OPENJMS_HOME/config/openjms.xml.

Replace the existing <DatabaseConfiguration> element with the one below. Be sure to adjust the password if you chose another one.

  <DatabaseConfiguration>
    <RdbmsDatabaseConfiguration
      driver="com.mysql.jdbc.Driver"
      url="jdbc:mysql://localhost/openjms" 
      user="openjms" 
      password="openjms"
      maxActive="10"
      maxIdle="5"
      evictionInterval="3600"
      testQuery="select current_date" />
  </DatabaseConfiguration>

Replace the existing <AdministeredDestinations> element with the one below.

  <AdministeredDestinations>
    <AdministeredTopic name="daisy">
      <Subscriber name="fullTextIndexer"/>
      <Subscriber name="emailNotifier"/>
    </AdministeredTopic>
    <AdministeredQueue name="fullTextIndexerJobs"/>
  </AdministeredDestinations>

Add the following element (after the AdministeredDestinations):

  <SecurityConfiguration securityEnabled="true"/>

In the openjms.xml, you will also see the <Users> element, which defines a user called "admin" with password "openjms". You can adjust these if you want.

Create the OpenJMS database tables

Now open a command prompt and go to the directory OPENJMS_HOME/bin, and execute the following:

For Linux:
dbtool.sh -create -config $OPENJMS_HOME/config/openjms.xml
For Windows:
dbtool.bat -create -config %OPENJMS_HOME%\config\openjms.xml

Start OpenJMS

Open a command prompt, go to the directory OPENJMS_HOME/bin, and execute:

For Linux:
startup.sh
For Windows:
startup.bat

Initialiasing and configuring the Daisy Repository

We will now execute the daisy-repository-init installation program which will initialiase the repository database and create a daisy data directory containing pre-configured configuration files and directories for storage of blobs, full text indexes and log files.

Open a command prompt, make sure DAISY_HOME is set, and go to DAISY_HOME/install. Then execute:

daisy-repository-init

You are first asked for some database parameters: database type, URL, database name, user and password. If you left all these to their defaults, you can simply press enter.

Then it will ask for an initial repository user name and password. You can create a user for yourself here. Remember these values of course -- you'll need them further on.

Then it will ask for a password for the "internal" user. The internal user is a user Daisy needs internally for various components that need to connect to the repository. A random generated password will be proposed. Since this password only needs to be entered in configuration files, it doesn't matter that it is complex.

Then you're asked if the database needs to be dropped before recreating. Answer yes (it is still empty anyway). Then answer yes again to confirm to start the database creation. This will take a few seconds.

Now you're asked to create a daisy data directory. Answer yes.

Enter the name (= full path) of the directory to be created.

The installation program ends.

If you look at the created data directory, it has the following content:

datadir
  + blobstore  (empty directory)
  + indexstore (empty directory)
  + logs       (empty directory)
  + conf
      + myconfig.xml
      + logkit.xconf

The myconfig.xml is the configuration file for the Daisy Repository Server. It is already adjusted to contain the database parameters you entered during the execution of daisy-repository-init, the locations of the blobstore and indexstore directories, and the internal user password.

Things you still need to manually adjust in the myconfig.xml:

  • If you chose a different user and/or password during the OpenJMS installation (= the user specified in the openjms.xml file), look for the following element: <credentials username="admin" password="openjms"/> and adjust.
  • If you want Daisy to be able to send out notification mails, you need to provide an SMTP server. Look for the following element: <smtpHost> _lazy_admin_.com</smtpHost> and adjust.

The logkit.xml file contains the logging configuration. By default log files will come in the datadir/logs directory and roll over daily.

Starting the Daisy Repository Server

Open a command prompt, make sure DAISY_HOME is set. Now go to 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 startup can take a few seconds (like 10 or so), though nothing special is printed to the screen to indicate it is completely started.

Don't forget that OpenJMS and MySQL still need to be running.

Initialising the Daisy Wiki

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

Therefore, open a command prompt, make sure DAISY_HOME is set. Go to 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 (ie the "user for yourself" mentioned there). It will also ask for the URL where the repository is listening, you can simply press enter here.

The program will then ask you for a password for the "registrar" user (Note: there's a typo in the prompt message, it says "internal " user but this should actually say "registrar" user). The registrar user is an administrator user used to allow people to self-register on the wiki, or to send password reminders, etc. The installation program will propose a complex autogenerated password. It's fine to leave it to this, since the next thing the installation program will do is propose to update the cocoon.xconf file with this password, so you don't need to remember it.

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

Creating a Daisy Wiki Site

The Daisy Wiki has the concept of multiple sites, these are multiple views on top of the same repository. The program "daisy-wiki-add-site" can automatically create and configure such a site for you (you need at least one).

Open a command prompt, make sure DAISY_HOME is set. Go to DAISY_HOME/install, and execute:

daisy-wiki-add-site

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, which should be:

DAISY_HOME/daisywiki/webapp/daisy/sites

Normally the installation program will propose this location, so you can simply press enter.

Configuring the Daisy Wiki

Now we still need to configure some parameters for the Daisy Wiki. Edit the following file:

DAISY_HOME/daisywiki/webapp/WEB-INF/cocoon.xconf

In that file, look for the following element:

<cacheUser login="internal" password="defaultpwd"/>

You need to adjust that password to the correct password for the user " internal". You can find this password in the file <datadir >/conf/myconfig.xml, look over there for <repositoryUser login=" internal" ...

If you changed the password for the OpenJMS user (in the openjms.xml file), then look for the following element:

<credentials password="openjms" username="admin"/>

and adjust as needed.

Starting the Daisy Wiki

Open a command prompt, make sure DAISY_HOME is set. Go to the directory DAISY_HOME/daisywiki/bin, and execute:

daisy-wiki

This will start Jetty (a servlet container) with the webapp found in DAISY_HOME/daisywiki/webapp.

You still need to have the repository server, OpenJMS and MySQL running.

Finished!

Now you can point your web browser to:

http://yourhost:8888/daisy/

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.