If you've thought about using Slash for a personal project, read this first, and learn from Paul's frustrations and do-overs.
Every academic department at the Institute of Technology, Carlow, Ireland, is required to perform an externally validated Programmatic Review every five years. In a nutshell, the review is designed to examine the workings of the department and their effectiveness, plus provide answers to questions such as:
Are our courses industry relevant?
Are our courses up-to-date?
What do we do well?
What could we do better?
The Department of Computing, Physics and Mathematics, of which I'm a member, currently is working on such a review. The biggest problem to date has been organizing meetings that involve over 30 staff members. Due to timetabling constraints, not everyone can attend every meeting without canceling classes. Short meetings often turn into long debating sessions. And, of course, there's the problem of having everyone sit in on a meeting that may cover topics of no particular interest to them. What starts out as a meeting to discuss assessment methods turns into a debate about preferred programming languages or operating systems. Holding large, department-wide gatherings has tended to be counterproductive, and reaching consensus on important issues is difficult, if not impossible. Of course, smaller “everyone interested in this topic” meetings are common, and e-mail is used to solicit opinion and ideas. However, no common mechanism exists to collect and collate the various opinions being expressed or decisions being made. On top of everything, we are struggling to work under a strict deadline.
The crux of the problem was the synchronous nature of the traditional department meeting was working against us. What our particular environment needed was an asynchronous medium that would allow staff to interact with one other when it suited them, to have their opinions heard and—critically—recorded, and to provide a focus for moving the Programmatic Review forward. This realization lead me to Slash.
Most of you probably are already familiar with Slash. It is the GPLed system that runs Slashdot, the global geek news site. I rarely visit Slashdot, preferring to check Use Perl every day for gossip about Perl. Both sites, as well as many others, use the Slash system. My idea was to take Slash, install it locally and then use it in support of the department's Programmatic Review activities.
For the remainder of this article, I describe the process I went through to get Slash working. As you'll see, it was not all plain-sailing, and I made some mistakes along the way. In documenting what I did, it is my hope that, should you find yourself needing to install Slash, you can learn from my experience.
There are seven steps to installing Slash.
Step 1: Install a Database Backend
Slash requires a database backend. At the present time, MySQL is the best supported database technology (with support for PostgreSQL under development). My target platform was an aging Apple Macintosh G3 Server, running release 2.3 of YellowDogLinux, a PowerPC distribution based on Red Hat. Prior to this, I'd never run a database on this server, so my first order of business was to get MySQL installed and configured. Luckily, the various MySQL RPMs were already in place, so all I had to do was switch on the MySQL dæmon with a few chkconfig commands (issued as root). These commands installed and configured the appropriate MySQL startup scripts into my boot sequence:
chkconfig --add mysqld
chkconfig mysqld on
The Slash documentation suggests adding two lines to the script that executes MySQL, which is /usr/bin/safe_mysql on my system. As root, I used vi to add these two lines to the start of the file:
TZ=GMT
export TZ
A quick reboot confirmed that MySQL was installed and executing on the server. As this was the first time I'd executed the MySQL server, I issued the following command at the Linux prompt, setting the MySQL root password to one of my choosing:
mysqladmin -u root password 'passwordhere'
It is now possible to securely access the MySQL Monitor command-line utility with the following command, providing the correct password when prompted:
mysql -u root -p
With MySQL ready, I used the Linux adduser command to create a user, called slash, that would own the MySQL database used by Slash. This may not have been necessary, but I did it in case I was asked to identify an “owner” during the installation of the Slash system.
From MySQL Monitor, I created a database for my Slash system, as well as a MySQL user called slash, granting all privileges on the newly created database to this user:
mysql -u root -p
mysql> create database PROGREVIEW;
mysql> use mysql;
mysql> grant all on PROGREVIEW.* to slash identified by 'passwordhere';
mysql> quit
Note that user slash is created within MySQL as a side-effect of granting these privileges. By the way, the Slash documentation recommends granting all privileges on the database. This may not suit you (or your database administrator), so be sure to check the Slash README/INSTALL documentation for the minimum set of database privileges.
In working with and testing MySQL, I received some strange authentication errors. I used MySQL Monitor to investigate and noticed that the user table in the database had a number of rows with empty user-ids. I deleted these rows from the table, and the authentication errors went away. Here are the commands I used:
mysql -u root -p
mysql> use mysql;
mysql> select * from user;
mysql> delete from user where User = '';
mysql> quit
MySQL now was ready to go.
Step 2: Install Apache/mod_perl
Next up was the installation of Apache with support for mod_perl. Again, my YellowDogLinux was not running either of these services and, unlike MySQL, neither of them were in place. Rather than download their source tarballs, I opted to download and install the prebuilt and preconfigured binaries from the YellowDogLinux FTP server. This process is automated by the apt-get system, which should be familiar to Debian and SuSE users. Red Hat users have a similar tool, called up2date.
The following commands (issued as root) downloaded, installed and configured these services:
apt-get install apache
apt-get install mod_perl
chkconfig --add httpd
chkconfig httpd on
I then edited the Apache configuration file located at /etc/httpd/conf/httpd.conf and uncommented the following lines to enable mod_perl:
<IfModule mod_perl.c>
Alias /perl /var/www/perl
<Directory /var/www/perl>
SetHandler perl-script
PerlHandler Apache::Registry
Options +ExecCGI
</Directory>
</IfModule>
Another quick reboot confirmed that Apache was running on the system. I used a small Perl program from Chapter 4 of my book (see Resources) to display the headers Apache returned:
./wwwb HEAD localhost /index.html
This step produced the following output:
HTTP/1.1 200 OK
Date: Thu, 30 Jan 2003 10:29:53 GMT
Server: Apache/1.3.27 (Unix) (Yellow-Dog/Linux) mod_perl/1.24_01
Last-Modified: Tue, 24 Dec 2002 07:46:41 GMT
ETag: "11b5-933-3e0810e1"
Accept-Ranges: bytes
Content-Length: 2355
Connection: close
Content-Type: text/html
The Server: line of this output confirms that Apache is running with version 1.24 of mod_perl enabled. I was not looking forward to building Apache/mod_perl from source, and now it looked it wouldn't be necessary. The Slash documentation did advise that certain Apache/mod_perl setups don't work well with Slash, but I decided to try, resigning myself to the fact that building Apache/mod_perl from source would be necessary if I ran into trouble.
Step 3: Install Perl
Slash, which is written entirely in Perl, recommends version 5.6.1 of the language. YellowDogLinux comes configured with the 5.6.0 release. To upgrade, I decided to let the CPAN module update Perl for me, something it can do automatically. As root, I fired-up the CPAN shell and asked the system to install the CPAN bundle. This not only installed the latest CPAN module, but also downloaded, compiled and installed release 5.8.0. of Perl:
perl -MCPAN -e "shell"
cpan> install Bundle::CPAN
cpan> quit
If this is the first time you've used the CPAN shell, you will be asked to provide some initialization settings. Provide answers to the questions as posed. If something goes wrong or if you make a mistake, press Ctrl-C to abort the initialization, then issue this command to restart it:
cpan> o conf init
With the latest Perl in place, I reset the machine again (just to be safe).
Step 4: Install Bundle::Slash
Slash requires the installation of 32 third-party Perl modules. The Slash documentation warns that zlib and expat need to be installed prior to the installation of some of the required modules. I queried the RPM database to confirm this was indeed the case:
rpm -q zlib
rpm -q expat
Refer to Resources at the end of this article for the zlib and expat web sites, should these technologies not be installed on your system.
Now, if you're a masochist with not much else to do, you can install each of the required Perl modules by hand, downloading them from your nearest CPAN. Alternatively, use the CPAN shell to install the Bundle::Slash distribution, which does it all in one go. This is what I did:
perl -MCPAN -e "shell"
cpan> install Bundle::Slash
cpan> quit
I ended up babysitting this entire process, as the bundle required me to respond to a number of prompts from various modules. So you know, the download and installation process for all of these modules takes quite a while. The most important piece of information to remember while installing this bundle is the value assigned to the virtual user name, because the DBIx::Password module prompts for it. This value is required while installing the Slash source code. Any alphanumeric string will do, and I choose “Programmatic”. The DBIx::Password module installation also prompted for details of my database and MySQL user name, and I provided answers to the prompts based on the values I'd chosen during Step 1. I was careful to check any messages displayed at the end of the bundle installation. A small number of modules had problems installing, so I had to install them by hand to resolve the difficulties.
With the installation of this bundle complete, I was ready to start installing the Slash source code.
Step 5: Install Slash
From www.slashcode.com I downloaded the latest source code by accessing the Current Slash quick link, which redirects to SourceForge. From this location, I downloaded slash-2.2.6.tar.gz, then started the install with the familiar set of commands:
tar zxvf slash-2.2.6.tar.gz
cd slash-2.2.6
make
This produced an error: the Apache/ExtUtils.pm module could not be found, and the make aborted. This was not one of the 32 required Perl modules, so I fired-up CPAN to fetch and install it, as follows:
perl -MCPAN -e "shell"
cpan>install Apache::ExtUtils
cpan>quit
To my complete surprise, this resulted in version 1.27 of mod_perl being installed (in support of Apache::ExtUtils). I was even more surprised when the installation asked me for the location of my Apache source. The problem was I didn't have one, as I'd installed Apache from its binary RPM file. In order to try and continue, I opened up another console terminal, used lynx to surf to the Apache web site and downloaded the 1.3.27 release. I unpacked the tarball in a temporary directory, and then fed this directory location to the mod_perl install. I crossed my fingers.
I then was asked if I wanted to use this source to build mod_perl. The default response was y, so I choose yes. I then was asked if I wanted to build httpd from the same sources. The default response was again y. I went ahead and choose yes, although, to be honest, I was a little worried at this stage about what actually was going happening.
After a relatively quick compile, the installation of the module (and, I'm assuming, mod_perl and Apache) was complete. I quit the CPAN shell and retried the make from the Slash source code directory.
This time things went somewhat smoother, until the installer tried to copy some files into a protected location, realized it was not running as root and bombed out again. Of course, the Slash README and INSTALL documents had told me to do everything as root. So it was my own fault that this occurred, because I was logged in under my regular user-id. I tried make again as root.
I got even further into the make but bombed out again, this time because certain header files were missing. To my horror, upon inspecting the generated error messages, it appeared that the system was referencing Perl 5.6.0 and not the upgraded 5.8.0 release. Indeed, perl -v confirmed that release 5.6.0 was running. I issued the whereis perl command and was told that Perl existed in both /usr/bin/perl and /usr/local/bin/perl. The former was the 5.6.0 executable, and the latter was the executable for the 5.8.0 release. I could fix this by turning /usr/bin/perl into a link to /usr/local/bin/perl. Having just installed a large collection of Perl modules, though, I was unsure whether they had been installed into release 5.6.0 or 5.8.0 of Perl, so I was concerned. I executed the appropriate ln command, then ran make again.
To my relief, this time make appeared to work fine. I held my breath and typed:
make install
After a long series of messages, the “Thanks for installing Slash” line appeared on screen. One final task was to add an Include of the generated slash.conf file to the bottom of Apache's httpd.conf file. I was almost done.
Step 6: Installing the Slash Site
The initialization of the Slash site is straightforward. I entered these commands (note the use of the “Programmatic” virtual user name from Step 4):
cd /usr/local/slash
bin/install-slashsite -u Programmatic
Unfortunately, this command failed, complaining that DBIx::Password was not installed in the Perl 5.8.0 module paths. It appeared the modules from Step 4 had been installed for Perl 5.6.0 and not 5.8.0, so I reran the commands from Step 4. As the CPAN module had already downloaded all of the required modules for Perl 5.6.0 and stored them in its cache, they were all locally available to 5.8.0 as a result. This sped things up considerably.
Unfortunately, after installing the modules into Perl 5.8.0, my troubles still were not over. When I restarted Apache, the httpd startup failed, displaying errors relating to missing Perl modules in the 5.6.0 paths.
Then it struck me: the RPM binary for mod_perl was compiled for use on YellowDogLinux, and YellowDogLinux assumes Perl 5.6.0 is installed, as does the mod_perl RPM. Although I'd upgraded to Perl 5.8.0, mod_perl was still Perl 5.6.0. The true extent of the folly of relying on RPM binaries was becoming clear to me.
I removed the Slash Include line from the httpd.conf file, started Apache and checked which version of mod_perl was running. It was still 1.24, even though as part of Step 5 it appeared that version 1.27 of mod_perl has been built and installed. It had been, of course, but not in the same directory structure as the older Apache/mod_perl installation supported by YellowDogLinux.
I removed all trace of YellowDogLinux's Perl 5.6.0 from the system with this command:
rpm -e --nodeps perl
then removed mod_perl as follows:
rpm -e mod_perl
This also removed the Apache executable from the system. There was nothing for it: I'd have to backtrack to Step 2 and install Apache/mod_perl from source. I went to the Apache web site and downloaded the source for release 1.3.27, then popped over to the mod_perl web site and downloaded the 1.27 release. I put these files into my “things to install” directory, then issued the following commands to install Apache/mod_perl:
cd /home/barryp/toinstall
tar zxvf apache_1.3.27.tar.gz
tar zxvf mod_perl_1.27.tar.gz
cd mod_perl_1.27
perl Makefile.PL APACHE_SRC=../apache_1.3.27/ \
DO_HTTPD=1 USE_APACI=1 PERL_MARK_WHERE=1 \
EVERYTHING=1 APACHE_PREFIX=/usr/local/apache/
make
make test
su
make install
Ctrl-D
To be safe, I re-ran the commands from Step 5, and everything appeared to go well.
I was prompted for a number of values during the now successful execution of the install-slashsite program. I identified the hostname of the Slash server as well as the user and group under which Slash would run (I opted to stick with the suggested “nobody”). A list of plugins was displayed, and I was given the chance to add/remove them from the list. I choose to keep the default set of plugins. When asked if I wanted to install these files as symlinks, I again went with the default response and choose yes. For the site administrator username I entered slash and then provided an appropriate password and valid e-mail address. The final message from the install-slashsite program again suggested changes to be made to the Apache httpd.conf file.
It was now time for the moment of truth.
Step 7: Give It a Whirl!
I stopped and started the httpd dæmon (restarting is not enough) and then started the /etc/init.d/slash dæmon. From another machine, I typed in the URL of my just-installed Slash system. After a short pause, up popped my Slash site. From the opening page I logged in as the slash user, clicking on the backSlash hyperlink to access the administrator options. I was up and running.
Although it is possible to start working with Slash right away, I'd recommend reading the included Slashguide, which is found in the Docs directory or by clicking Help from the main Slash menu. There's enough in this document to get you started on the road to changing the way your Slash site looks and operates. After that, it's a case of advertising your site's existence and letting your users at it.
I tested these instructions on Red Hat 8 and initially had problems with the pre-installed Apache 2. When I downgraded to the 1.3.27 version of Apache/mod_perl, things worked perfectly. The only downside was the resulting system was as slow as molasses. This slowness had more to do with the fact that Red Hat 8 was running on my two-year-old laptop, configured with 64MB of RAM (well below the recommended minimum for Slash) than anything else. On top of this, I tested the system from localhost using the Mozilla browser, which did not help matters.
I could not have made it through the install and configuration of MySQL without a copy of my trusty reference, MySQL, written by Paul DuBois and published by New Riders, 2000.
The source code for wwwb is part of the bundle.
Paul Barry lectures at The Institute of Technology, Carlow in Ireland. His first book, Programming the Network with Perl, was published in February 2002, by Wiley. His next book, Bioinformatics, Biocomputing and Perl, is a collaboration with Michael Moorhouse. It is due to be published in late 2003, again by Wiley.
