Installation Guide

System requirements

Hardware:
  • At least 512 MB RAM, recommended 1 GB
  • 2 GHz CPU or more (multi-user access benefits from multi-core machines)
  • min. 1 GB of free disk space for resource storage (and more, depending on usage)

Operating System:

docendo is being developed and tested on Debian Linux, Gentoo Linux and Windows Vista but it should run without problems on all platforms supported by Java, including:
  • Windows x86 and x64 (Windows 2000, 2003, XP, Vista, 7)
  • Linux x86 and x64 (Redhat, SUSE, SLES, Debian, Gentoo)
Software:
  • Java 6 JDK (tested on Sun JDK and OpenJDK).
  • Optional: A DBMS like MySQL or Oracle. This is optional because the standard docendo installation uses HSQLDB, which is a file based SQL server that does not require any services to be installed.
  • Optional: A LaTeX distribution, preferably Tex Live (Version >= 2007) or MiKTeX for Microsoft Windows Systems and additionally the program dvipng (Version >= 1.11). The two commands texi2dvi (now part of the package "texinfo") and dvipng should be runnable from the shell. docendo will check these two commands upon startup and if successful will enable the formula editor (which converts LaTeX-code to PNG image files).
  • Optional: For thumbnail generation of SWF files: the program swfdec-thumbnailer which is part of the swfdec-gnome package for various linux distributions. In case this program is not installed on the server, a fallback thumbnail image will be used for SWF files instead.
  • Optional: For thumbnail generation of FLV files: the program ffmpeg. Running "ffmpeg -formats" should output a line containing "flashsv" indicating that the flash video codec is supported on your system. In case this program is not installed or not correctly configured on the server, a fallback thumbnail image will be used for FLV files instead.

Installation

You can choose to install docendo in two different flavors. Technically, it is a standard Java web application, so if you already have a J2EE application server (like Apache Tomcat) up and running, the simplest way is to download docendo as a single web application archive (WAR) and deploy it on your application server. In case you do not already have an application server installed, you may want to download and install the standalone version, which is pre-bundled with Apache Tomcat.

Option 1: Installing the stand-alone version

  1. Download the latest stand-alone version (ZIP or TGZ file) from http://dev.docendo.org.
  2. unzip (or untar) the file.
  3. run [install-dir]/bin/startup.sh on Linux or [install-dir]/bin/startup.bat on Windows systems.
  4. Open your internet browser and visit "http://[servername]:8080/docendo", replacing [servername] with the server you have unpacked docendo on. You should see the docendo page and should be able to login with user "admin", password "admin".

Please consult the Configuration Guide on where to go from here.

Option 2: Installing the deployable web application

This installation option requires an already installed J2EE application server. The concrete installation procedure depends on that application server and we can only give examples for the most commonly used ones. If yours is not in that list, please drop us a note.

The first step for all application servers is to download the latest docendo web application (WAR file) from http://dev.docendo.org. Then follow the steps below. After having deployed the web application, please consult the Configuration Guide on where to go from here.

Deploying on Apache Tomcat

Please note, that the docendo web application needs Tomcat Version >= 6.0. The docendo WAR file already contains a Tomcat deployment descriptor in META-INF/context.xml which sets the needed JNDI properties, so that for deployment you only need to:

  1. Copy the HSQLDB driver jar into Tomcats's lib/ folder.
  2. Rename the downloaded docendo web application WAR file to "docendo.war" and copy it into Tomcats's webapps folder.
  3. Open the server configuration file "server.xml" within Tomcat's conf/ folder and configure the Connector being used to include the following attributes (especially the attribute URIEncoding):
    <Connector port="8080" protocol="HTTP/1.1" enableLookups="false" connectionTimeout="20000" disableUploadTimeout="true" URIEncoding="UTF-8" />
    
  4. Open your internet browser and visit "http://[servername]:8080/docendo", replacing [servername] with the server you have deployed docendo on. You should see the docendo page and be able to login with user "admin", password "admin".

Deploying on Jetty

  1. Copy the HSQLDB driver jar into Jetty's lib/ext/ folder.
  2. Copy the downloaded docendo web application WAR file into Jetty's webapps folder.
  3. Create a file docendo.xml in Jetty's contexts folder with the XML content below. Note that you have to replace the [version] string to match the downloaded docendo WAR file. The configuration has been tested on Jetty 6.1.19.
  4. Open your internet browser and visit "http://[servername]:8080/docendo", replacing [servername] with the server you have deployed docendo on. You should see the docendo page and be able to login with user "admin", password "admin".
<?xml version="1.0"?>
<!DOCTYPE Configure PUBLIC "-//Mort Bay Consulting//DTD Configure//EN" "http://jetty.mortbay.org/configure.dtd">
<Configure id='wac' class="org.mortbay.jetty.webapp.WebAppContext">
    <!-- Ensure Jetty Plus features are enabled for docendo web application -->
    <Set name="configurationClasses">
        <Array type="java.lang.String">
            <Item>org.mortbay.jetty.webapp.WebInfConfiguration</Item>
            <Item>org.mortbay.jetty.plus.webapp.EnvConfiguration</Item>
            <Item>org.mortbay.jetty.plus.webapp.Configuration</Item>
            <Item>org.mortbay.jetty.webapp.JettyWebXmlConfiguration</Item>
            <Item>org.mortbay.jetty.webapp.TagLibConfiguration</Item>
        </Array>
    </Set>
    <Set name="contextPath">/docendo</Set>
    <Set name="war"><SystemProperty name="jetty.home" default="." />/webapps/docendo-webapp-[version].war</Set>
    <Set name="extractWAR">true</Set>
    <Set name="copyWebDir">true</Set>

    <!-- Define an env entry for docendo repository path with webapp scope for java:comp/env -->
    <New id="docendo/repositoryPath" class="org.mortbay.jetty.plus.naming.EnvEntry">
        <Arg><Ref id='wac' /></Arg>
        <Arg>docendo/repositoryPath</Arg>
        <Arg type="java.lang.String"><SystemProperty name="jetty.home" default="." />/docendo-files/repository</Arg>
        <Arg type="boolean">false</Arg>
    </New>

    <!-- Define an env entry for docendo database configuration with webapp scope for java:comp/env -->
    <New id="jdbc/docendo" class="org.mortbay.jetty.plus.naming.Resource">
        <Arg><Ref id='wac' /></Arg>
        <Arg>jdbc/docendo</Arg>
        <Arg>
            <New id="myxadatasource" class="org.enhydra.jdbc.standard.StandardDataSource">
                <Set name="DriverName">org.hsqldb.jdbcDriver</Set>
                <Set name="Url">jdbc:hsqldb:file:<SystemProperty name="jetty.home" default="." />/docendo-files/database/docendo</Set>
                <Set name="User">sa</Set>
                <Set name="Password"></Set>
            </New>
        </Arg>
    </New>
</Configure>

Deploying on JBoss

to be done...