Sunday, July 30, 2006

TWiki 4.0.4 setup on debian stable (sarge) HowTo.

Step by step guide for TWiki 4.0.4 setup on debian stable (sarge) 3.1-r2 - Fresh Install.
Enjoy.

-- Pre Install --

Start by downloading and installing debian stable.
I recommend you select linux26, it just sounds better.
Select "Web Server" from server roles during d-i.

# -- Post Install --

# We'll be installing some packages required by TWiki to run in apache2 cgi mode.
aptitude install libalgorithm-diff-perl
aptitude install libdigest-sha1-perl
aptitude install libmime-base64-perl
aptitude install libnet-perl
aptitude install libtext-diff-perl
aptitude install libcgi-session-perl

# Disable unneeded apache2 modules to increase security
cd /etc/apache2/mods-enabled && rm perl.* php4.* mod_python.load

# Configure your exim MTA to use smarthost (no local delivery)
dpkg-reconfigure -plow exim4-config

# Now looks like a good time create the soon to be twiki setup dir
mkdir /var/www/twiki

# -- TWiki setup --

cd /var/www/twiki
wget http://twiki.org/p/pub/Codev/Release/TWiki-4.0.4.tgz
tar xzvf TWiki-4.0.4.tgz

# Save original setup for future reference, good safty-net in case something borks.
mkdir /root/nondeb_install
mv TWiki-4.0.4.tgz /root/nondeb_install

# Set some config files, "the debian way". Well... almost
cd /var/www/twiki
mv root-htaccess.txt .htaccess
mkdir /etc/twiki && cd /etc/twiki
mv /var/www/twiki/twiki_httpd_conf.txt twiki.conf
sed -i -e 's@/home/httpd@/var/www@' /etc/twiki/twiki.conf

# Set proper permissions on twiki cgi runtime files.
chown -R root:www-data /var/www/twiki
chmod -R 750 /var/www/twiki/
chown -R www-data:www-data /var/www/twiki/pub/
chown -R www-data:www-data /var/www/twiki/data/

# Cool, lets link twiki.conf to apache2 main config
cd /etc/apache2/conf.d
ln -s /etc/twiki/twiki.conf twiki.conf

# -- TWiki configurations --

# Time to edit some config files.
# use either vi(m), gedit, nano, pico, emacs, ed or check Debian Reference - Editors
# I use sed to speed things up, this allows this whole HowTo to be step-by-step copy & run.

# Tell twiki script where it should look for his perl modules
mv LocalLib.cfg.txt LocalLib.cfg
sed -i -e '/twikiLibPath/ { s@/absolute/path/to/your/lib@/var/www/twiki/lib@ }' LocalLib.cfg

# And set apache to "by default" redirect to our twiki
# (This replaces the string "apache2-default" with "/twiki/bin/view/")
sed -i -e '/RedirectMatch/ { s@/apache2-default/@/twiki/bin/view/@ }' /etc/apache2/sites-available/default


# -- TWiki Security --

# Lets set apache and twiki to use basic authentication
htpasswd -c /var/www/twiki/data/.htpasswd USERNAME
chown www-data:root /var/www/twiki/data/.htpasswd
chmod 750 /var/www/twiki/data/.htpasswd

# We'll add a few lines to twiki.conf, making the server require valid-user

sed -i '/<Directory "\/var\/www\/twiki\/bin">/ a AuthType Basic\nAuthName "TWiki - Knowledge is Power"\nAuthUserFile /var/www/twiki/data/.htpasswd' /etc/twiki/twiki.conf

# -- Twiki web configurations --

# Let's access the web interface and configure the wiki
http://YOUR-SERVER.local/twiki/bin/configure

Things to pay attention to :

Security Setup >> Authentication >> {LoginManager} =TWiki::Client::ApacheLogin
Security Setup >> Passwords >> {PasswordManager} =TWiki::Users::HtPasswdUser
Security Setup >> Passwords >> {Htpasswd}{FileName} =/var/www/twiki/data/.htpasswd

# -- System cron --

# Let's have twiki mailing us at 2AM

echo '0 2 * * * root (cd /path/to/twiki/bin; ./mailnotify -q)' >> /etc/crontab

# -- User Setup --

We're almost there, the last thing you should do is educate yourself.

1. Read http://twiki.org/cgi-bin/view/TWiki/TWikiReferenceManual
2. Check http://twiki.org/cgi-bin/view/TWiki/WebHome
3. Play with the system before you take it into production.

My 2cent's :
1. The system uses rcs to store it's data (no rational db such as mysql & co.)
2. All system configurations are done from within the wiki itself, a somewhat new but interesting concept : You use the same interface to edit both the wiki pages & the wiki configuration files. Once you hit the "Save" button the change is applied, and the cherry on the cake is you get to use the same revision system to revert back if you mess something up with the config.


That's about all, enjoy your new wiki.
I hope this helps someone.
Maxim V.

Comments are welcome.