The tricky part comes when you have several different fact tables that share dimensions. For example your student-course-load fact and your grades fact, plus even your student-head-count fact, can all be measured by semester and by department.

The main thing is to make sure you roll up your summaries to the same level of granularity. That is, if you're summarizing head-count by division, then you should also roll up course-load by division, in the same query. Otherwise you'll be double-counting all kinds of stuff.

NOTE: for a more up-to-date step-by-step guide on installing a modern Sakai these days, check out the official Development Environment Setup Walkthrough at the Sakai Confluence site. In particular, Sakai version 2.5.x and beyond all use Maven 2 ("mvn"). Sakai 2.4.x and older versions of Sakai use Maven 1 ("maven"). Also, the JDK compatibility package mentioned below is no longer required for recent versions of Sakai.

Still, you may still find the HOWTO here helpful, as it includes newbie-friendly rationale and context not found in the official version (plus, we're told that our writing is a bit different from most, in that it's "written in English, for humans" -- we hear that a lot).

Sakai is an open-source CLE (collaborative learning environment) or LMS (learning management system) similar to Blackboard, but without the licensing headaches. OSP is an electronic portfolio toolkit built into Sakai -- so, once you install Sakai, you've got an electronic portfolio system ready to roll! Here's how you can get it running as a sandbox so you can learn more about what it can do--

Prerequisites:

To get SAKAI/OSP running, you'll need:

• Java Developer Kit, or "JDK" for short (Sakai and OSP are written in Java)
• Maven (this builds the system)
• Tomcat (it serves up the web pages)
• Subversion, or "svn" for short (it pulls the source code from sakaiproject.org)
• Mysql (somewhere to store all the data)
• and, of course, Sakai itself

Note that versions change when patches are applied and bugs are fixed, so we'll try to avoid version-specific info when possible. For the exact versions we're using as we write this (January 2007) see footnotes at the very bottom.

Ready?

Java:

We download the "netbeans" version. Don't be surprised if this part of your experience is confusing -- which link to follow? You're not alone (Java is for programmers, don't forget, so they build the website for a clientele different from normal mortals)...

Here's the most generic path to a healthy JDK that we could find -- instad of giving you a final URL which could change weekly, here's a conceptual path to get to the stuff you need (and the website may change too, of course, but they're likely to keep the general idea the same):

1. Visit http://java.sun.com/ -- now, if you think you can 1) where to go and 2) which one is the right download for you, feel free and dive right in! We find that there are enough varieties and versions to select among that it's easy to get lost, so:
2. Click "Downloads":
   
3. Click "Java SE":
   
4. Click "Get the JDK download" line:
   
5. Check out the license agreement and click "Accept" -- though it looks like you can skip this part and go straight to your download, that won't work! :)
   
6. Pick the instance appropriate for your platform (we use Debian/GNU Linux) and click it to start your download:
   • Linux
   • Solaris SPARC
   • Solaris x86
   • Windows
   For Linux, we use the non-rpm *.bin style.

Now that we've got it downloaded, we plop it into /usr/local:

# ls -lF /usr/local
total 48460
drwxrwsr-x   2 root    staff     4096 Jun 30 18:14 bin/
drwxrwsr-x   2 root    staff     4096 Nov 18  2005 games/
drwxrwsr-x   2 root    staff     4096 Nov 18  2005 include/
-rw-r--r--   1 root    staff 49518537 Oct 25 16:21 jdk-***-linux-***.bin
drwxrwsr-x   5 root    staff     4096 Mar 22  2006 lib/
lrwxrwxrwx   1 root    staff        9 Nov 18  2005 man -> share/man/
drwxrwsr-x   2 root    staff     4096 Nov 18  2005 sbin/
drwxrwsr-x   6 root    staff     4096 Mar 22  2006 share/
drwxrwsr-x   2 root    staff     4096 Nov 18  2005 src/

(Instead of a specific version number above we're showing asterisks -- when you get around to doing these steps you're likely to wind up with a more modern instance than what we just downloaded, so we're trying to keep this very generic.) And there, we "run" it (after all it's just a shell script):

# sh jdk*bin

It'll ask for you to agree to the licencing scheme again, and once you do it'll decompress everything in no time.

Now you'll have a new directory:

drwxr-xr-x   9 root    staff     4096 Oct 12 15:01 jdk1.*/

This is your java home! (Again, we're generifying the version numbers since they're ephemeral.) For convenience, we make a generic "java" symbolic link to refer to our new java home:

# ln -s jdk1.* java
# ls -ldF j*
lrwxrwxrwx  1 root staff       11 Oct 25 16:41 java -> jdk1.*/
-rw-r--r--  1 root staff 49518537 Oct 25 16:21 jdk-***-linux-***.bin
drwxr-xr-x  9 root staff     4096 Oct 12 15:01 jdk1.*/

So now when we refer to /usr/local/java we're really referring to the instance we unfolded into the jdk1.*/ directory. And if we ever need to install an update, we do so and then just point the "java" symlink to the new directory. Neat!

Maven:

Here, the specific VERSION is actually important -- Maven 1.0.2 is what Sakai expects, until further notice. If you look at the Apache website you'll see that Maven is already past version 2.0... but the Sakai architects haven't given the "green light" to that one yet [NOTE: Maven 2.0 is required for 2.5.x and beyond, but this install-howto is for version 2.3.x] so stick with 1.0.2 for now. So here we go:

1. Browse to http://maven.apache.org/maven-1.x/ making sure you're NOT looking at version 2.x!
2. Click "Download"
   
3. Choose the Maven 1.0.2 version appropriate for your platform:
   
   Only version 1.0.2, remember! For Debian/GNU Linux, we use ".tar.gz".
4. Clicking the link there will take you to a list-of-mirrors, and THAT is where you download the actual file. (If you download the above link and try to unzip it, you won't get very far since it's really just an HTML page.)

Once we have it downloaded we move it to /usr/local:

# cd /usr/local
# ls -lF maven*
-rw-r--r--  1 root staff 20092 Oct 25 20:46 maven-1.0.2.tar.gz

And now we unzip it:

# tar zxf maven-1.0.2.tar.gz
# ls -ldF mav*
drwxr-xr-x  5 root root     4096 Dec  7  2004 maven-1.0.2/
-rw-r--r--  1 root staff 6060686 Dec  7  2004 maven-1.0.2.tar.gz

Now we do our "symlink" trick again:

# ln -s maven-1.0.2 maven
# ls -ldF mav*
lrwxrwxrwx  1 root staff      11 Oct 27 11:11 maven -> maven-1.0.2/
drwxr-xr-x  5 root root     4096 Dec  7  2004 maven-1.0.2/
-rw-r--r--  1 root staff 6060686 Dec  7  2004 maven-1.0.2.tar.gz

Now for our web server--

Tomcat:

There are TWO downloads to make here: one is Tomcat itself, the other is the JDK compatibility package.

1. Visit http://tomcat.apache.org/
2. Click "Tomcat 5.x" under "Download":
   
3. Download the appropriate "Core" instance for your platform -- for Debian/GNU Linux we use ".tar.gz":
   
4. ALSO download the JDK compatibility package as well:
   
   

First, move the Tomcat archive to /usr/local and unfold it there -- and make a symlink to it:

# tar xfz apache-tomcat*
# ln -s apache-tomcat-*** tomcat
# ls -ldF *tomcat*
drwxr-sr-x  11 root staff    4096 Oct 27 15:33 apache-tomcat-*/
-rw-r--r--   1 root staff 5949295 Sep 28 09:01 apache-tomcat-*.gz
lrwxrwxrwx   1 root staff      20 Oct 27 15:33 tomcat -> apache-tomcat-*/

(Note we're leaving out the version-number specifics again -- just make sure you're using the latest version 5 tomcat.)

Now move the JDK-compat package to /usr/local and unfold it right on top of your new Tomcat setup (it adds bin/jmx.jar, common/endorsed/xercesImpl.jar and common/endorsed/xml-apis.jar):

# tar xfz apache-tomcat-***-compat.tar.gz
# ls -ldF *tomcat*
drwxr-sr-x  11 root staff    4096 Oct 27 15:50 apache-tomcat-*/
-rw-r--r--   1 root staff 1624224 Sep 28 09:01 apache-tomcat-*-compat.tar.gz
-rw-r--r--   1 root staff 5949295 Sep 28 09:01 apache-tomcat-*.tar.gz
lrwxrwxrwx   1 root staff      20 Oct 27 15:53 tomcat -> apache-tomcat-*/

Edit tomcat/conf/server.xml and look for port="8080" to find this snippet:

    <Connector port="8080" maxHttpHeaderSize="8192"
               maxThreads="150" minSpareThreads="25" maxSpareThreads="75"
               enableLookups="false" redirectPort="8443" acceptCount="100"
               connectionTimeout="20000" disableUploadTimeout="true" />

We need to add a URIencoding attribute there:

    <Connector port="8080" maxHttpHeaderSize="8192"
               URIEncoding="UTF-8"
               maxThreads="150" minSpareThreads="25" maxSpareThreads="75"
               enableLookups="false" redirectPort="8443" acceptCount="100"
               connectionTimeout="20000" disableUploadTimeout="true" />

Nothing to it! Now, we'll make life a little easier for casual browsers by giving them a default redirect: they'll be able to browse to http://your.server:8080 and this will redirect them to your OSP portal [which is being deprecated in version 2.5.x and beyond] instead of showing a default Tomcat page:

# cat > tomcat/webapps/ROOT/index.html
<html>
    <head>
        <meta http-equiv="refresh" content="0;url=/osp-portal">
        <title>Redirecting to /osp-portal</title>
    </head>
    <body>serving up <a href="/osp-portal">/osp-portal</a> instead...</body>
</html>
^D

Subversion:

You may have noticed that we use Debian/GNU Linux -- and here's why:

# apt-get update
# apt-get install subversion

And to keep everything up-to-date, we just do:

# apt-get upgrade

Big chore, eh? Next!

Unfortunately, Debian's Tomcat is a version behind, and Maven isn't even available as a Debian package. Zut alors!

Mysql:

Again, using Debian, we can get MySql running in a jiffy:

# apt-get update
# apt-get install mysql-client-4.1 mysql-server-4.1

Nothing to it!

Another nice aspect of dealing with Debian is that "unstable" to the debian community matches what many other folks would consider "rock solid". There are mission-critical servers running Debian "unstable" for years on end without a blip!

Note that we still don't have an actual Sakai database yet -- that will come soon enough...

We also need a java library to hook up your Java to your MySql (strangely enough, it's called the JDBC MySql connector):

1. Browse to http://dev.mysql.com/downloads/connector/j/3.1.html
2. Download the latest version-3 connector (version 5 isn't fully endorsed)

3. Unfold it so you can get to the *.jar file:

   $ tar xfz mysql*tar.gz
   $ ls -ld mysql*
   drwxr-xr-x  5 sakai sakai     4096 Oct 18 16:35 mysql-connector-java-3.1.*/
   -rw-r--r--  1 sakai sakai 28936239 Oct 31 14:21 mysql-connector-java-3.1.*.tar.gz
   $ ls -l mysql*/*jar
   -rw-r--r--  1 sakai sakai 459094 Oct 18 16:35 mysql-connector-java-3.1.14/mysql-connector-java-3.1.*-bin.jar

4. Plop the *.jar file into common/lib:

   $ cp mysql*/*.jar /usr/local/tomcat/common/lib/

Without that, Tomcat would NOT be able to communicate with MySql.

On with the configuring!

Variables, Preparations and other Settings:

Okay. Before we do anything else, we'll create a "sakai" shell user and make sure permissions on /usr/local/tomcat are properly set:

# useradd sakai
# chown -R sakai:sakai /usr/local/tomcat/*
# su - sakai

The home directory of user "sakai" is where the source code and settings will be for building Sakai/OSP. And when user "sakai" builds and deploys the sakai system, it'll wind up in /usr/local/tomcat.

You should set some environmental variables: do these "live" on your command line so you can test them, but also put them in a shell script that you can source at any time (including from ~sakai/.bashrc) so they'll be "permanent".

First, SAKAI_HOME is ~sakai:

$ export SAKAI_HOME=/home/sakai

Next, where's java? It's in $JAVA_HOME:

$ export JAVA_HOME=/usr/local/java
$ ls -l $JAVA_HOME
lrwxrwxrwx  1 root staff 11 Oct 25 16:41 /usr/local/java -> jdk1.5***

So now $JAVA_HOME refers to our /usr/local/java symlink. And Java itself can be found in $JAVA_HOME/bin/java. Easy!

Now for $MAVEN_HOME:

$ export MAVEN_HOME=/usr/local/maven

Now add the appropriate BIN directories to your $PATH (in your .bashrc so it's permanent) and then test to make sure everything is all set up:

$ export PATH="$PATH:$JAVA_HOME/bin:$MAVEN_HOME/bin"
$ java -version
java version "1.5***"
Java(TM) 2 Runtime Environment, Standard Edition (build 1.5***)
Java HotSpot(TM) Client VM (build 1.5***, mixed mode, sharing)
$ maven -v
 __  __
|  /  |__ _Apache__ ___
| |/| / _`  V / -_) '   ~ intelligent projects ~
|_|  |___,_|_/___|_||_|  v. 1.0.2

Piece of cake!

For Tomcat, the environmental variable is, for historical purposes, $CATALINA_HOME -- we set the variable (in .bashrc, of course) and then test it:

$ export CATALINA_HOME=/usr/local/tomcat
$ sh $CATALIA_HOME/bin/version.sh
Using CATALINA_BASE:   /usr/local/tomcat
Using CATALINA_HOME:   /usr/local/tomcat
Using CATALINA_TMPDIR: /usr/local/tomcat/temp
Using JRE_HOME:       /usr/local/java
Server version: Apache Tomcat/***
Server built:   ***
Server number:  ***
OS Name:        Linux
OS Version:     ***
Architecture:   ***
JVM Version:    ***
JVM Vendor:     Sun Microsystems Inc.

To be specific, we create a script called "~sakai/variables.sh" and it contains:

#!/bin/sh
export SAKAI_HOME=/home/sakai
export JAVA_HOME=/usr/local/java
export MAVEN_HOME=/usr/local/maven
export CATALINA_HOME=/usr/local/tomcat
export PATH="$PATH:$JAVA_HOME/bin:$MAVEN_HOME/bin"
export JAVA_OPTS="

Your ~/.bashrc should 'source' that file, and so could any other script -- which is useful, as we'll soon see.

Now let's get MAVEN ready: create a file "build.properties" to point to your tomcat directory and indicate the remote sakai repository:

$ cat > build.properties
maven.repo.remote=http://source.sakaiproject.org/maven/
maven.tomcat.home=/usr/local/tomcat/
^D

End "cat" with control-D (and note that /usr/local/tomcat is the tomcat-specific symlink we established a while back). Now, initialize your MAVEN repository:

$ $MAVEN_HOME/bin/install_repo.sh ~/.maven
$ ls -lF ~/.maven
drwxr-xr-x   3 sakai sakai 4096 Oct 27 17:57 ant/
drwxr-xr-x   3 sakai sakai 4096 Oct 27 17:57 commons-beanutils/
drwxr-xr-x   3 sakai sakai 4096 Oct 27 17:57 commons-betwixt/
drwxr-xr-x   3 sakai sakai 4096 Oct 27 17:57 commons-cli/
[yada yada, snip snip]

A walk in the park! Now for the important stuff--

Download, Build, Deploy:

Now you're ready to get started with the meat of the project -- and this is the part you can iterate over as you tweak your sakai instance (adding skins, for example):

$ svn export https://source.sakaiproject.org/svn/sakai/branches/sakai_2-3-x/

This will take quite a while -- lots of stuff to download! -- so go catch up on email if you need to. The 2-3-x instance gets all the latest patches and fixes, so we use that instead of 2-3-0 or 2-3-9.

Subversion ("svn" for short) creates the "sakai_2-3-x" directory and populates it with all kinds of source stuff. Eventually. Now, another symlink:

$ ln -s sakai_2-3-x sakai
$ ls -ldF sakai*
lrwxrwxrwx   1 sakai sakai   11 Oct 27 18:42 sakai -> sakai_2-3-x/
drwxr-xr-x  57 sakai sakai 4096 Oct 27 18:41 sakai_2-3-x/

Now our sakai source files will be found at ~sakai/sakai/ because of our old friend, the symlink trick. Nice!

Here we go! [Maven 2, which is used for 2.5.x and beyond, has a different set of commands to use here, of course: mvn clean install sakai:build] If you build it, they will come!

$ maven sakai | tee maven-sakai-log
Starting the reactor...[snip]
BUILD SUCCESSFUL
Total time: 10 minutes 43 seconds
Finished at: Fri Oct 27 19:23:04 CDT 2006

Using "maven sakai" is a nice shortcut for "maven cln bld dpl" which means "clean, build, deploy". It zaps old stuff (for the first instance here, there isn't any to zap, of course) and then rebuilds it, and deploys it into the tomcat directory (according to your build.properties file).

This command will take a LOOOONG time -- ten minutes, maybe more -- and generate copious output. (Thus it's good to use "tee" to keep a copy in case you want to look at it later.)

What BUILD does, is takes all the .../src/* stuff, and compiles it to their respective .../target/* destinations in preparation for deployment. DEPLOY moves it all to the live Tomcat directory. (And CLEAN zaps all the .../target/ directories.)

So -- now that Tomcat has everything it needs to serve up Sakai, we need to configure Sakai to our liking, and we also need a database for Sakai to work with...

Final Configuration:

Two things remain: Sakai needs a database, and some configuration.

Create the Sakai database

As root, connect to MySql and:

mysql> create database sakai_2_3_x default character set utf8;
mysql> grant all on sakai_2_3_x.* to sakaiuser@'localhost' identified by 'snarkySekrit';
mysql> grant all on sakai_2_3_x.* to sakaiuser@'127.0.0.1' identified by 'snarkySekrit';

Piece of cake! Just make sure you use your own settings for the bold stuff -- particularly a reasonable password, as opposed to cut-and-pasting our example here...

Now we need to make sure sakai.properties is all set up:

Configuring sakai.properties

If we're going to tell Sakai (tomcat) that SAKAI_HOME is ~sakai, that's where it expects to find sakai.properties. You'll notice that there isn't any such animal there, yet.

Fortunately there are several available in the source code you just downloaded via svn: the one we want is specifically OSP-savvy:

$ mkdir $CATALINA_HOME/sakai
$ cp sakai/osp/overlay/component/component-api/component/src/config/org/sakaiproject/config/sakai.properties $CATALINA_HOME/sakai
$ ln -s $CATALINA_HOME/sakai/sakai.properties ~/properties
$ ln -s $CATALINA_HOME/logs/catalina.out ~/

Now we have ~sakai/properties as a symlink to $CATALINA_HOME/sakai/sakai.properties and a shortcut to the catalina.out logfile as well.

The OSP instance is the one with /osp-portal instead of just /portal. (This is assuming your sakai symlink -- the one that points to the sakai-* source code you just downloaded via svn -- is in your current directory, of course.)

Now, edit your "~sakai/sakai.properties" file to ensure:

# set the hibernate dialect (for shared datasource), HSQLDB by default, mySql and Oracle examples
#hibernate.dialect=org.hibernate.dialect.HSQLDialect
hibernate.dialect=org.hibernate.dialect.MySQLDialect

That is, disable (comment-out) HSQL, and enable MySQL instead. Also add:

vendor@org.sakaiproject.db.api.SqlService=mysql
driverClassName@javax.sql.BaseDataSource=com.mysql.jdbc.Driver
url@javax.sql.BaseDataSource=jdbc:mysql://localhost:3306/sakai_2_2_x?useUnicode=true&characterEncoding=UTF-8
username@javax.sql.BaseDataSource=sakaiuser
password@javax.sql.BaseDataSource=snarkySekrit
validationQuery@javax.sql.BaseDataSource=select 1 from DUAL
defaultTransactionIsolationString@javax.sql.BaseDataSource=TRANSACTION_READ_COMMITTED

Those are the parameters needed to tell Tomcat how to connect to the Sakai database; the bold stuff needs to be replaced by the strings you've used in your setup. (During the first connection, it'll create all the tables as needed. Nice!)

Also tweak the following, accordingly:

serverId=serious.name.net
serverUrl=http://www.serious.name.net:8080
serverName=www.serious.name.net
termyear.*
termlistabbr.*
termstarttime.*
termendtime.*

Now we can create up.sh/down.sh scripts to launch and terminate Sakai:

#!/bin/sh
. ~sakai/variables.sh
$CATALINA_HOME/bin/startup.sh && tail -f $CATALINA_HOME/logs/catalina.out

That's "up.sh" and here's "down.sh":

#!/bin/sh
. ~sakai/variables.sh
$CATALINA_HOME/bin/shutdown.sh && tail -f $CATALINA_HOME/logs/catalina.out

Note that these scripts finish with "tail -f" which will show the log file contuously, as it grows... to get your command-line back, you can press ^C (control-C) any time.

$ ~/up.sh 
Using CATALINA_BASE:   /usr/local/tomcat
Using CATALINA_HOME:   /usr/local/tomcat
Using CATALINA_TMPDIR: /usr/local/tomcat/temp
Using JRE_HOME:       /usr/local/java
[snip]

The first four lines should reflect some of your environment variable settings. And we're off to the races!

This will continue for QUITE A WHILE -- ten minutes or more, on the first run. Remember, it has to initialize the database as well!

If all goes well, you'll see LOTS of "INFO:" items fly by (and hopefully no ERROR or SEVERE). If you get to the point where the log shows:

INFO: Server startup in 258168 ms

Then you're up! To shut it down:

$ ~/down.sh
[snip]
INFO: Stopping Coyote HTTP/1.1 on http-8080[snip]

When you see "Stopping Coyote" you're all finished!

Versions (as of January 2007):

• Java: jdk-1.5.0_10-linux-i586-rpm.bin
• Maven: maven-1.0.2
  
• Tomcat: apache-tomcat-5.5.20
  
• Subversion: 1.1.4-2 (Debian Sarge)
• MySql: 4.1.12 (Ubuntu universe)
• Sakai/OSP: 2-3-x

Previously this article had talked about getting Tomcat itself secured via a Keystore, and having Tomcat deal directly with the SSL traffic. Well, we've got a whole new paradigm now. :)

So you've got Sakai up and running, and now you'd like to enable secure-sockets layer (SSL) so you can run it encrypted over HTTPS instead of plain-text HTTP...

No problem. First make sure you have Sakai installed and configured, and test it to make sure it works as expected via port 8080 in clear-text (http). Once that's confirmed to be working well, then you take the steps you'll need to secure it for https.

Using APACHE to handle HTTPS traffic, with Tomcat backstage

We've found that the most flexible way to do this is to use Apache to handle the secure https:// traffic, and have Mod_JK communicate with Tomcat (Using the "AJP13" protocol) behind the scenes. That is, Apache will handle all of the actual encrypted user interaction on port 443 -- Tomcat will only talk to Apache via AJP, and your users can't even get directly to Tomcat, only through Apache.

Here's what you will need, certificate-wise:

• A private key (certificate)
• A certificate-signing request (CSR)
• A certificate authority (CA) to sign the public key
• A public key signed by the CA

Note that you can be your own CA -- but your users' browsers will alert them to the fact that the certificate-authority that signed the certificate isn't a recognized one, and they should "proceed at their own risk, with extreme caution", and "don't complain if something odd happens because we're not responsible for you trespassing in these dangerous, murky waters"... warnings like that. If you pay a recognized CA to sign your certificate instead, they won't see any warnings at all and your users will have a nice, seamless experience as they browse securely.

You will also need the following components -- and if you use Debian or a Debian derivative such as Ubuntu, we've included the commands used to install them:

• Apache (apt-get install apache2)
• Apache's Mod_SSL (dpkg -S mod_ssl indicates that 'apache2.2-common' supplies it, meaning that it comes with apache2)
• Apache's Mod_JK (apt-get install libapache2-mod-jk, this is where the AJP protocol setup comes from)
• OpenSSL (apt-get install openssl)

Creating your private and public keys/certificates:

Ready? First set up your fully-qualified-domain-name and server-name:

HOSTNAME=`hostname`
SERVER=`hostname | cut -f1 -d.`
mkdir sakai-cert
cd sakai-cert/

So here $HOSTNAME should be something like "sakaisys.university.edu" and $SERVER is "sakaisys". Set yours according to your context! (Note that we will be using $HOSTNAME and $SERVER below instead of fixed strings, even when it's not possible to use the variable in a particular context.)

Next, generate your private key:

# openssl genrsa -des3 -out $SERVER.private.key 1024
Generating RSA private key, 1024 bit long modulus
.........................................++++++
....................................++++++
e is 65537 (0x10001)
Enter pass phrase for $SERVER.private.key: pazwrd-goeth-here
Verifying - Enter pass phrase for $SERVER.private.key: pazwrd-goeth-here

If you want to remove the password on your private key, try this:

# openssl rsa -in $SERVER.private.key -out $SERVER.private.nopassword.key

Now we do the hard part, creating a certificate-signing request (CSR). Here you give your geographical and structural information, and note in particular that you must have your server's FQDN as the COMMON NAME!

# openssl req -new -key $SERVER.private.key -out $SERVER.csr
Enter pass phrase for sakaibb.private.key: pazwrd-goeth-here
You are about to be asked to enter information that will be 
incorporated into your certificate request.
What you are about to enter is what is called a Distinguished 
Name or a DN.
There are quite a few fields but you can leave some blank
For some fields there will be a default value,
If you enter '.', the field will be left blank.
-----
Country Name (2 letter code) [AU]: US
State or Province Name (full name) [Some-State]: New Hampshire
Locality Name (eg, city) []: Portsmouth
Organization Name (eg, company) [Internet Widgits Pty Ltd]: Serensoft University
Organizational Unit Name (eg, section) []: Information Technology
Common Name (eg, YOUR name) []: sakaisys.university.edu
Email Address []: helpdesk@university.edu

Please enter the following 'extra' attributes
to be sent with your certificate request
A challenge password []:
An optional company name []:

Again, just to be certain you're aware -- the COMMON NAME must be the fully-qualified domain name (FQDN) of your server. That's the value that was originally put into $HOSTNAME when we got started.

Once you get a signed public certificate ($SERVER.public.key) you might want to have a look and see what's in it. Here's how:

# openssl x509 -in $SERVER.public.key -text -noout

Post your public and private keys where Apache can use them:

# cp $SERVER.public.key /etc/apache2/ssl/certs/
# cp $SERVER.private.nopassword.key /etc/apache2/ssl/private/

Configure Apache, Mod_SSL and Mod_JK

Apache will be handling all our web traffic, mod_ssl will encrypt it all for us, and mod_jk will pass off appropriate requests to Tomcat for handling by Sakai code.

1. Create a directory /var/www/$SERVER and put an empty "index.html" there.

You might also have a minimal "splash" page there instead, with a link to the https:// version of your Sakai instance.

2. Edit /etc/apache2/sites-available/$SERVER thus:

Note that this example shows a bare-bones setup. You can enhance your configuration to do what you please, but it's a good idea to start with a simple setup first, test it, and once you are confident that all is well, you can start adding tweaks later.

<VirtualHost *:80>
        ServerName  $HOSTNAME
        ServerAlias 192.168.123.234
        ServerAlias $SERVER
        ServerAlias 127.0.0.1

        #ServerAdmin webmaster@localhost

        RedirectMatch ^/$         https://$HOSTNAME/portal
        RedirectMatch ^/(.+)      https://$HOSTNAME/$1
</VirtualHost>

So, for all HTTP requests, we redirect all traffic to the HTTPS secure port. (Instead of $HOSTNAME above you'll have your actual FQDN, and instead of $SERVER you'll have the node-name of your server, of course.)

Now for the SSL and JK (aka AJP) portions of our program:

<IfModule mod_ssl.c>
JkWorkersFile /etc/apache2/workers.properties
<VirtualHost *:443>
        ServerName  $HOSTNAME:443
        # ServerAlias -- not for HTTPS! wouldn't match the certificate

        # Just in case:
        DocumentRoot /var/www/$SERVER

        # Servlet for context to worker named sakai, see workers.properties
        JkMount /* sakai
        JkUnmount /library/skin/* sakai
        JkUnmount /library/content/* sakai

        Alias /library/skin    /path/to/tomcat/webapps/library/skin
        Alias /library/content /path/to/tomcat/webapps/library/content

        #   SSL Engine Switch:
        #   Enable/Disable SSL for this virtual host.
        SSLEngine on
        SSLCertificateFile    /etc/ssl/certs/$SERVER.public.key
        SSLCertificateKeyFile /etc/ssl/private/$SERVER.private.nopassword.key

</VirtualHost>
</IfModule>

Both of the above <VirtualHost> snippets should be in the same /etc/apache2/sites-available/$SERVER config file.

Here if we don't have SSL (IfModule mod_ssl.c) we don't need to worry about mod_jk, and if we do have mod_ssl but we don't have mod_jk we'd rather have Apache break anyway, so we can fix it. You'll need to replace the BOLD items above with the items that make sense for your server, of course ("$SERVER" isn't valid inside Apache config files, for example -- you'll need to replace that with the real value for your server).

Note that we will have Tomcat handle most requests (JkMount /* sakai) but not the static items in /library/skin or /library/content (JkUnmount ...).

3. Edit /etc/apache2/workers.properties.

The above Apache configuration refers to /etc/apache2/workers.properties. That's what configures the core of the Tomcat AJP connector -- here is the workers.properties file in its entirety:

# mod_jk config to connect apache to tomcat
workers.tomcat_home=/home/sakai/tomcat
workers.java_home=/usr/local/java
ps=/
worker.list=sakai

worker.sakai.port=8009
worker.sakai.host=localhost
worker.sakai.type=ajp13
worker.sakai.lbfactor=1

The first # line is just a comment in the file, not a command-line entry! What this does is tell Apache to connect to Tomcat using port 8009 on localhost.

4. Enable your virtual website

# a2ensite $SERVER

5. Restart Apache:

# /etc/init.d/apache2 restart

Note that Apache can be restarted just about any old time -- it's just a conduit for traffic bound for Tomcat. Tomcat is where all the session information is stored. Restarting Apache might get a few of your users a quick "server not found" message, but a quick refresh will resume their session as if nothing happened.

Restarting Tomcat, on the other hand, is a big deal. Your users will be booted off and their sessions closed completely. Careful!

Configure Tomcat

Finally, you must edit $CATALINA_HOME/conf/server.xml to make sure that the AJP connection is enabled on port 8009, and to turn off clear-text traffic on port 8080. The AJP connector should NOT be commented out:

<!-- Define an AJP 1.3 Connector on port 8009 --> 
<Connector port="8009" 
       address="127.0.0.1"
       enableLookups="false" redirectPort="8443" protocol="AJP/1.3" />

As shown above, you might also want to make sure you're asking Tomcat to look for connection on localhost (127.0.0.1) only, meaning it'll ignore your public-facing traffic, for even tighter security.

And the HTTP connector on port 8080 should be commented out:

<!-- Define a non-SSL HTTP/1.1 Connector on port 8080 -->
<!-- <Connector port="8080" maxHttpHeaderSize="8192"
...
/> -->

If you leave the port-8080 traffic open, folks might still keep on using it, and any network packet sniffer would be able to cull passwords and everything else! Better to lock it down.

Finally, restart Tomcat (after checking either A: to see that your users are off, or B: you're willing to suffer the consequences from those who aren't):

# $CATALINA_HOME/bin/shutdown.sh
# tail -f $CATALINA_HOME/logs/catalina.out

Once your Tomcat logs show "INFO main org.apache.coyote.http11.Http11BaseProtocol - Stopping Coyote HTTP/1.1 on http-8080" you can ^C to get out of "tail -f" and then start Sakai back up again:

# $CATALINA_HOME/bin/startup.sh
# tail -f $CATALINA_HOME/logs/catalina.out

Watch for "INFO main org.apache.catalina.startup.Catalina - Server startup in #### ms" and then you're ready!

You could easily configure Apache to listen on port 8080 and forward all requests to http://$HOSTNAME/portal as well.

Easy!