HowToInstallWebical

So you want to install Webical on your own server? Great! Here is how to do it.

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/
  • The following assumes you have Tomcat 5.5 running on http://localhost:8080/
• MySQL 5 or higher: http://dev.mysql.com/downloads/
  • The following assumes you have MySQL 5.0.26 running on localhost:3306
• MySQL Connector/J from: http://dev.mysql.com/downloads/connector/j/

There are 2 ways of installing webical:

• Downloading the prebuild war
• Building it from source yourself

The prebuild war

You can download the latest webical WAR from http://sourceforge.net/project/showfiles.php?group_id=176849.
A readme file is included. You can also follow the Default Installation steps below

Building from Source

You can use your favorite svn client to checkout the latest webical source. The url is https://webical.svn.sourceforge.net/svnroot/webical/trunk.
Execute svn co https://webical.svn.sourceforge.net/svnroot/webical/trunk webical-parent to download the latest source with the svn commandline client

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

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

Default Installation

Webical comes with settings for a default installation. If you want to changes these settings, read Custom installation below. If you have build webical from source, rename the ROOT.war to webical.war. The prebuild war comes with a README

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 prebuild version, 2 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 and copy the .jar file from the MySQL? Connector/J package and place the .jar in $CATALINA_HOME/common/lib/.

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. Documentation on how to use the Tomcat manager can be found at http://tomcat.apache.org/tomcat-5.0-doc/manager-howto.html.

The default installation is compelete!

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

Custom installation

If you want to alter the default installation, you first have to complete the default installation. After webical is deployed, Tomcat has unpacked the war to $CATALINA_HOME/webapps/webical and the xml files can be changed.

Change login settings

With the default installation a user is created from the AUTH_setup.sql script. If you want to change the login settings for the user, 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 aswell.

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

Use a different database

The database settings are stored in context.xml. This file can be found in $CATALINA_HOME/webapps/webical/META-INF/context.xml. This file is only editable after webical is deployed.
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 database.
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. But it's not impossible to use a different database, like Oracle.

To do this, you have to install your own JDBC driver for Tomcat to use in $CATALINA_HOME/common/lib, and change the in context.xml.
For more information contact your database provider (or Google ).

Alternate Realm setup

The default installation uses a MySQL? database for the Tomcat authentication realm. It is however possible to use a different method of authentication.
You can use a separate database for authentication if you already have a database with users you want to use. To do this, you have to edit the context.xml file located in $CATALINA_HOME/webapps/webical/META-INF/context.xml. This file is only editable after webical is deployed deployed.

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 used to authenticate by replacing the following paramaters:

• connectionName: the username to use when connecting to the database
• connectionPassword: the password to use when connectig 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 user 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 $CATALINA_HOME/webapps/webical/WEB-INF/web.xml.

Troubleshooting

• $CATALINA_HOME
  • $CATALINA_HOME refers to the installation directory of Tomcat. In other words: The directory you installed or extracted Tomcat to.
• It does not work
  • Check $CATALINA_HOME/logs/webical.log for pointers
• It still does not work
  • Consult the mailing lists