SID-02435: Newbie TWiki Basics

Status:	Asked	TWiki version:	6.1.0	Perl version:
Category:	CategoryInstallation	Server OS:		Last update:	5 years ago

WARNING - This is what I think I know, and may or may not be correct. If it is useful, great! Don't bet the farm on it...

TWiki Installation

TWiki is available as a Virtual Machine (which I've successfully set up on VirtualBox on a Windows 10 pc on my home wireless network), and as a zip file (tarball). The Virtual Machine version (as of this writing) is available as 6.0.2 (paid) and 6.0.1. The current zip version is 6.1.0.

IF you are doing a proprietary install (where you are the proprietor - you are admin, have root and suid access, and can shut down and restart the web server as you wish), you can follow the instructions at TWikiInstallationGuide. The toughest part of using the VM is setting up the IP address/port to access it from other PCs on the network.

IF you are trying to install in a hosted site environment, where you do not have admin access, but have to live within the rules set by the hosting company, things get a lot more detailed. The purpose of this page is to give the information you need that is typically under-the-covers and less-than-obvious in a proprietary install. It is based on my experience installing and configuring TWiki on NFSHost (Nearly Free Speech Host).

First, TWiki runs on a *nix (e.g., unix, linux, free bsd, red hat, ubuntu, mac) system - so either that needs to be the operating system of your host, or it needs to run on a virtual system that uses that type of operating system. By definition, using a *nix operating system means there are many, many variations. What works on one may not work on another, or work differently. My goal for this page is to present one specific install / configuration that works - your mileage may vary...

Next - you need to know enough about basic administration and commands under *nix to handle the tasks TWiki requires. This is not intended to be an education on *nix administration.

Activities to do a successful install / configuration

From here on, the focus will be on installation to a hosted site - specifically Nearly Free Speech (NFSHost). To install TWiki as a proprietary system (see above) follow the installation instructions. Mostly, you can just ignore / skip the "special cases" unless you're pretty sure they apply to you.

To install on a hosted site, there are no out-of-the-box instructions to follow. The proprietary system install instructions provide a general guideline of what needs to be done, but it also does a lot of things for you behind your back (either by design, or with "helpers" along the way that are designed for a proprietary install).

On a hosted system, an install involves the following areas:

• Get TWiki onto the install platform (e.g., download the TWiki tarball, upload it to the hosted site, and unzip it)
• Set the users, groups, and privileges
• Relocate public directories
• Set up .htaccess files
• Point to deployment location
• Run Configure (this is THE tool that does the setup of the TWiki for your environment)
• Configure your TWiki as required (non-proprietary locations for various directories, etc.)
• Request the host's service department to do the commands that require privileges you do not have
• Test the features of your install of TWiki (like, if you want to be able to create a web, create pages, do a backuprestore, see images, attach images, make new revisions of pages, look at history, register users, etc.)
• Final customization and configuring (which is out of the scope of this topic)

Disclosure: I am using a Windows 10 system, so the tools I refer to may or may not be appropriate for you. WinSCP is a utility that allows you to see your local directories, and the hosted site's directories, and to transfer files back and forth. PuTTY is a utility that starts a session on the hosted site, giving you the ability to execute commands as if you were at a command prompt on the hosted site. Any tools that accomplish these tasks may be used, and many web host services provide a control panel app that can do these things.

By the way - portions of this topic that are indented like this provide additional, supplemental information. You can safely ignore them when doing an install (assuming everything goes well...if not, there might be hints in the indented sections that help.

Nearly Free Speech Hosting (NFSHost) Orientation

NFSHost is a do-it-yourself hosting service, and provides minimal assistance / tools for the novice user. However, so far, I have found you can do pretty much anything you need to do, within the limits they've adopted (mostly for security purposes). NFSHost does not provide a control panel app. Instead, they expect you to use freely available tools to perform uploads, backups, etc., etc.

The default site directory structure they provide is as follows:

/home
/home/conf (this is where host configuration files for your site are stored)
/home/logs (contains your site's log files)
/home/private (your site's private information that is NOT accessible via URL)
/home/protected (your web site's information that is NOT accessible via URL)
/home/public (this is the base of your public web site - the index.html file here is the default page that displays when you go to the web site.)
/home/tmp (this is for temporary use, and is periodically wiped without notification or permission)

NFSHost requires you to provide a unique short name for your site - like xyla. Your default site URL is then xyla.nfshost.com (or whatever you gave as your site's short name). You can specify one or more aliases that will also go to your site - like xyla.com and www.xyla.com (and no, they are not the same) - which could be registered domain names.

At the end of this topic, there are instructions on installing / configuring the tools I used, if you need that information.

Getting TWiki onto the hosted site

On a hosted site, this will typically involve copying the tarball (zip file) you downloaded from TWiki.org to the hosting site. On NFSHost, the easiest way to do this is to use the free utility WinSCP. Copy the TWiki tarball to the site's /home/protected directory, and unpack it.

Performing interactive command-level actions can be done using PuTTY.

The distribution has the directories, files, owners, and rights needed for a proprietary install (and are mostly correct for our hosted site install). Using the following commands will unpack it with all that information intact.

In PuTTY, start a session, and do the following:

cd /home/protected
tar xvfz TWiki-6.1.0.tgz

Expect lots of messages. It doesn't take long to run. When it completes, the complete TWiki install (directories, subdirectories, owners, rights) will be present in the /home/protected/twiki directory.

Set Owner, Group, Permissions for Hosted Site

Note: Unzipping the distribution file should set all the ownership and permissions to the correct values, with the exception of what we change later in the instructions.

The TWiki.org topic SettingFileAccessRightsLinuxUnix provides information on the default settings that are needed for the TWiki install. TWiki 5.1.x commands seems to be the most relevant.

Set the User and Group

On NFSHost, all scripts are run as user "web", so we need to set group to web [25000] for all relevant directories and files.

In PuTTY, do the following commands:

cd /home/protected
chgrp -R web twiki

On NFSHost, the twiki base directory is /home/protected and it is NOT available via a URL (this is expected and to assist in site security).

Two directories must be moved from /home/protected/twiki to /home/public/twiki - bin and pub. All TWiki web functionality is provided via these two directories.

In PuTTY , do the following:

cd /home/public
mkdir twiki

Move the bin and pub directories

Move the following directories to /home/public/twiki:

bin
pub

In !WinSCP, refresh the site directories.

Browse to the /home/protected/twiki directory, right click the bin directory, and select Move To...

Enter /home/public/twiki/ in the Target Remote Path editbox and click OK.

Browse to the /home/protected/twiki directory, right click the pub directory, and select Move To...

Enter /home/public/twiki/ in the Target Remote Path editbox and click OK.

In WinSCP, refresh the site directories.

Browse to /home/public/twiki directory, and you should see the bin and pub subdirectories.

Create .htaccess files for root, bin, pub, and pub/Trash

Use ApacheConfigGenerator to generate a twiki.conf file. This is the configuration file that is used on a proprietary system and it can only serve as a starting point for the needed .htaccess files. On a hosted system, all Apache settings can be in the twiki.conf file and will take effect when the Apache web server is restarted - since you cannot restart the Apache web server on a hosted site, that will not work for our situation.

For a hosted site, the twiki.conf file must be split up into .htaccess files for each directory.

The settings I used in the ApacheConfigGenerator were:

Full filepath to your twiki root directory (mandatory): /home/public/twiki
URL path of the TWiki bin directory containing the scripts (mandatory): /bin
URL path of the TWiki pub directory containing file attachments (mandatory): /pub
Choose your Login Manager: TemplateLogin
Prevent execution of attached files as PHP scripts if PHP is installed:j PHP 4/5 Installed
Block known rogue spiders (recommended on public TWiki sites): checked
Block direct access to viewing attachments that ends with .htm or .html (recommended against spam abuse): checked
Block direct access to viewing attachments in Trash web (recommended against spam abuse): checked
Secure file attachments: Yes
Page to return to when authentication fails: TWiki Registration
Execution of TWiki's Perl scripts: mod_cgi
Apache version installed: Apache 2.4 or newer

Click the Update config file button, and follow the instructions to copy the generated text to twiki.conf

Copy the directory-specific sections

Do the .htaccess file for the /bin directory first

In the twiki.conf file, look for the <Directory "/home/public/twiki/bin"> starting tag. Copy the lines between the header and closing </Directory> tag to a new file. (Do not include the beginning and ending <Directory...> </Directory> tags.)

Comment out the AllowOverride None line (put a # at the beginning)
Comment out the Deny from env=blockAccess linejavascript:void(0)

Change value of AuthUserFile to /home/protected/twiki/data/.htpasswd

Save it as .htaccess and upload it to /home/public/twiki/bin

This is the "magic" that allows files in the /home/public/twiki/bin directory to be recognized and executed as cgi scripts without any file extensions. On NFSHost, cgi execution is enabled on /home and all subdirectories - you just have to make sure to turn it on for Apache for the directory, and specify that any file (extensionless or not) is to be considered an executable script.

By default, in *nix, file names that start with . (a period) are hidden. To see the .htaccess file: In WinSCP Ctrl+Alt+H will toggle displaying hidden files or go to Preferences > Panels. The first option will be a checkbox Display Hidden Files - check it. In PuTTY, from the /home/public/twiki/bin directory, do a

ls -d .*
It will show you . (current directory), .. (parent directory), and .htaccess (if it exists), as well as any other files that start with a period.

Create .htaccess for the /pub directory

In the twiki.conf file, look for the <Directory "/home/public/twiki/pub"> tag. Copy the lines between the opening and closing </Directory> tag to a new file.

Save it as .htaccess and upload it to /home/public/twiki/pub

Create .htaccess for the /pub/Trash directory

In the twiki.conf file, look for the <Directory "/home/public/twiki/pub/Trash"> tag. Copy the lines between the opening and closing </Directory> tag to a new file.

Save it as .htaccess and upload it to /home/public/twiki/pub/Trash

Create .htaccess for the /twiki directory

In the twiki.conf file, copy from the beginning of the file to the first <Directory...> tag to a new file.

Comment out the ScriptAlias and Alias commands (in my case, there were 4 of them).

Scroll to the end of the file, and insert the following section:

# Replacement for Alias and ScriptAlias above
RewriteEngine on
RewriteRule ^([A-Z].*) /twiki/bin/view/$1 [R]
RewriteRule ^(pub/TWiki) /twiki/pub/TWiki [R]
RewriteRule ^(pub/Sandbox) /twiki/pub/Sandbox [R]
RewriteRule ^(pub/) /twiki/bin/viewfile [R]
RewriteRule ^(do/) /twiki/bin/ [R]

Save the file as .htaccess and upload it to /home/public

Note: I don't know if those commands are critical - the reason I'm commenting them out is that /twiki/bin/configure or /twiki/bin/view/Main won't work if they remain in the .htaccess file.

Set the CGI-BIN Scripts Location

Download /home/public/twiki/bin/LocalLib.cfg.txt

Perform the following edit: (around line 24)

$twikiLibPath = "/home/protected/twiki/lib";

Save the file as LocalLib.cfg and upload it to /home/public/twiki/bin

Note that $twikiLibPath must be set to whatever the directory/path is for your system. This is for NFSHost. If your system is different, this setting must match your install's location.

Setting Owners / Rights

On NFSHost, all scripts run as user "web", so we need to set the group to web, and only the web user has the rights to write to the files.

From PuTTY...

cd /home/public
chgrp -R web twiki

and grant write right to the group for /home/public/twiki/pub

cd twiki
chmod -R g+w pub

And for the directories still in /protected...

cd /home/protected
chgrp -R web twiki
chmod -R g+w twiki

Set Up for BackupRestore Plugin

From PuTTY... do the following:

cd /home/protected
mkdir tmp
chgrp web tmp
chmod g+r+w-x tmp

The default directory to house backups for the BackupRestore plugin is /tmp (directory path), which is not a part of the TWiki install. So, we have to have a writable directory where we can store backups that is within the shared host directory structure. I'm guessing at the location...

Configure TWiki

In a browser, go to the following URL:

https://<<your site short name>>.nfshost.com/twiki/bin/configure

The configure script should run.
1st line below TWiki Administrator Login should be:
Could not find existing configure file /home/public/twiki/lib/!LocalSite.cfg.
(Because you are running this for the first time!)

If you get a message that a the lib directory is not writable, something went wrong in the steps to set group owner and write rights above. If you get an error 500, chances are that the .htaccess file in /home/public/twiki/bin is incorrect.

Enter the password you want two times and click Configure
(You do NOT want to forget this password!)

First line below header should read (red text, pink background)
Password changed
Click Next (don't worry about the errors/warnings at this time)

On the Please Confirm the Following Changes screen,
Click Save button

Yes, save the password change FIRST - before making other changes to the configure file...

Click the Return to Configuration link at the bottom of the screen. Enter the password again and click the Configure button.

Regardless of what it says, your TWiki site is NOT already working.

The Modify Configuration Screen appears - look for the word EXPERT in red text just above the Setting section (grey horizontal background
line)

Click the "Yes, I've read all the documentation" button (otherwise, some settings will not display).
In order to have access to all the options you need to change, you MUST click the "Yes, I've read all the documentation" button.

The screen will refresh.

The goal is to have no errors and minimal Warnings in the Settings section. Errors appear in red text against a pink background, Warnings appear in orange text against a light orange background. Near the bottom, a line will say:
Total: 2 errors, 2 warnings
(or whatever the number of errors / warnings there are)

BUT - The errors and warnings are for a proprietary install (see above), and are NOT intended for a hosted site. In addition to the warnings and errors, you must also update all the settings that point to the hosted server's directory structure - which is different for security purposes.

Click the link that precedes each section that needs to be changed, and scroll to find the values listed in the following sections. You may need to scroll up to start with the first option for the section.

The following changes were the ones I had to make for NFSHost (Nearly Free Speech Hosting) - different hosts' setups will be different. If in doubt, go through each setting group, and look for directories, paths, rights, file names that are different from "standard" admin host install - things like: having to move directories, install to other than the public path for the web server, relocating bin to a pre-defined cgi/script directory - all indicate differences in a hosted site deployment that you must change in configure to match your deployment. That is, if you want TWiki to work... correctly...

You can have an error-free configuration, and TWiki still will not work on your hosted site. You have been warned!

General path settings

{PermittedRedirectHostUrls} ofih.work,www.ofih.work

ofih.work is my registered site name, which has an alias with and without www. - use yours...

{ScriptUrlPath} /twiki/bin
{TemplateDir} /home/protected/twiki/templates
{DataDir} /home/protected/twiki/templates
{LocalesDir} /home/protected/twiki/locale
{WorkingDir} /home/protected/twiki/working

Security setup > Passwords

{Htpasswd}{FileName} /home/protected/twiki/data/.htpasswd

Log files

{ConfigurationLogName} /home/protected/twiki/data/configurationlog.txt
{DebugFileName} /home/protected/twiki/data/debug.txt
{WarningFileName} /home/protected/twiki/data/warn2026-03-10.txt
{LogFileName} /home/protected/twiki/data/log 2026-03-10

.txt

Store settings

{StoreImpl} RcsLite
{RCS}{dirPermission} 0775 (rwxrwxr-x)
{RCS}{filePermission} 0664 (rw-rw-r--)
{RCS}{EgrepCmd} /usr/bin/grep -E %CS{|-i}% %DET{|-l}% -H -- %TOKEN|U% %FILES|F%
{RCS}{FgrepCmd} /usr/bin/grep -F %CS{|-i}% %DET{|-l}% -H -- %TOKEN|U% %FILES|F%

Store settings relate to using RCS (the version control system) to keep the history of changes to the TWiki pages.

Mail and Proxies

NFSHost does not provide e-mail services of its own. I worked around this by creating a new e-mail account on gmail, and used the following settings:

{WebMasterEmail} MyNewEMail@gmail.com
{MailProgram} /usr/bin/sendmail -t -oi -oeq
{SMTP}{SENDERHOST} shtp.gmail.com
{SMTP}{Username} MyNewEMail @gmail.com
{SMTP}{Password} password for your e-mail service

Miscellaneous settings

{TemplatePath} /home/protected/twiki/templates/$web/$name.$skin.tmpl, /home/protected/twiki/templates/$name.$skin.tmpl, /home/protected/twiki/templates/$web/$name.tmpl, /home/protected/twiki/templates/$name.tmpl, $web.$skinSkin$nameTemplate, TWiki.$skinSkin$nameTemplate, $web.$nameTemplate, TWiki.$nameTemplate
{MimeTypesFileName} /home/protected/twiki/data/mime.types

Extensions

{Plugins}{BackupRestorePlugin}{BackupDir} /home/protected/tmp
{Plugins}{BackupRestorePlugin}{TempDir} /home/protected/tmp
{Plugins}{BackupRestorePlugin}{createZipCmd} /usr/local/bin/zip -r
{Plugins}{BackupRestorePlugin}{listZipCmd} /usr/local/bin/unzip -l
{Plugins}{BackupRestorePlugin}{unZipCmd} /usr/local/bin/unzip -o

Save the configuration file

When all the changes have been made, click Next Button, click Save button on next screen.

Click "Return to Configuration" link

Enter the password and click Configure

Click the "Yes, I've read all the documentation" button

Be sure it is a clean configuration (no errors).

Click the "Cancel and return to TWiki WebHome " link.

The TWiki web home page should display, complete with images, links, etc.

Remaining Issues

Now...having said all that, I still have the following issue(s):

BackupRestoreConsole doesn't work - after making the above changes, and trying to create a new backup, I get the following error message:

*TWiki detected an internal error - please check your TWiki logs and webserver logs for more information.

Can not open pidfile (pid_file => 'path'): Permission denied*

Help Me Fix This!

No, it isn't complete and correct. It is, at best, a start. I'm thinking of adding a troubleshooting section at the bottom (like what happens if you can't see .htaccess, why the configure script shows up as text rather than executing, etc., but not clogging up the main instructions with things that might go wrong.

After getting to the (temporary) end of this, I realize that its TWiki. TwikiWord isn't clear that it relates to installation instead of basic operation of TWiki. Probably needs changed.

-- David Tremain - 2020-03-14

Comments

Thank you for contributing these setup instructions.

My feedback: I do not recommend installing TWiki in a public directory, you run into security issues. For example, anybody with a browser could access URL path /twiki/data/SecretWeb/SomeTopic.txt to circumvent TWiki's access control, or /twiki/data/.htpasswd to access the password file. In addition, among others, the TWiki configuration can be accessed via /twiki/lib/LocalSite.cfg to read passwords in clear text.

I recommend unpacking the TWiki tarball in /home/private/twiki, and move only two directories elsewhere:

• twiki/bin to /home/public/twiki/bin
• twiki/pub to /home/public/twiki/pub

A setup like this is possible and secure, albeit a bit tricky. In twiki/bin/LocalLib.cfg you can define the path to your twiki/lib. The ApacheConfigGenerator comes in handy to get the settings right.

-- Peter Thoeny - 2020-03-14

Thanks Peter - I re-did the install and just moved the two directories. That also forced me to update many additional changes in configure. I'm still having issues with RCS (thought I read something about RCS using the nobody / nothing user). Also, the BackupRestoreConsole seems to not create a backup, but it doesn't act like it is trying to and just hanging with a scrolling status bar.

-- David Tremain - 2020-03-16

      Change status to: Asked question Answered question Closed unanswered

</literal>