Is this page obsolete? It was last edited "02 Apr 2004 - 06:47 - PeterThoeny" before I made some corrections and added this question. -- DavidBooth - 12 Mar 2006

Yes, it's pretty inaccurate for Dakar installs. So in that sense it's obsolete

-- MeredithLesly - 05 Apr 2006

---

I decided to rewrite the installation guide for Twiki as a "personal guide" for my subsecuent Twiki installations. But RichardDonkin asked me to post this Work in Progress here, so here it is. I am not a Unix guru, and know nothing about Perl, so feel free to correct and modify this "guide".

---

TWiki Installation Guide for Non-Root Accounts

Installation instructions for the TWiki 01-Sep-2001 production release

Overview

These installation steps are based on the Apache Web server on Linux. TWiki runs on other Web servers and Unix systems, and should be fine with any OS and server that meet the system requirements. Documentation for other platforms is currently limited. For Windows, check TWiki:Codev/TWikiOnWindows. Search the TWiki:Codev web for other intallation notes.

These installation steps supose that don't have access to your Web server configuration files - for example, if you're installing on an ISP-hosted account. This means that you don't have the privileges to modify the httpd.conf file, nor restart Apache.

Step 1: Request and Download TWiki

Request and download the TWiki 01-Dec-2001 distribution in Unix ZIP format from http://TWiki.org/download.html. (To install TWiki on SourceForge, for use on a software development project, read TWiki:Codev/TWikiOnSourceForge .)

Step 2: Configure Twiki

Note: If you have telnet access to your hosting site, it may be faster and easier to upload the entire *.zip file of the TWiki download, unzip it there, and configure it there. -- DavidBooth - 12 Mar 2006

• Download and unzip TWiki on your local PC
• Using the table below, decide a directory structure on your host server

TWiki dir:	What it is:	Where to copy:	Example:
twiki/bin	CGI bin	cgi-enabled dir	/home/smith/public_html/cgi-bin
twiki/lib	library files	same level as twiki/bin	/home/smith/public_html/lib
twiki/pub	public files	htdoc enabled dir	/home/smith/public_html/pub
twiki/data	topic data	outside of htdoc tree (for security)	/home/smith/twiki/data
twiki/templates	web templates	outside of htdoc tree (for security)	/home/smith/twiki/templates

• Security issue: Directories twiki/data , twiki/templates and all its subdirectories should be set so that they are not visible as a URL. (Alternatively, move the directories to a place where they are not visible, and change the variables in twiki/lib/TWiki.cfg accordingly)
• Discussion about how to name your webs: RenameTestWebToSandboxWeb, RenameTheMainWeb (to User), see TWikiAdminCookBook for other suggestions.

I was unable to get my mine to work with twiki/bin under my cgi-bin directory for reasons having nothing to do with twiki. (For some reason, Apache wasn't seeing changes I made to my cgi-bin directory.) I eventually moved twiki/bin (and twiki/lib) under my public_html directory (which meant I needed to rename most bin files to *.pl and set {ScriptSuffix} when running wiki/bin/configure.pl from a browser) and got it working that way. - DavidBooth - 12 Mar 2006

Step 3: Configure

• The default location of Perl usually is /usr/bin/perl. If it's elsewhere, change the path to Perl in the first line of each script in the twiki/bin directory.

• On ISP-hosted accounts, Perl CGI scripts usually require a .cgi extension to run. Some systems need .pl, the regular Perl extension. Modify all twiki/bin script filenames if necessary (exceptLocalLib.cfg.txt and setlib.cfg).

• Edit twiki/lib/TWiki.cfg, setting the variables to your needs. [Won't this file be overwritten by a TWiki software upgrade? Should this now say "Copy twiki/lib/LocalSite.cfg.txt to twiki/lib/LocalSite.cfg and edit twiki/lib/LocalSite.cfg . . ."? -- DavidBooth - 12 Mar 2006]
  • Set $wikiHomeUrl. This variable must point to the twiki/bin you selected in Step 2, this is the URL where your point your browser to start the wiki.
  • Set $defaultUrlHost. Host of the TWiki URL, usually the "first part" of the $wikiHomeUrl.
  • Set $scriptUrlPath. cgi-bin path of TWiki URL, usually the "last part" of the $wikiHomeUrl.
  • Set $pubUrlPath. Path of the public data TWiki URL (root of attachments). It must be in a htdoc enabled directory.
  • Set $pubDir. Full system path to public data directory twiki/pub, the last part must match $pubUrlPath.
  • Set $templateDir. Full system path to the templates directory twiki/templates.
  • Set $dataDir. Full system path to the data directory twiki/data.
  • Make sure RCS is installed. To do this log on into your accout and type "rcs". Set $rcsDir in twiki/lib/TWiki.cfg to mach the location of your RCS binaries.
  • Set the file extension in the $scriptSuffix variable to cgi or pl if required to match the extension of the scripts in twiki/bin.

• Section of a Example twiki/lib/TWiki.cfg file:

    # variables that need to be changed when installing on a new server:
    # ==================================================================
    #                   /cgi-bin/view/Main/WebHome : link of TWiki icon in upper left corner :
    $wikiHomeUrl      = "http://www.mywebsite.com/twiki/cgi-bin/twiki/bin";
    #                   Host of TWiki URL :    (Example "http://myhost.com:123")
    $defaultUrlHost   = "http://www.mywebsite.com";
    #                   /cgi-bin : cgi-bin path of TWiki URL:
    $scriptUrlPath    = "/twiki/cgi-bin/twiki/bin";
    #                   /p/pub : Public data path of TWiki URL (root of attachments) :
    $pubUrlPath       = "/twiki/pub";
    #                   Public data directory, must match $pubUrlPath :
    $pubDir           = "/home/myuser/public_html/twiki/pub";
    #                   Template directory :
    $templateDir      = "/home/myuser/twiki/templates";
    #                   Data (topic files) root directory :
    $dataDir          = "/home/myuser/twiki/data";

• This Guide assumes user nobody ownership for all files manipulated by the CGI scripts (executed by the Web server), and user twiki for all other files. You can:
  • replace nobody with another user if your server executes scripts under a different name (ex: default for Debian is www-data).
    • HINT: Run the testenv script from your browser: http://yourdomain.com/twiki/bin/testenv. It will show you the user name of the CGI scripts, a table listing all CGI environment variables, and a test of your twiki/lib/TWiki.cfg configuration file (you'll configure that in a minute).

Hmm, twiki/bin/testenv does not seem to exist in TWiki version 4.0.1. Perhaps twiki/bin/configure now has this this capability? -- DavidBooth - 12 Mar 2006

• • replace user twiki with your own username

• The twiki/data/*/*.txt,v RCS repository files in the installation package are locked by user nobody. If your CGI scripts are not running as user nobody, it's not possible to check in files (you'll see that the revision number won't increase after saving a topic). In this case, you need to unlock all repository files (check the RCS man pages) and lock them with a different user, ex www-data, or delete them all - new files will be automatically created the first time each topic is edited.

Question: can you please add here RCS command how to unlock all files - for completeness?

Step 4: Deploy the files to the server

• Create the directories

• Upload the TWiki files by FTP, set transfer mode as text except for the image files in the twiki/pub directory.

• Set the file permission of all Perl scripts in the twiki/bin directory as executable to -rwxr-xr-x (755), use: chmod 755 *

• Set the permission of the twiki/data directory and its subdirectories so that files in there are writable by user nobody. A simple way is to chmod -R them to 744 and to chown them to nobody.

• Set the permission of the twiki/pub directory and all its subdirectories so that files in there are writable by user nobody. A simple way is to chmod -R them to 544 and to chown them to nobody.

• Test your settings by running the testenv script from your browser: http://yourdomain.com/twiki/bin/testenv. Check if your twiki/lib/TWiki.cfg configuration file settings are correct.

• If you didn´t change the user which locks the RCS repository files in the installation package from nobody, and you need to, a simple way to change ownership is with a search-and-replace in all files; for example, using sed:

cd twiki/data
for f in */*,v; do sed 's/nobody\:/www-data\:/' $f > x; mv -f x $f; done

Note: If you do not have root access you can use the QuickAndDirtyExecUtilityForHostedSites.

Step 5: Finish Up from Your Browser

• Point your Web browser at http://yourdomain.com/twiki/bin/view and start TWiki-ing away!

• Edit the TWikiPreferences topic in the TWiki:TWiki06x01 web to set the WIKIWEBMASTER email address, and other preferences.

• Edit the WebPreferences topic in each web, if necessary: set individual WEBCOPYRIGHT messages, and other preferences.

• Enable email notification of topic changes, TWikiSiteTools has more.

• Edit the WebNotify topic in all webs and add the users you want to notify.

• Add the TWiki:Main/PoweredByTWikiLogo to your Main topic.
  • You can use also new HighResolutionLogos.

• You can add new %VARIABLES%. Define site-level variables in the TWikiPreferences topic. See also: TWikiVariables.

That's it for the standard basic installation of TWiki. Read on for server-level customization options.

TWikiAdminCookBook has many interesting links, i.e. simpler skins, how to present TWiki in better light.

Will continue...

Very usefull, thank you. I took freedom to add some links about how to name webs and other stuff.

-- PeterMasiar - 25 Mar 2002

This does look useful, good to see some more documentation being written!

It would be good to point to TWikiOnWebHostingSites early on, emphasising how important it is to select a site with Telnet/SSH and access to a compiler such as GCC. Also, you might want to link to TWikiDebugging, which has a pointer to a CGI-Telnet tool that largely makes up for the lack of Telnet/SSH (e.g. where people have already chosen a host before going for TWiki).

Also, have a look at WindowsInstallCookbook - since this was mainly written for CygWin's Unix-like environment, a lot should apply to Unix-hosted sites (e.g. there's a set of instructions to re-lock the RCS files).

-- RichardDonkin - 25 Mar 2002