Introduction

This guide will tell you what is needed to install Webical and how to do this step by step.

Requirements

You need to have a couple of things installed on your machine, in order to run Webical.

• Java 1.5 or higher: http://java.sun.com/javase/downloads/index.jsp
• Tomcat 5.5 or higher: http://tomcat.apache.org/
• MySQL 5 or higher: http://dev.mysql.com/downloads/
• MySQL Connector/J from: http://dev.mysql.com/downloads/connector/j/

Getting the application

There are two ways of obtaining Webical. You can either download the pre build war file to deploy in Tomcat. Or you can get the Webical source from our svn repository and compile it yourself. Both methods are explained below.

Pre built

The latest pre built war is available in our download section. A readme file is included in the Archive with the a short version of this guide.

If you download the pre built war, you can continue to the Installation steps below.

Building from Source

You can use your favorite svn client to checkout the latest webical source. The url is http://webical.googlecode.com/svn/trunk/.

Execute svn co http://webical.googlecode.com/svn/trunk/ ./webical to download the latest source with the svn commandline client

To have maven build a war for you, enter the webical directory and execute mvn -Denv=release clean package. If you don't have Maven, get it from the apache maven site. The maven manual is also found on that website.

If all went well, you now have a WAR called ROOT.war in the webical/webical-war/target/release/ directory.

Installation

Webical comes with a default installation setup. This is a quick way of getting Webical up and running.

If you plan on running Webical on a live production server, we suggest you continue with the Custom installation part.

Default Installation

Webical comes with settings for a default installation. If you want to changes these settings, read Custom installation below.

This guide assumes you have Tomcat 5.5 running on http://localhost:8080/ and MySQL 5 running on localhost:3306 for the default installation.

If you have built Webical from source, rename the ROOT.war to webical.war.

Setting up the database

Webical uses a database to cache the calendar data. By default, it uses a MySQL database. The default installation assumes you have a database named webical and a database user webical with password webical. This user needs at least SELECT, INSERT, UPDATE, DELETE, ALTER, INDEX, CREATE and DROP access to the webical database.

With the pre built war, two SQL scripts are included. If you checked out the source from svn, these scripts can be found in the doc directory. Apply DB_setup.sql to your database to create the tables needed for the calendar cache.

The default installation uses the same MySQL database for the Tomcat authentication realm. If you want to change to a different way of authenticating, or if you have an existing database with user, read Custom installation. Apply AUTH_setup.sql to your database to create the tables needed by Tomcat to authenticate. This script also inserts the first user into the database.

Setting up Tomcat

Tomcat needs the MySQL Connector/J driver to connect to a MySQL database. Unpack the MySQL Connector/J package and copy the .jar file to the $CATALINA_HOME/common/lib/ directory.

Next, copy the webical.war file to the $CATALINA_HOME/webapps directory. Once you start Tomcat, Tomcat will deploy it into the /webical context.

As an alternative, you can use the Tomcat manager to deploy the war to your Tomcat server. The manager can be reached at http://localhost:8080/manager/html. Documentation on how to use the Tomcat manager can be found at http://tomcat.apache.org/tomcat-5.5-doc/manager-howto.html.

After (re)starting tomcat, you can visit http://localhost:8080/webical to view the installation. You can log in with username webical and password webical. On the first visit, you will be redirected to the configuration page after login. You can go to the configuration page manually by visiting http://localhost:8080/webical/app/configuration.

Custom installation

If you downloaded the pre built war file, and you want to alter the default setup, you first have to complete the Default installation steps above. After Webical is deployed, Tomcat has unpacked the war to $CATALINA_HOME/webapps/webical and the XML configuration files can be changed.

If you downloaded the source, you can alter the files before packaging them. The files can be found in the webical-war/etc/environments/release directory.

All paths in this installation step are relative from either $CATALINA_HOME/webical/ for the deployed war or PATH/TO/WEBICAL/SOURCE/webical-war/target/release/ for the unpackaged source.

Change login settings

The default installation user is created with the AUTH_setup.sql script. If you want to change the login settings for the user, then change them in this file. The following 2 inserts contain the information for the user:

-- Create a new user
INSERT INTO _auth_user (username, userpass) VALUES ("webical", "webical");

-- Create a new userrole
INSERT INTO _auth_userrole (username, role) VALUES ("webical", "webicaluser");

The first insert creates a new user, the second insert connects it to a user role. If you change the user name in the first insert, make sure you change the first value of the second insert as well.

If you decide to change the name of the user role, make sure it corresponds to the <role-name> in WEB-INF/web.xml.

Use a different database

The database settings are stored in META-INF/context.xml. You can change the settings for the database in this file. The resource part looks like this:

...
   <Resource 
      name="jdbc/calendarDataBase" 
      auth="Container" 
      type="javax.sql.DataSource" 
      factory="org.apache.tomcat.dbcp.dbcp.BasicDataSourceFactory" 
      username="webical" 
      password="webical" 
      driverClassName="com.mysql.jdbc.Driver" 
      url="jdbc:mysql://localhost:3306/webical?autoReconnect=true" />
...

Replace webical in the url string to use a different database. Change the username and password strings if you have a different database user for the Webical installation.

Make sure that the database user has sufficient rights on the database. The user should have at least SELECT, INSERT, UPDATE, DELETE, ALTER, INDEX, CREATE and DROP access to the database.

Use a different database provider

Webical uses a MySQL database by default. Others can be configured as well, as long as a JDBC driver is available for that specific database.

Copy the JDBC driver (a .jar file) to $CATALINA_HOME/common/lib, and change the driverClassName and url in META-INF/context.xml. Change the following line to the driver for your database:

...
      driverClassName="com.mysql.jdbc.Driver" 
...

Alternate Realm setup

The default installation uses a MySQL database for the Tomcat authentication realm. It is possible to use all other methods of authentication that Tomcat (or the container you are using) provides. You can use a separate database for authentication if you already have a database with users. To do this, you have to edit the META-INF/context.xml file.

The realm part looks like this:

...
   <Realm className="org.apache.catalina.realm.JDBCRealm" 
      debug="4"
      driverName="com.mysql.jdbc.Driver"
      connectionName="webical" 
      connectionPassword="webical" 
      connectionURL="jdbc:mysql://localhost:3306/webical?autoReconnect=true"
      userTable="_auth_user" 
      userNameCol="username" 
      userCredCol="userpass"
      userRoleTable="_auth_userrole" 
      roleNameCol="role"/>
...

You can change the database by replacing the following paramaters:

• connectionName: the username to use when connecting to the database
• connectionPassword: the password to use when connecting to the database
• connectionURL: the URL to the database. The format is jdbc:connectorName://hostname:port/databaseName
• userTabel: the table where the user data is stored (will not be written)
• userNameCol: the column in userTable to use as the username
• userCredCol: the column in userTable to use as the user password
• userRoleTable: the table to use for user roles
• roleNameCol: the column to use in userRoleTable as the name for the user roles

Make sure that the user roles are the same as in WEB-INF/web.xml.

If you would like to use LDAP for authentication, here is an example:

    <Realm className="org.apache.catalina.realm.JNDIRealm"
	debug="4"
	connectionURL="ldaps://ldap.webical.org"
	secure="true"
        connectionName="ou=System,dc=webical,dc=org"
        connectionPassword=""
        userPattern="uid={0},ou=Users,dc=webical,dc=org"
        roleBase="ou=Groups,dc=webical,dc=org"
        roleName="cn"
        roleSearch="(memberUid={1})"/>

Troubleshooting

What is $CATALINA_HOME?

$CATALINA_HOME refers to the installation directory of Tomcat.

It does not work

Check $CATALINA_HOME/logs/webical.log for possible causes. Also check our issue tracker if this problem occurred with other users. Please don't hesitate to file an issue

It still does not work

Consult the developers on our mailing list.