TWiki on Ubuntu - HOWTO Install on Feisty or Gutsy

Ubuntu is a very popular Linux distribution used by about 6 million people world-wide instead of Windows, on both desktops and servers.

It's very easy to install and run TWiki on Ubuntu: you only need to type one command to install everything, and when you upgrade Ubuntu, TWiki is upgraded as well.

TWiki 4.1.2, a recent version, is now available on Ubuntu with the release of Ubuntu 7.10 (Gutsy Gibbon) on 18 Oct 2007. Ubuntu 8.04 and 8.04.1 (Hardy Heron) has the same version of TWiki.

• You can install TWiki manually (see TWikiInstallationGuide and the Ubuntu forums HOWTO linked below). However, f you haven't installed TWiki before, I strongly recommend going with 4.1.2 using this TWikiOnUbuntu guide first!
• Try TWiki on Ubuntu without changing your Windows setup - you can reboot a Windows PC into an Ubuntu Live CD and try TWiki very easily, without installing anything on the hard disk. Just burn a copy of the Ubuntu Desktop CD, reboot from the CD, install two packages through the GUI, and you have a working TWiki 4.1.2 server! Nothing is saved to hard disk, so this is most useful to run a quick test.
• You can run TWiki on a web hosting site by using Ubuntu on a Virtual Private Server (VPS) - this is only recommended after you're familiar with Ubuntu and running a secure Linux server from the command line. See TWikiOnWebHostingSites for some discussion.

Getting into Ubuntu

If you are new to Ubuntu, and are using a desktop or laptop, I recommend trying the Ubuntu 8.04.1 Desktop Edition, as long as you have a Pentium III or better with 512 MB RAM. Or you can use Xubuntu 8.04.1, which needs only 200 MB RAM. The Desktop CDs for these versions can be used as Live CDs until you decide you want to install Ubuntu or Xubuntu to your hard disk, and the installer will preserve your Windows setup so you can dual-boot.

For server or very low memory installations, see below for tips on which Ubuntu to use.

Overview

Installing on Ubuntu 8.04, 7.10 or 7.04 ()

If you are using Ubuntu 7.10 (Gutsy) or 8.04 (Hardy), this one-line installation process installs TWiki 4.1.2, which is a recent stable version (Mar 07), with improved usability and easier plugin installation among other new features.

If you are using Ubuntu 7.04 (Feisty), this installation process installs TWiki 4.0.5, which is quite a recent version (Jan 07), and the latest 4.0.x available, including some bug fixes.

This is the easiest way to install TWiki - only if you can't use Feisty or Gutsy but really need the new features added in TWiki 4.1 or TWiki 4.2 should you use the manual install section below. It's quite possible to install TWiki manually later once you have some experience.

This process has been tested on Xubuntu 7.04 (Feisty) and 7.10 (Gutsy) but will work identically on any other Feisty or Gutsy flavour of Ubuntu, including Kubuntu, Xubuntu, and Edubuntu (and maybe other Ubuntu derivatives). TWiki runs quite nicely on older machines - I regularly use it on a Pentium III machine and a laptop with 192 MB RAM.

Upgrading from Ubuntu 7.04 to 7.10 -

If the twiki 4.0.5 package was installed on 7.04 (Feisty), it will automatically be upgraded with 7.10 (Gutsy) to TWiki 4.1.2. This is very easy - I just had to answer a question about which version of the /etc/apache2/twiki.conf file to use, and chose the new version from Gutsy. TWiki 4.1.2 is now running nicely.

Installing on Dapper or Edgy

TWiki has been packaged in Ubuntu since Dapper and Edgy, which included the older TWiki 3 (Sep 2004) version. If you can upgrade to Feisty, you'll get a much better TWiki version - if you aren't ready to upgrade, perhaps because you want Dapper's long-term support, see the manual install section below. To speed things up you can check the twiki package details in Feisty to get a list of packages (dependencies) that you will probably need to install to make TWiki 4.x work on Dapper or Edgy.

Credits

Enormous credit is due to:

• SvenDowideit and others who have worked on the twiki package for Debian GNU/Linux, which is the base from which Ubuntu is derived.
• The Ubuntu Masters of the Universe (MOTU) team who included twiki in Ubuntu

Installation steps

Step 1: Ensure that Universe is enabled in your package manager

You may need to enable the 'Universe' part of the Ubuntu repositories, which contains the twiki package - to do this, see the HOWTO on adding repositories, which includes screenshots.

Note that security updates for TWiki are not handled by the Ubuntu team, but by the TWiki project itself - so keep track of SecurityAlerts if you are going to use TWiki as a server.

Step 2: Update list of Ubuntu packages

This is just to ensure your system knows about the latest version of the required packages before installing TWiki.

Here's what to do for Ubuntu:

1. Open the terminal through the menus: Applications Accessories GNOME Terminal
2. Type sudo apt-get update into the terminal and hit Enter
3. Keep the terminal open for later steps

You will normally need to put in your own password to let sudo become root.

Step 1 is slightly different on Xubuntu (run the Terminal application from a different menu option and Kubuntu (run the Konsole application) - see TWikiOnUbuntuManualInstall for Kubuntu details.

If you prefer to do things through the GUI, use Synaptic or the Ubuntu Update Manager tool (Ubuntu or Xubuntu) and tell it to upgrade packages - this is normally running automatically, and the Adept equivalent is used by Kubuntu. These tools will also automatically alert you to important upgrades, so you may have already done this step.

Optional - upgrade Ubuntu packages

You are recommended to run this command:

sudo apt-get upgrade

This installs upgraded versions of any Ubuntu packages that are out of date, fixing security holes and other bugs, but this is not required to install TWiki. This may take quite a long time if you don't regularly do upgrades, but it's completely automatic - many people do an upgrade every day.

Step 3: Install Apache and TWiki the easy way

You only need to type one line to install TWiki on Ubuntu 7.04 or 7.10, or any Ubuntu variant. Type this, and confirm with 'yes' at various points if needed:

sudo apt-get install apache2 twiki

Once the installation process is complete, which may take quite a few minutes due to downloads and setup processing, TWiki is fully installed and working. Apache, RCS, Perl, and any other pre-requisites, including CPAN modules, are installed automatically.

• Apache 2 should start up on localhost so that it's accessible only from your Ubuntu system, not other network users. If you get an error, see next section on troubleshooting.

After the download and most of the installation process is done, you need to answer a couple of questions:

• Administrator email address - specify a working email address so that users can contact you. This will be published on TWiki pages with limited spam proofing only.
• Password for the TWikiGuest user - this is what you will use to log in to the TWiki configure tool under Ubuntu. If this is going to be a network accessible TWiki, choose a good password - if it's a personal TWiki it's not so important but still worth choosing something reasonable. You can add or change users later.

: If you don't specify anything (perhaps you are using a GUI such as Synaptic to install), the default userid is TWikiGuest, and default password is guest - this is only accessible to users on the same PC but change it if you need more security.

If you prefer to do things through the GUI, use the Add/Remove Programs tool, or Synaptic (Ubuntu or Xubuntu). On Kubuntu, use the Adept tool. Either way, search for apache2 and twiki in the tool and install both of them.

Troubleshooting - PHP error

If you don't have PHP installed, you may get an error on Apache startup - this is because TWiki's supplied twiki.conf config file for Apache turns off PHP processing for security reasons, not because TWiki requires PHP! To fix this, don't install PHP (unless you want it for some other application) - just edit the /etc/apache2/conf.d/twiki.conf file and comment out the line mentioning PHP. The exact line depends on your PHP version, but for PHP5 it should be like this

    # No need to disable PHP as it's not installed on this system
    # php_admin_flag engine off

Step 4: Make your TWiki network-accessible (if required)

For a personal TWiki, where you just want a Wiki on your desktop or laptop PC, you can skip this step.

If you are setting up TWiki as a server, whether on an intranet or the Internet, you will need to tell Apache to allow access to configure from a range of IP addresses.

• Before you enable network access, please check for any SecurityAlerts for TWiki, particularly for Internet use, and compare the latest TWiki.org version (TWikiProductionRelease) with the Ubuntu package (try aptitude show twiki to check version) - it's possible, though unlikely, that there's a vulnerability fixed by a hotfix for a TWiki.org security alert, but not yet fixed in the Ubuntu package. In that case, you'd need to apply the TWiki hotfix from the relevant security alert page(recommended approach), or install TWiki manually (see below).

The twiki package installation also ensures that a password is also required to access configure, but it's a good idea to restrict by IP address as well if possible.

1. Find out the IP address of the system or network that must be allowed to access TWiki (e.g. 10.0.0.0, network mask 255.255.0.0 is common on intranets)
2. Use an editor such as nano (or your favourite GUI editor such as gedit for Ubuntu or kate for Kubuntu) to make the following change:
   • Type sudo nano /etc/apache2/conf.d/twiki.conf to edit the TWiki config for Apache
   • On the Allow From line where by default a 192.168.x.x address is mentioned, change this to match your IP address and mask (e.g. 10.0.0.1 for just one PC, or 10.0.0.0/255.255.0.0 for the whole of a 10.x intranet) - see the Apache page on the host authorization module on how to do this. If you always use one PC to administer TWiki, just use that address (check ifconfig on Linux and ipconfig on Windows.) Some examples:

    # IP address, or range of addresses
    Allow from 10.1.2.3
    Allow from 192.168.1.104 192.168.1.205
    # IP address and mask, or address and CIDR prefix
    Allow from 10.1.0.0/255.255.0.0
    Allow from 10.1.0.0/16 

1. Restart apache: sudo /etc/init.d/apache2 restart

Step 5: Test your TWiki installation

Any URLs in this HOWTO that point to http://localhost should now point to pages on your newly installed TWiki (assuming you are installing on a desktop or laptop), so you can just click them from here.

Once the installation is done, you should be able to use your favourite web browser to surf to http://localhost/ which will redirect you automatically to http://localhost//cgi-bin/twiki/view. You can try editing a TWiki page in the Sandbox, e.g. http://localhost//cgi-bin/twiki/view/Sandbox/TestTopic.

Step 6: Finish configuring TWiki in a web browser

You will need to configure TWiki once it's installed:

1. To run the configure tool, click on http://localhost//cgi-bin/twiki/configure
   • The user is TWikiGuest, the password is whatever you specified during the installation
   • Typically you will want to set up SMTP settings so that TWiki can reach your SMTP server for email notifications
2. To configure site-wide preferences, click on http://localhost//cgi-bin/twiki/view/Main/TWikiPreferences - these override the main preferences at TWiki.TWikiPreferences.

For more information, see the main installation guide for TWiki: the latest version for TWiki 4.0 is on TWiki.org at TWiki04.TWikiInstallationGuide, or you can use your locally installed version here. The guide assumes you've done a manual installation so many steps are not needed, just skip to the part about configuring TWiki

Where things are

Apache configuration is in /etc/apache2 - the TWiki specific configuration is the twiki.conf file in the conf.d subdirectory. You can check the Apache log files in /var/log/apache2 - errorlog is the key one if you have any problems

TWiki's "home" is /var/lib/twiki - you can get to all the different TWiki directories for data, logs, pub (attachments/images) from there, although due to the way Ubuntu and Debian like to organise things, some of these subdirectories are actually "symbolic links" to other parts of the Ubuntu filesystem. Use ls -l to see the symbolic links.

Step 7: For TWiki servers on the Internet, or secure intranets (optional)

If you are installing TWiki on an Internet website (or a secure intranet), you need to consider security and anti-spam more seriously:

• You will need a more advanced twiki.conf file, to block unwanted spiders crawling your site - you should use use TWiki.org's online twiki.conf file generator: click over to the config generator page and enter your details, specifying /var/lib/twiki as the TWiki directory (NOT TESTED) and TemplateLogin as the authentication mechanism. Then back up the existing /etc/apache2/conf.d/twiki.conf and replace it with your generated version.
• To reduce spam changes to your Wiki, sure that BlackListPlugin is enabled, and updating itself with latest IP addresses to block (see WikiSpam as well)
• You must also check SecurityAlerts for any new security issues that may have been fixed by TWiki.org but are not yet fixed in the Ubuntu package. Also, subscribe right now to the very low-volume twiki-announce mailing list for security alerts - normally such fixes are pushed through to Ubuntu quite fast.

Also, you should do some reading around on how to run a secure TWiki server - TWiki is generally secure and used on many Internet sites, but careful setup is required in some areas.

Make TWiki authenticate users through Windows login (optional)

The idea here is to avoid users having to log in again to the TWiki site - since most users are on Windows client PCs, you can simply have Apache authenticate them based on their Windows login (using protocols called NTLM, related to file sharing / SMB, and LDAP, related to Active Directory).

See TWikiOnUbuntuWindowsAuthentication for details - this is not a fully documented approach yet but it could turn into a HOWTO with some more work.

Getting support

For Ubuntu related issues, use the Ubuntu forums. If you find a bug, submit a bug in Launchpad on the twiki package - it's also good to search this if you have installation problems.

For issues that are more TWiki specific, just use the TWiki Support.WebHome web as usual.

Other installation options

The GUI way

You can also use a GUI based package manager, such as Synaptic (Ubuntu) or Adept (Kubuntu), to do the installation. You may need to open up the 'details' window to see the prompts from the installation process, and I haven't tested this, but it should work just like apt-get.

Manual installation

If for some reason you want to install TWiki manually, e.g. to get the absolute latest version, you can just get into a root shell and follow the TWikiOnUbuntuManualInstall guide, which shows how to download the latest TWiki version as a tar file and install it from there. However, the "easy way" above is much easier and more maintainable as Ubuntu and TWiki are upgraded, so only do this if you know what you are doing.

Get into a root shell

For Ubuntu, you can launch a new root shell by doing this instead of the first Preparing Kubuntu step:

1. Open the GNOME Main Menu Programs System GNOME Terminal
2. Make this into a root shell by typing sudo bash, and entering your password (same as the default user password)

Now go to TWikiOnUbuntuManualInstall and follow the steps there.

Server installations - which Ubuntu to use

If you want a real server install, or for smaller systems where a GUI is not feasible, see Ubuntu 7.10 Server Edition, and also look into Google:Ubuntu+server+install. Note that Ubuntu 7.10 is supported for 18 months from release - you can get 5 years of server support on Dapper, but it has a much older version of TWiki. If you have Linux skills already and require a small system setup, you might also consider TWikiOnDebian as the installation process is very similar.

: If you want to install TWiki within a VMware virtual machine, consider Ubuntu JeOS (a lightweight Ubuntu tuned for VMware) - installing TWiki under JeOS should work just like a server install. TWikiVMDebianStable may also be interesting for the VMware setup notes, but the VM would be JeOS plus TWiki.

Making backups of your TWiki data

If you are doing full backups of your system, TWiki is included - it doesn't use a database so there are no hassles in backing it up.

If not, see this tip on how to back up TWiki's data using rsync - if you back up to a USB stick, you could also put TWikiForWindowsPersonal or similar on there and run your TWiki on Windows PCs from the memory stick. However, it's worth checking the Windows TWiki is the same version as your Ubuntu-based TWiki if you are using any advanced features.

-- Contributors: RichardDonkin - 28 May 2007

Other resources:

• UbuntuForums HOWTO on TWiki installation on Ubuntu including discussion - the HOWTO does not use the twiki package, but some people commenting have done. This is mostly on earlier versions than Feisty so some paths are different.
• TWikiOnDebian - Ubuntu is not the same as Debian, but some tips on that page may help with more advanced setups.
• If you need to do additional setup:
  • For a lot more detail on how to set up TWiki on Linux, after the twiki package is installed, see the excellent TWikiOnRedHat page, most of which should apply to Ubuntu with little change. Start from the Run configure first time section.
  • TWikiInstallationGuide - the main TWiki installation guide - mostly useful for the parts where you use configure once TWiki is up and running.
• Ubuntu twiki package home page in Launchpad (Ubuntu's bug tracker).

-- RichardDonkin - 28 Sep 2007

Discussion

Did this work for you? Any comments or updates very welcome to improve this.

TODO: include information on Apache setup for low memory PCs.

Updated to cover the new Ubuntu 7.10 (Gutsy Gibbon) release, which includes TWiki 4.1.2.

-- RichardDonkin - 21 Oct 2007

See TWikiOnPlaystation3 if you really want a Wiki on your games console ...

-- RichardDonkin - 30 Oct 2007

Since Ubuntu install discs work as Live CDs, it could be interesting to do a 'TWiki Live CD' using Ubuntu as a base. It would need to use a USB stick or hard drive for data storage, but that should not be too hard to do through TWiki configuration.

-- RichardDonkin - 06 Dec 2007

I can't install Plugins from configure!

I trie to install the plugin "TreePlugin":

Fetching http://twiki.org/p/pub/Plugins/TreePlugin/TreePlugin.tgz...
Unpacking...
templates/

Note: Existing templates/booktree.tmpl overwritten.
TreePlugin_installer
lib/
lib/TWiki/
lib/TWiki/Plugins/
lib/TWiki/Plugins/TreePlugin.pm
lib/TWiki/Plugins/TreePlugin/
lib/TWiki/Plugins/TreePlugin/FormatHelper.pm
lib/TWiki/Plugins/TreePlugin/FormatOutlineNodeFormatter.pm
lib/TWiki/Plugins/TreePlugin/ColorNodeFormatter.pm
lib/TWiki/Plugins/TreePlugin/ImgNodeFormatter.pm
lib/TWiki/Plugins/TreePlugin/test.tar.gz
lib/TWiki/Plugins/TreePlugin/OutlineNodeFormatter.pm
lib/TWiki/Plugins/TreePlugin/TWikiNode.pm
lib/TWiki/Plugins/TreePlugin/NodeFormatter.pm
lib/TWiki/Plugins/TreePlugin/Node.pm
lib/TWiki/Plugins/TreePlugin/HOutlineNodeFormatter.pm
lib/TWiki/Plugins/TreePlugin/ListNodeFormatter.pm
pub/
pub/TWiki/
pub/TWiki/TreePlugin/

Note: Existing pub/TWiki/TreePlugin/oL.gif overwritten.

Note: Existing pub/TWiki/TreePlugin/white.gif overwritten.

Note: Existing pub/TWiki/TreePlugin/oT.gif overwritten.

Note: Existing pub/TWiki/TreePlugin/T.gif overwritten.

Note: Existing pub/TWiki/TreePlugin/I.gif overwritten.

Note: Existing pub/TWiki/TreePlugin/L.gif overwritten.

Note: Existing pub/TWiki/TreePlugin/pL.gif overwritten.

Note: Existing pub/TWiki/TreePlugin/pT.gif overwritten.
TreePlugin_installer.pl
data/
data/TWiki/

Note: Existing data/TWiki/TreePlugin.txt overwritten. Backup saved in /var/lib/twiki/data/TWiki/TreePlugin.txt.bak
data/Sandbox/

Note: Existing data/Sandbox/TreeBookviewOutlineSample.txt overwritten. Backup saved in /var/lib/twiki/data/Sandbox/TreeBookviewOutlineSample.txt.bak

Note: Existing data/Sandbox/HeadingOutlineSample.txt overwritten. Backup saved in /var/lib/twiki/data/Sandbox/HeadingOutlineSample.txt.bak

Note: Existing data/Sandbox/TreePluginSamples.txt overwritten. Backup saved in /var/lib/twiki/data/Sandbox/TreePluginSamples.txt.bak
Error: No permission to write to /var/lib/twiki/templates/booktree.tmpl
Software error:

Installation terminated at /usr/share/perl5/TWiki/Configure/UIs/EXTEND.pm line 145.

or the plugin "CalendarPlugin":

Fetching http://twiki.org/p/pub/Plugins/CalendarPlugin/CalendarPlugin.tgz...
Unpacking...
lib/
lib/TWiki/
lib/TWiki/Plugins/
lib/TWiki/Plugins/CalendarPlugin.pm
CalendarPlugin_installer.pl
pub/
pub/TWiki/
pub/TWiki/CalendarPlugin/
pub/TWiki/CalendarPlugin/exclam.gif
data/
data/TWiki/
data/TWiki/CalendarPlugin.txt
Error: Failed to move file 'lib/' to /usr/lib/cgi-bin/lib: Permission denied
Software error:

Installation terminated at /usr/share/perl5/TWiki/Configure/UIs/EXTEND.pm line 149.

Can anybody help me?

-- ThomasHesse - 14 Jan 2008

Thanks for commenting, it's always nice to see someone is using this page, even if not everything works.

I haven't tried this myself, but it seems fairly clear that it's a permissions error - see Error: No permission to write to /var/lib/twiki/templates/booktree.tmpl above. So the problem is that you would need to set the relevant directories to be writeable by the userid that configure is running as (probably www-data but you can check this in configure itself), so that the plugin installer (which runs under configure) can write to these directories when installing plugins.

Note that this change of permissions will open up some security holes, e.g. anyone who can create a CGI script on your server can also change the modules used by TWiki - if you want a secure server it's best not to do this, but it does make installing plugins more convenient. There are ways around this through a more complex SecureSetup using suexec but that can be hard to debug.

There was an issue with the plugin installer unpacking the tar.gz file into /tmp and having problems with moving files across to the main filesystem (/) since the two are separate on Ubuntu - but that's not the issue here I think.

If you just want the plugin to work, I would simply install it manually, which is not hard.

-- RichardDonkin - 15 Jan 2008

Many thanks for your fast and detailed answer!

I am installing rather my plugins now manuelly, I will not open some security holes on my TWiki.

-- ThomasHesse - 18 Jan 2008

In my opinion does the way Ubuntu installs the TWiki break the automatic plugin installer from the configure page. This can't be intended, does it? I changed the permissions on /usr/lib/cgi-bin to allow "www-data" to write. But doing this messes the whole thing up. The plugins get now installed into /usr/lib/cgi-bin/ subdirectories and not in /var/lib/twiki subdirectories where they should.

If you have to set up a new twiki system and you need to install more then 20 plugins, doing it manually is a pain in the ass. Should I file a bug report? Is there a quickfix for me to correct this? Comments?

Thanks, Jan

-- JanMichael - 24 Jan 2008

Yes, it does. I have some fixes to the debian 4.1.2 package cued up, but I have had trouble getting it all completed due to other priorities.

The Ubuntu package is pretty much a modification on that.

-- SvenDowideit - 24 Jan 2008

If you are using Ubuntu for a personal TWiki on a slower PC (e.g. Pentium III with 512 MB), i.e. you are running your web browser and TWiki on same PC, try Firefox 3 beta 3 - it's now quite stable at least on Ubuntu (has only crashed a few times in several weeks), and is much less heavy on the CPU and memory, resulting in a better user experience for personal TWikis. Some add-ons are not yet working but many major add-ons are already ported.

-- RichardDonkin - 27 Feb 2008

This installation page needs a serious amount of updating, and personally I don't have the time to go through it all.

-- NojiRatz - 2010-07-30

Ok, I've installed TWiki on my server, per the instructions. So now how do I access TWiki from our Windows workstations? I don't see any help here on that, and I've spent the better part of today reading through it all.

-- NojiRatz - 2010-07-30

Yes, these instructions need heavy updates. TWiki is open source, I invite you to document what you learn, e.g. update above docs for others to read.

For specific installations questions I suggest to ask in the Support forum.

-- PeterThoeny - 2010-07-31