Yawns: Yet Another Weblog/News Site

• Introduction
• Documentation
• Download
• FAQ

Installing Yawns on Debian Sarge

This document describes installing Yawns upon a Debian GNU/Linux system - using the Sarge release. The hostname used throughout this example is 'yawns.my.flat' (IP address 192.168.1.202) which is a pristine instance of Debian Sarge running under Xen.

If you're in a hurry and you have a pristine installation of Sarge you can try to use the automated-installer which will complete all the steps described upon this page. However this is still new so there might be a few errors:

• Yawns installer for Debian Sarge

Initial Setup

First install the major requirements: MySQL and Apache2, along with the CVS binary so that we can checkout the code from the CVS repository:

yawns:~# apt-get install mysql-server cvs apache2 make

We'll also install the Perl DBI module to talk to the database, along with Danga's Memcached.

(Memcached is a fast in-memory cache with a number of clients for different languages. We use it to cache database accesses intelligently, as described in the article speeding up dynamic websites with caching.)

yawns:~# apt-get install libdbd-mysql-perl libdbi-perl 
yawns:~# apt-get install memcached libcache-memcached-perl

Apache Setup

Make a new web directory to contain the installation, and checkout the latest code into it.

I tend to store sites beneath /home/www. You might have a preferred location, and you're welcome to use that, but I'll use /home/www as the installation prefix in this guide:

yawns:~# mkdir -p /home/www
yawns:~# cd /home/www

yawns:/home/www/# cvs -d :pserver:anonymous@cvsrepository.org:/home/cvs login
Logging in to :pserver:anonymous@cvsrepository.org:2401/home/cvs
CVS password:  Empty Password / Just press return

yawns:/home/www#  cvs -d :pserver:anonymous@cvsrepository.org:/home/cvs  co yawns

Now that you have the code checked out into the yawns/ subdirectory we'll create some canonical directories that Apache can use:

yawns:~# mkdir /home/www/logs
yawns:~# ln -s /home/www/yawns /home/www/htdocs

This gives us the following structure:

yawns:~# ls -l /home/www/
lrwxrwxrwx   1 root staff   15 Apr  3 19:06 htdocs -> /home/www/yawns
drwxr-sr-x   2 root staff 4096 Apr  3 19:08 logs
drwxr-sr-x  16 root staff 4096 Apr  3 19:25 yawns

Following the style of the Debian Apache2 packages we will now create the Apache virtual host configuration file /etc/apache2/sites-available/yawns with the following contents:

<VirtualHost *>
        ServerName   yawns
        ServerAlias  yawns.my.flat

        DocumentRoot /home/www/htdocs/

        # To use CGI scripts outside /cgi-bin/:
        AddHandler cgi-script .cgi

        # Our site runs via one single .cgi file.
        DirectoryIndex index.cgi 

        # Add the mod_rewrite handlers.
        Include /home/www/htdocs/doc/rewrite.sample.conf

        # Document root.
        <Directory />
                Options -Indexes
                Options +ExecCGI

                # Overly permissive ..
                AllowOverride All  
        </Directory>
        
        # Logfiles
        ErrorLog  /home/www/logs/error.log
        CustomLog /home/www/logs/access.log combined
  </VirtualHost>

Once we've created the site configuration file we can make Apache use it after enabling the mod_rewrite module which Yawns uses. (This module is used to provide prettier URLs.)

Enable the module and the site as follows:

yawns:~# a2enmod rewrite
Module rewrite installed; 
run /etc/init.d/apache2 force-reload to enable.

yawns:~# a2ensite yawns
Site yawns installed; 
run /etc/init.d/apache2 reload to enable.

yawns:~# /etc/init.d/apache2 reload
Reloading web server config...apache2: 
done.

Database Setup

Now our Apache setup is complete, we just need to sort out the database stuff. Firstly we'll need to create the Yawns database, along with a username + password with which to access it.

For simplicity we'll choose the username + password of yawns - you should choose something different!

yawns:~# mysql --user=root -e CREATE DATABASE yawns'
yawns:~# mysql --user=root -e "GRANT ALL PRIVILEGES on \
  yawns.* to yawns@localhost IDENTIFIED BY 'yawns';"

yawns:~# cd /home/www/yawns/tables/
yawns:/home/www/yawns/tables# mysql --user=yawns --pass=yawns yawns < yawns.sql

Now we'll add two initial users to the Yawns database, one for ourself to administer the site, and the "Anonymous" user which is required:

yawns:~# mysql --user=yawns --pass=yawns yawns;
mysql> insert into users (username,password) VALUES( 'admin', MD5('admin') );
Query OK, 1 row affected (0.00 sec)

mysql> insert into users( username) VALUES('Anonymous' );
Query OK, 1 row affected (0.00 sec)

mysql> exit
Bye

The admin user that we've just added isn't a special user, to make it an administrator you should run the following command:

./admin/make-admin --username=admin

This will give the user complete administrative privileges, and from this point on you can administer the website via your browser.

Once this basic installation is complete you should also update the tables to their most recent versions, do this by running:

make db-migrate

Perl Module Installation

Now that we have setup our database and webserver we need to make sure we have all the required Perl modules installed.

We can run one of the site test cases to see which modules are not installed yet:

yawns:~# cd /home/www/yawns/
yawns:/home/www/yawns# perl tests/modules.t

The output of this test case will show you that many modules are missing, we can install them one-by-one:

# apt-get install liburi-find-perl libtext-diff-perl libwww-perl
# apt-get install libhtml-template-perl libmail-verify-perl
# apt-get install libhtml-fromtext-perl libcgi-session-perl

After this step we can re-run the test and see we're still missing some modules, and these are not available in Sarge's release. Add my backport repository and install them from there:

echo 'deb http://www.steve.org.uk/apt sarge main contrib non-free' >> /etc/apt/sources.list
echo 'deb-src http://www.steve.org.uk/apt sarge main non-free contrib' >> /etc/apt/sources.list

apt-get update

# This module is required
apt-get install libcgi-session-expiresessions-perl

# Formatting modules
apt-get install libtext-textile-perl libhtml-bbcode-perl

# These two modules are used for 'make test-output'
apt-get install libtest-tap-htmlmatrix-perl libtest-tap-model-perl

# This is for 'make test' + 'make test-verbose'
apt-get install libtest-file-perl

(These packages were created from CPAN sources following the method outlined in the building Debian packages of perl modules article.)

All module tests now pass except one. Oops.

The Yawns code makes use of a more recent version of the libcgi-session-perl package than that which is contained in Sarge, and this causes the test case to fail even though the module/package is installed.

To install a newer version, or backport, we can use the same apt-get repository which we installed the other modules from. In this case we're upgrading a module rather than installing it - so we can just run:

apt-get update
apt-get upgrade
The following packages will be upgraded:
     libcgi-session-perl

All our Perl modules should be installed and configured now. We can verify this by running the test case again:

cd /home/www/yawns
perl tests/modules.t
...
...
ok 130 - require strict;
ok 131 - require vars;
ok 132 - require warnings;
1..132

(No errors! W00t!)

Minor Setup

Now that the major configuration steps are complete we we just need to fix a couple of small things before we can customise the site to our liking.

Firstly we need to make sure the output RSS + Atom.xml file(s) are writable by our Apache user - since these will be updated automatically when new articles are published.

On Debian systems the Apache2 process runs as the www-data user, so you make the feeds writable to that user by running:

yawns:/home/www/yawns# make feeds
yawns:/home/www/yawns# chgrp www-data *.rdf *.xml
yawns:/home/www/yawns# chmod 664 *.rdf *.xml

(A less secure approach is just to run "chmod 777 *.rdf *.xml")

Secondly we need to update the list of Debian security advisories - since these are included in the index of our site.

yawns:/home/www/yawns# make security

     <h3 class="sideBarTitle">Security Advisories</h3>
     <!-- tmpl_include name="../includes/security.template" -->

*/30 *  *  *  *  perl /home/www/htdocs/admin/gen-security-pages > /home/www/htdocs/templates/includes/security.template

perl -pi.bak -e "s/debian-administration.org/yawns/g" conf/SiteConfig.pm

     /etc/init.d/memcached restart