Installing BlueDragon on Ubuntu

Dave Epler presented a great session on LAMBDA boxes at CFUnited-05 in late June 2005. During the course of his presentation, the conversation turned to Ubuntu and his use of it. Dave graciously provided some pointers on getting New Atlanta’s free BlueDragon CFML server installed. With credit to him, here are the steps I had to go through to get BD up and running on my Ubuntu 5.04 boxes. In addition to Ubuntu 5.04, I am running Apache 2.0.53, and installing the free version of BD 6.2. YMMV, of course…

Updated 11.21.2005: These same steps also work verbatim with Ubuntu 5.10, which includes Apache 2.0.54 and MySQL 4.0.24 in its repositories.
Updated 07.03.2006: These same steps, at least down through the automation of the server startup/shutdown, also work verbatim with Ubuntu 6.06, which includes Apache 2.0.55. I have not yet tried for connectivity with my MySQL installation yet. Note also that the name of the file downloaded from the New Atlanta site will be different than shown in the steps below.

Configuring the Directory Structure

BD’s installation script makes some assumptions about where/how the Apache Web server is installed. The BD installation manual covers the gist of what has to happen to get the BD installation to see and recognize the installed Apache so that its connector can be configured; see section 3.7.7 of that document for details. I use the stock Apache2 installation via synaptic on my Ubuntu boxes, and that stock installation is very different from the standard Apache directory structure. As a result, several directories and links need to be established before you run the installation script:

sudo mkdir -p /usr/local/apache/bin
sudo mkdir -p /usr/local/apache/conf
sudo ln -s /etc/apache2/apache2.conf /usr/local/apache/conf/httpd.conf
sudo ln -s /var/www /usr/local/apache/htdocs
sudo ln -s /usr/lib/apache2/modules /usr/local/apache/modules
sudo ln -s /usr/sbin/apache2 /usr/local/apache/bin/httpd

Installing BlueDragon

With the above directories and symbolic links in place, you should be able to run the BD installation script. If you haven’t done so, download it from the the New Atlanta site. As of this writing, it will come down as a file named “BlueDragon_Server_62-Linux.sh”. This script, if invoked without any arguments, will run a GUI-based installer, but I used (and recommend) the console-mode version:

sudo BlueDragon_Server_62-Linux.sh -i console

I chose to install BD in /opt/bluedragon-6.2, and other than that, pretty much accepted the defaults offered by the installation as it went through. If, toward the end of the installation script, it does not recognize the presence of Apache on your box, Ctrl-C the script, and double-check the folders, links, etc., from above.

The installation script modifies file /usr/local/apache/conf/httpd.conf, but to be consistent with Apache2’s installation methodology on Ubuntu, I took the following steps to make the connection between the Web server:

  1. Delete the updated httpd.conf file (and the renamed version of the symlink) created by the installation script, and re-symlink them as above:
    sudo rm -f /usr/local/apache/conf/httpd.conf
    sudo rm -f /usr/local/apache/conf/httpd.conf.bak
    sudo ln -s /etc/apache2/apache2.conf /usr/local/apache/conf/httpd.conf
  2. Using sudo, create file /etc/apache2/mods-available/servletexec.load with the following content:
    LoadModule servletexec_module /usr/lib/apache2/modules/mod_servletexec2.so
  3. Using sudo, create file /etc/apache2/mods-available/servletexec.conf with the following content:
    ServletExecInstances default 127.0.0.1:9999
    ServletExecAliases default /servlet .cfc .cfm .cfml
    
    <location /servlet>
    SetHandler servlet-exec
    </location>
    
    AddHandler servlet-exec cfc
    AddHandler servlet-exec cfm
    AddHandler servlet-exec cfml
  4. Symlink those two new files into Apache’s configuration:
    sudo ln -s /etc/apache2/mods-available/servletexec.load /etc/apache2/mods-enabled/servletexec.load
    sudo ln -s /etc/apache2/mods-available/servletexec.conf /etc/apache2/mods-enabled/servletexec.conf
  5. Restart Apache, and then manually start the BD server using the following command:
    sudo /opt/bluedragon-6.2/bin/StartBlueDragon.sh

At this point, the next step is to make sure it actually works. The BD installation script places an index.cfm file in the root of the Web folder (i.e., /var/www/index.cfm). Point your Web browser at http://localhost/index.cfm, and you should see the results rendered as processed CFML (not as CFML source). I also tested my installation by copying /var/www/index.cfm into my user account’s local Web folder:

cp /var/www/index.cfm ~/public_html/index.cfm

and pointing my browser at that folder to make sure that the server would appropriately process CFML files there.

Configuring BD to Run as a Non-root User

For obvious security reasons, we don’t want the BD server to be running as root, so we need to create a group and user for the BD server, and then change the ownership of the BD server files appropriately:

sudo groupadd bdragon
sudo useradd -d '/opt/bluedragon-6.2' -c 'BlueDragon CFML Server' -s /bin/sh -g bdragon bdragon
sudo passwd -l bdragon
sudo chown -R bdragon.bdragon /opt/bluedragon-6.2

Automating Startup/Shutdown

The BD installation script creates an “init” script for the BD server, placing it in /etc/rc.d/init.d/BlueDragon_Server. There are a couple of things that I had to do to that script to get it to work:

  1. That script references a file /etc/rc.d/init.d/functions which does not exist on (at least my) Ubuntu boxes. Comment out that line.
  2. Add a line setting a variable that specifies the user under whose identity the server is to run.
  3. Tweak the lines that start and stop the BD server, to specify that you want the process run as the user ‘bdragon’ that you created above. My startup script looks like this. (Note: ‘daemon’ was not installed by default on my system, but is available for installation via synaptic.):
    #!/bin/sh
    # Startup script for the BlueDragon Server
    #. /etc/rc.d/init.d/functions
    bdstart=" /opt/bluedragon-6.2/bin/StartBlueDragon.sh "
    bdstop=/opt/bluedragon-6.2/bin/StopBlueDragon.sh
    prog="BlueDragon Server"
    bduser=bdragon
    
    start() { echo -n "Starting $prog: "; daemon -u $bduser $bdstart ; echo ; RETVAL=$? ; return $RETVAL ; }
    stop() { echo -n "Stopping $prog: "; daemon -u $bduser $bdstop  ; echo ; RETVAL=$? ; return $RETVAL ; }
    case "$1" in
    start) start& ;;
    stop) stop  ;;
    restart) stop; start ;;
    *) echo $"Usage: $prog {start|stop|restart}"
    exit 1
    esac
  4. For consistency with the rest of the system startup/shutdown stuff on my system, I copied the modified script to the directory with the rest of the system files:
    sudo cp /etc/rc.d/init.d/BlueDragon_Server /etc/init.d
  5. The last piece then is to establish the symbolic links from the various run-level folders to the startup/shutdown script I placed in /etc/init.d — this is discussed within the BD installation manual (see section 4.2.3, “Startup and Shutdown Automation on Linux”, p. 15). I chose to mimic the configuration of the Apache installation for these links for the various run-levels:
    sudo ln -s /etc/init.d/BlueDragon_Server /etc/rc0.d/K95bluedragon
    sudo ln -s /etc/init.d/BlueDragon_Server /etc/rc1.d/K95bluedragon
    sudo ln -s /etc/init.d/BlueDragon_Server /etc/rc2.d/S95bluedragon
    sudo ln -s /etc/init.d/BlueDragon_Server /etc/rc3.d/S95bluedragon
    sudo ln -s /etc/init.d/BlueDragon_Server /etc/rc4.d/S95bluedragon
    sudo ln -s /etc/init.d/BlueDragon_Server /etc/rc5.d/S95bluedragon
    sudo ln -s /etc/init.d/BlueDragon_Server /etc/rc6.d/K95bluedragon

After all of that, I could restart my system, sign in, and successfully invoke one of my test CFM pages.

Configuring BD to see MySQL

Out of the box, BD is not configured to be able to connect to MySQL datasources. The BD installation manual touches on this (see Section 3.4, p. 7), and points you to an entry within the New Atlanta BD FAQ with instructions on how to configure BD to provide support for MySQL.Those installations instructions, in summary, are as follows:

  1. Download the version 3.0.x version of the MySQL Connector/J package from the MySQL site. As of this writing, that file is mysql-connector-java-3.0.17-ga.tar.gz. (Note: MySQL does have a 3.1-series of the Connector/J product available, but the BD FAQ entry points the reader to the 3.0-series, and Dave Epler has indicated that he was unable to get the 3.1-series to work when he tried it.)
  2. Open the downloaded .tar.gz file, and extract just the mysql-connector-java-3.0.17.jar file.
  3. Copy that file to the appropriate location, per the above entry from the BD FAQ:
    sudo cp mysql-connector-java-3.0.17-ga.jar /opt/bluedragon-6.2/lib/mysql.jar
    sudo chown bdragon.bdragon /opt/bluedragon-6.2/lib/mysql.jar
  4. Restart BD. The BD administrator should now have an entry in the list of available datasource types for MySQL.

Applying the BD Server Hotfix

The hotfixes that NewAtlanta makes available are cumulative, so all you need to do is grab the most recent (August 2005, as of this writing) and apply it. The hotfixes themselves come with readme files and instructions; take the time to read through them. Having said that, here are the steps I took to apply the August 2005 hotfix (after unpacking the downloaded file in a folder named /home/ron/Downloads/BlueDragon/tmp):

sudo daemon -u bdragon /opt/bluedragon-6.2/bin/StopBlueDragon.sh
cd /opt/bluedragon-6.2/lib
sudo cp BlueDragon.jar BlueDragon.jar.20051122
sudo cp /home/ron/Downloads/BlueDragon/tmp/BlueDragon.jar ./
sudo chown bdragon.bdragon *
cd ../bin/apache
sudo mv mod_servletexec.so mod_servletexec.so.20051122
sudo cp /home/ron/Downloads/BlueDragon/tmp/mod_serveltexec.so ./
sudo chown bdragon.bdragon *
sudo daemon -u bdragon.bdragon /opt/bluedragon-6.2/bin/StartBlueDragon.sh

More to come…

  • Issues and Questions…

Credits

I can take credit for very little of this — all I have done is take my notes and turn them into this post. Much of the credit has to go back to Dave Epler, and I am grateful for his help and guidance. Credit also has to go to the folks at New Atlanta for the quality of their documentation for their BlueDragon server product and their willingness to make a free version of it available to developers.