TWiki

Introduction

TWiki is a flexible, powerful, and easy to use web-based collaboration platform.

Purpose

Getting a TWiki server installed on your gentoo box.

• twiki-4.0.5

References

• /usr/share/webapps/twiki/4.0.5
• TWiki install guide

Installation

Emerge

Make sure you have apache2 selected in your USE flag.

 emerge --info | grep apache

Find out if twiki is masked package

emerge --pretend twiki

If it is, then add it to /etc/portage/package.keywords. (It is probably best to specify the version to unmask so that world upgrades stick to stable versions only)

echo "www-apps/twiki ~x86" >> /etc/portage/package.keywords
echo "virtual/perl-CGI ~x86" >> /etc/portage/package.keywords
echo "perl-core/CGI ~x86" >> /etc/portage/package.keywords

Once the pretend emerge is successful, check that there are no surprises and then:

emerge twiki

If you installed a bunch of dependencies in the emerge then you might want to check if any config files need updating before moving on:

etc-update

Webapp-config

The following message is printed by portage after emerging twiki:

* 
* If you are upgrading from an older version of TWiki, back up your
* data/ and pub/ directories and any local changes before upgrading!
* 
* You are _strongly_ encouraged to read the upgrade guide:
* http://twiki.org/cgi-bin/view/TWiki/TWikiDocumentation
* 
* webapp-config will not be run automatically
* Run webapp-config -I -h <host> -d twiki twiki 4.0.4-r1 to install
*

Installing TWiki is a two step process. The emerge discussed in the previous section will install a set of master files in /usr/share/webapps/twiki/4.0.5/ (in addition to any missing dependencies), but then you need to run something called webapp-config to install the twiki files that will be served by apache. The installation is set up like this to allow for virtual hosting (serving two or more websites from the same server). Look to the webapp-config manual for more infomation:

man webapp-config

If you don't want to do virtual hosting (or don't know what it means) then you can leave out the "-h <host>" option (it will use "localhost" as default) and so run the command:

webapp-config -I -h localhost -d twiki twiki 4.0.5

This will give the following post-install instructions:

0. You will need to manually adjust permissions for the installation script to run:

$ chown -R apache:apache /var/www/localhost/htdocs/twiki

When you're done with the installation, don't forget to make sure that only 
the data/ and pub/ directories are writeable by the webserver!!!

1. Review /var/www/localhost/htdocs/twiki/bin/LocalLib.cfg and make sure all 
paths are set correctly

2. Take a look at twiki_httpd_conf.txt and modify your Apache configs as
needed. Make sure your webserver can execute /var/www/localhost/htdocs/twiki/
bin/configure
Pay attention to the ExecCGI option (see https://bugs.gentoo.org/134132).

3. Visit http://localhost/twiki/bin/configure
Most values should have been automatically set for you.

4. Read the install guide
http://twiki.org/cgi-bin/view/TWiki/TWikiDocumentation

============================================================================

If you are upgrading:

Follow the manual upgrade procedure as described on
http://twiki.org/cgi-bin/view/TWiki/TWikiDocumentation

Lets look at these in turn:

0. This is necessary (assuming apache is being run as the user apache) for TWiki to be able to actually save configurations and store pages.

1. paths should be OK already

2. The settings in /var/www/localhost/htdocs/twiki/twiki_httpd_conf.txt should be OK. However, if you are not running PHP (you don't need it for TWiki) then comment out the line saying "php_admin_flag engine off". To edit the file use:

nano /var/www/localhost/htdocs/twiki/twiki_httpd_conf.txt

To search for the correct line in nano, use the search command with control-w, then type "php_admin" and hit enter. Also, if you want to restrict access to your TWiki (either permanently or temporarily, while you get it set up), you will want to alter the <Directory> statements in this file. When you are finished editing twiki_httpd_conf.txt, save it as twiki_httpd.conf. Finally, the file must be referred to in /etc/apache2/httpd.conf so that apache can find it. One method is

echo "Include /var/www/localhost/htdocs/twiki/twiki_httpd.conf" >> /etc/apache2/httpd.conf

An alternative is to keep the twiki configuration file separate. You can link or drop it into one of the *.d files under /etc/apache2/, e.g., naming it /etc/apache2/modules.d/80_twiki.conf .

The webserver should be able to execute configure already - to check use the command:

ls -l /var/www/localhost/htdocs/twiki/bin/configure

and check that the permissions allow for execution (e.g. -rwxr-xr-x). Also, bug 134132 seems to have been resolved and so is no longer an issue.

3. Start the Apache server with:

/etc/init.d/apache2 start

If you see any errors here then apache probably didn't start and you'll need to troubleshoot them before being able to access anything. Be careful---apache sometimes is quiet when there are errors, but still does not start. You can find out if you point your browser to http://localhost/twiki/bin/configure to run the configure script, which you need to do anyway.

Testing it

1. /etc/init.d/apache2 stop
2. /etc/init.d/apache2 start
   • If the hostname is "mygentoobox", then check the url http://mygentoobox/twiki/

Troubleshooting

I was getting a "too many failures to send email" error when trying to register my first user. This was a problem with ssmtp (the email program that was automatically emerged as a dependency of twiki). The issue was solved by setting the mailhost (e.g. mailhub=mail.my.company.com) in /etc/ssmtp/ssmtp.conf file.

The emails sent have the 'from' address as "added by portage for apache <apache@leviathan.lbl.gov>". This is the apache user name as it appears in /etc/passwd; change this if necessary to something more suitable.

> Uncomment the line #FromLineOverride=YES in /etc/ssmtp/ssmtp.conf

>If using the famous FormmailScript you need to edit the following line:

"print MAIL "From: $Config{'email'} ($Config{'realname'})\n";"

to read:

"print MAIL "From: $Config{'email'} ($Config{'email'})\n";"