HOWTO: Installing Slash for a Private
Project
Posted on Wednesday, February 26, 2003
by Paul Barry |
 
|
|
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.
Red Hat 8 Footnote
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.
Resources
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.
The SLASH web site
The Perl web site
The CPAN Repository
The zlib web site
The expat web
site
The Apache web site
The mod_perl web site
Slashdot
Use Perl
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. |
