Tuesday, May 19, 2009

Setup TWiki 4.3.1 on Ubuntu for newbie

Today, I have to setup a demo version of TWiki for R&D devision. It is used as a new channel for centralizing information of all technical staff.

I choose the latest TWiki version (4.3.1) to deploy. Actually, I am very disappointed with the configuration guideline on this version. I follow up all steps there but it takes to many problems.

After solving all of them, I decide to write another installation guide version here (for newbie and stupid one - like me).
My environment:
+ Ubuntu 9.0.4
+ Apache 2.2
+ Perl 5.0

TWiki is developed in Perl. However, you do not need to install Perl on Ubuntu 9.0.4 because it has a built-in installation of Perl there.

Step 1: install Apache Perl mod
You need to install the following package
sudo aptitude install libapache2-mod-perl2

After this, restart Apache: service apache2 restart (this command is only used in Ubuntu 9.0.4)

Step 2: Download TWiki and copy to installation folder

+ Download TWiki (4.3.1)
+ Unzip it and rename it to twiki
+ Copy to /var/www/twiki folder. Actually, you can change the location, but please follow this because it helps us reduce complexity in later steps


Step 3: Change configuration files on TWiki
+ Go to /var/www/twiki copy twiki_httpd_conf.txt to /etc/apache2/ (I installed Apache in this location). Rename this file to: twiki.conf
+ Open twiki.conf, go to this section:

AllowOverride None
Order Allow,Deny
Allow from all
Deny from env=blockAccess

Options ExecCGI FollowSymLinks
SetHandler cgi-script

# Password file for TWiki users
AuthUserFile /var/www/twiki/data/.htpasswd
AuthName 'trandangkhoa'
AuthType Basic
...

Change AuthName value by a username in your .htpasswd file. To create this file, please use htpasswd command on Ububtu.

Go to another section:

SetHandler cgi-script
Order Deny,Allow
Deny from all
Allow from 127.0.0.1 192.168.1.10
Require user trandangkhoa
Satisfy Any


Change value of Require user with the name same as above step.

+ Open: /etc/apache2/apache2.conf and add below line into the end of this file:
Include /etc/apache2/twiki.conf

After this, restart Apache: service apache2 restart

Step 4: Create the file LocalLib.cfg located as twiki/bin/LocalLib.cfg

+ There is a template for this file in twiki/bin/LocalLib.cfg.txt. Simply copy LocalLib .cfg.txt to LocalLib .cfg. Make sure the ownership and access rights of the copy are the same as LocalLib .cfg.txt

+ The file twiki/bin/LocalLib.cfg must contain a setting for $twikiLibPath, which must point to the absolute file path of your twiki/lib e.g. /var/www/twiki/lib.

Step 5: Fix TWiki error with Unicode path
Open /var/www/twiki/lib/TWiki/Render.pm file:(you must change the mode of this file to edit - it is read-only by default)
1. Remove this line:
use Unicode::String qw(utf8 latin1 utf16be);
2. Replace the following two lines:
my $utf8AnchorName = Unicode::String->new($anchorName);
    $anchorName = $utf8AnchorName->substr(0, 32);
with this line:
$anchorName =~ s/^(.{32})(.*)$/$1/; # limit to 32 char

Step 6: Change access mode for files/folders in twiki

+ Change owner for the twiki folder:
chown -R www-data:www-data /path/to/twiki 
(Note: in order to see www-data you may need to modify root's /apps/gnome-system-tools/users/showall GConf setting; see GConfEditor)

+ Change access mode (this step is VERY IMPORTANT)
cd /var/www/twiki


find . -type d -print -exec chmod -v 755 {} \;
find data -name '*.txt' -type f -exec chmod -v 644 {} \;
find data pub -name '*,v' -type f -exec chmod -v 444 {} \;
find lib -type f -exec chmod -v 444 {} \;
find locale -type f -exec chmod -v 444 {} \;
find pub -type f -exec chmod -v 644 {} \;
find bin -type f -exec chmod -v 555 {} \;
find bin/logos -type f -exec chmod -v 444 {} \;
find templates -type f -exec chmod -v 444 {} \;
find tools -type f -exec chmod -v 555 {} \;
chmod -v 644 lib/LocalSite.cfg
chmod -v 644 data/.htpasswd
chmod -v 644 data/mime.types
chmod -v 644 bin/LocalLib.cfg.txt bin/.htaccess.txt
chmod -v 444 bin/setlib.cfg
chmod -v 444 tools/extender.pl
chmod -v 444 working/tmp/README working/README working/registration_approvals/README working/work_areas/README
chmod -v 660 working/.htaccess
chmod -v 444 AUTHORS COPYING COPYRIGHT index.html INSTALL.html LICENSE pub-htaccess.txt readme.txt robots.txt root-htaccess.txt subdir-htaccess.txt TWikiHistory.html twiki_httpd_conf.txt TWikiReleaseNotes04x02.html

Step 7: Setup TWiki settings
Open this link on your web browser http://localhost/twiki/bin/configure




In the Store Settings section, choose: RCSLite for StoreImpl

At the next step, TWiki will ask you to type password for doing configuring in the future.





After this step, you can go to the home page of TWiki:
http://localhost/twiki/bin/login/Main/WebHome

Done!
All above steps are just the fundamental steps that you can set up TWiki in an easiest way.

If you want to do more thing, please read its manual document.

It takes me over 2 hours to fix all problems with TWiki deployment. I hope this helps you also.