How to setup Twiki 4.1.2 (Edinburgh Release) with DreamHost hosting

The installation guide in the distribution needs some changes in order to work on DreamHost.

• To install TWiki on DreamHost, follow the instructions below. This is specifically for the Edinburgh version; it has not been tested with other releases.
• To install TWiki with another hosting provider, follow TWikiDocumentation.html in the distribution.
• Most of this guide was adapted from http://g-b.dk/bin/view/Main/InstallTwikiDakarOnDreamhost and http://twiki.org/cgi-bin/view/Codev/DreamhostSetupNotes
  • I am keeping this separate guide to document my exact steps to get the Twiki up and running.
  • Many thanks to the original authors

Before you begin

• Just follow this description and replace these example strings with your own:
  1. example DreamHost user = DH_user
  2. example DreamHost server = DH_server
  3. example server path = /home/DH_user/subdomain.domain.com
  4. example browser URL = http://subdomain.domain.com
  5. example Twiki administrator name = YourAdminName
• This example is designed around using a subdomain as the root of the twiki site
  • For example http://wiki.example.com/ 'wiki' is the subdomain of 'example.com'

Prepare the domain

• Go to the DreamHost web panel (the Add Domain tab) and create a new (sub)domain. This will create a directory /home/DH_user/subdomain.domain.com on the web server that gets http-enabled as http://subdomain.domain.com.
  • This can take a while, so do this first - it will be ready when you need it, later on.
  • Here's a direct link to the Add Domain tab: https://panel.dreamhost.com/index.cgi?tree=domain.add_domain&;
• I chose to make my Twiki a strict subdomain of my main domain wiki.heckheck.com

Get shell access for your DreamHost user account and log in

• Go to the DreamHost web panel (the Manage Users tab)
• Click Edit for the user you will use and check Shell account - allows FTP plus ssh/telnet access. under the User Account Type: section.
• Save the changes.
• SSH into the shell account
  • The Manage Users tab also contains the server name in parentheses after your user name (e.g. camaro)
  • Use an SSH client like putty to ssh into DH_server.dreamhost.com

Get the TWiki source files

• Download the tgz file to the DreamHost subdirectory that will host your Twiki subdomain
  • Download page: http://twiki.org/cgi-bin/view/Codev/DownloadTWiki
  • File link: http://twiki.org/p/pub/Codev/Release/TWiki-4.1.2.tgz
  • Commands:

    [DH_user@DH_server:~]$ wget http://twiki.org/p/pub/Codev/Release/TWiki-4.1.2.tgz
          

• Copy the tgz file to the subdirectory that will host the subdomain containing the Twiki and expand it
  • Commands:

    [DH_user@DH_server:~]$ cp TWiki-4.1.2.tgz subdomain.domain.com/.
    [DH_user@DH_server:~]$ cd subdomain.domain.com/
    [DH_user@DH_server:~/subdomain.domain.com]$ tar xvzf TWiki-4.1.2.tgz
          

Edit special files

• Edit the following files in place in your DreamHost shell in the subdirectory you just untar'd the Twiki files into. Use your favorite editor, (emacs, vim, nano)
  • These files are in the directory structure that corresponds to the subdomain you will use to host the Twiki (e.g. /home/DH_user/subdomain.domain.com)

• Copy root-htaccess.txt to ".htaccess" and edit the last line. I've used my examples but you must change this to match your setup.
  • Commands:

    [DH_user@DH_server:~/subdomain.domain.com]$ cp root-htaccess.txt .htaccess
    [DH_user@DH_server:~/subdomain.domain.com]$ chmod 644 .htaccess
    [DH_user@DH_server:~/subdomain.domain.com]$ emacs .htaccess
    [DH_user@DH_server:~/subdomain.domain.com]$ chmod 444 .htaccess
          

  • Edit

    Line 13: Redirect /index.html http://subdomain.domain.com/bin/view/Main/WebHome
          

• Copy pub-htaccess.txt to "pub/.htaccess". No edits here.
  • Commands:

    [DH_user@DH_server:~/subdomain.domain.com]$ cp pub-htaccess.txt pub/.htaccess
          

• Copy subdir-htaccess.txt to ".htaccess" in each of the folders data, lib, locale and templates. No edits here.
  • Commands:

    [DH_user@DH_server:~/subdomain.domain.com]$ cp subdir-htaccess.txt data/.htaccess
    [DH_user@DH_server:~/subdomain.domain.com]$ cp subdir-htaccess.txt lib/.htaccess
    [DH_user@DH_server:~/subdomain.domain.com]$ cp subdir-htaccess.txt locale/.htaccess
    [DH_user@DH_server:~/subdomain.domain.com]$ cp subdir-htaccess.txt templates/.htaccess
          

• In the bin folder, copy .htaccess.txt to .htaccess and make the following changes.
  • Commands:

    [DH_user@DH_server:~/subdomain.domain.com/bin]$ cp .htaccess.txt .htaccess
          

  • Edit:

    Line 41: AuthUserFile /home/DH_user/subdomain.domain.com/data/.htpasswd
    Line 66: ErrorDocument 401 /bin/view/TWiki/TWikiRegistration
    Line 81: # Allow from 127.0.0.1, 192.168.1.10
               Allow from all
          

  • IMPORTANT Come back to this .htaccess file and secure after you run configure (see below). You will want to comment out line 81 and the extra Allow from all line to prevent any unauthorized running of the configure script. Also change the permissions on the file back to 444.
• In the data folder, touch the .htpasswd file and chmod its permissions to 644
  • Apache will create this file automatically, but with 600 permissions. This will cause problems with the bin/.htaccess file, which references this file. The result will be that users can't edit any TWiki pages.
  • I have not verified that pre-creating this file and setting the permissions will work. I ended up setting the permissions after I had a problem.

Run the configure script

• From a browser, run the configuration script at http://subdomain.domain.com/bin/configure. If you get a logon dialog, you've done something wrong in the bin/.htaccess file (check the configure stanza starting at line 72)
  • After working on each section you must click the Next button on the bottom of the screen and save the configuration on the next page.
• Fix the errors and warnings under General path settings
  • Fix the tmp directory. You should create a writable directory that is in your local home directory, for example /home/DH_user/tmp/twiki
  • Remove the .something out of the path names for PubDir, TemplateDir, _DataDir and LocalesDir. The modified path is a link to the path with the .something, and should not change if they reconfigure the server storage.
• Fix the warnings under Security setup
  • Choose a {LoginManager}. I chose TWiki::Client::TemplateLogin.
  • If present remove the .something out of the path name for {Htpasswd}{FileName}.
• Setup the mail properly under Mail and Proxies
  • Add your webmaster e-mail address {WebMasterEmail}. This could be [email protected]_domain.com.
  • Add your domain's SMTP server under {SMTP}{MAILHOST}. This should be mail.your_domain.com.
• Turn on the WYSIWYG plugin under Plugins
• Install the BlackListPlugin to keep "evil-doers" at bay
  • Download the plugin to your home computer from http://twiki.org/cgi-bin/view/Plugins/BlackListPlugin. It is available only in zip format, and wget doesn't like the link, so you'll have to move it onto your DreamHost account with a file copy.
  • Copy to DreamHost using scp or on windows pscp (from Putty). From Linux that's as easy as

    user@linuxhost:~$ scp BlackListPlugin.zip DH_user@DH_host.dreamhost.com:BlackListPlugin.zip
          

  • Copy the plugin into the subdomain directory and expand.

    [DH_user@DH_server:~/subdomain.domain.com]$ cp ../BlackListPlugin.zip .
    [DH_user@DH_server:~/subdomain.domain.com]$ unzip BlackListPlugin.zip
          

  • Back in the browser running the Configure script, enable the plugin under Plugins and save the configuration.
• If you haven't already, set a password for configuration. This is done on the screen where you save configuration. Enter the password twice in the lower portion of the dialog. Even though you will be disabling, Configure, it never hurts to have too much security!
• Once you are happy with TWiki configuration, secure it! The following steps should be overkill in preventing configure from being run.
  • Disable access to configure by editing the bin/.htaccess file and commenting out any Allow directives starting at line 81.
  • Make the bin/.htaccess, bin/configure and lib/LocalSite.cfg files read only with unix permissions of 444.
    • lib/LocalSite.cfg is where the configure script stores settings for the TWiki
  • When you need to run configure again, just undo these steps
    • To secure

      [DH_user@DH_server:~/subdomain.domain.com]$ emacs bin/.htaccess
      [DH_user@DH_server:~/subdomain.domain.com]$ chmod 444 bin/.htaccess
      [DH_user@DH_server:~/subdomain.domain.com]$ chmod 444 bin/configure
      [DH_user@DH_server:~/subdomain.domain.com]$ chmod 444 lib/LocalSite.cfg
               

    • To unsecure

      [DH_user@DH_server:~/subdomain.domain.com]$ chmod 644 bin/.htaccess
      [DH_user@DH_server:~/subdomain.domain.com]$ chmod 555 bin/configure
      [DH_user@DH_server:~/subdomain.domain.com]$ chmod 644 lib/LocalSite.cfg
      [DH_user@DH_server:~/subdomain.domain.com]$ emacs bin/.htaccess
               

Test out a few things

• Make sure the main TWiki page comes up when you navigate to http://subdomain.domain.com. If not, you got something wrong when setting up redirection in the root .htaccess file.
• Test redirection for errors. Try to edit a page while logged in as no user. This should bring you to your TWiki registration page.
• Add the user you will use as the Administrator. This will test also test to see if mail works properly. You should receive a registration e-mail

Problems with images and cascading style sheets

• After installing Foswiki on Dreamhost, everything seemed to work until I went to the main page after configuring. None of the style sheets nor images were loading. The pages worked, but they didn't look right. It turns out that something in the pub-htaccess.txt file conflicts with Dreamhost. I copied the sample from the Foswiki distribution to the /pub directory as per the instructions. After taking it out, however, everything worked. I don't know enough about .htaccess files to know where the conflict lies, but commenting out certain parts in an attempt to find the conflict lead to conflicting results (perhaps due to caching?). Anyway, the easy way to get images and css to work on dreamhost is to NOT use the pub-htaccess.txt file that comes with Foswiki.

Now setup some TWiki administrative stuff

• Add your user as to the TWikiAdminGroup and deny others from joining this group
  • From the main TWiki page http://subdomain.domain.com/bin/view, navigate to the TWikiUsers link and make sure the user you added is listed.
  • From the Related Topics link at the top of the TWiki user page navigate to the TWikiGroups link and from there navigate to the TWikiAdminGroup link.
  • Read the instructions and edit this page. Basically, you want to replace ATWikiUser with the name of the user you added, and remove the # in front of the ALLOWTOPICCHANGE attribute.
• The TWiki.TWikiPreferences and Main.TWikiPreferences pages have already been setup with ALLOWTOPICCHANGE and ALLOWTOPICRENAME attributes set to TWikiAdminGroup, (the latter has it as a hidden comment field), so only your user should be able to change site wide preferences.

Now create a Web to collaborate with

• Log in as the user belonging to the TWikiAdminGroup
• In the sidebar under Webs Click on the TWiki web.
• Then click on the Admin Tools link under the _ TWiki Documentation and Configuration_ heading.
• Then click on the ManagingWebs link under the _ All Admin Tools Category topics_ heading
• Now fill in the form in the middle of the page with information on your new web and click on the Create new web button.

. -- JimHeck - 22 Apr 2007

-- TWiki:Main/JimHeck - 28 Apr 2007