Installing Foswiki on BlueHost shared hosting

This is a step-by-step guide for installing Foswiki on BlueHosts's shared hosting plan. It's been tested with Foswiki version 1.1.3.

Prerequisites

Things to have

• A shared hosting plan at BlueHost. They have only one plan, so you can't choose the wrong one.
• SSH shell access to the host. They will enable this only after you've requested it and sent them a scan of your photo ID.
• An SSH client. On Linux, this comes standard with almost every distro. On Windows, you can download PuTTY. All sample code you will see in this document, happens in an SSH session to your host, either at the command prompt or inside a text editor.

Things to know

• Basic operations in a TTY text editor. When you're logged into your host through SSH, you're in a Red Hat Linux command-line environment. Choose one of the available editors (vi, emacs, pico, nano) as your favourite - if you haven't done so already - and make sure you get familiar with simple operations like save, find, replace.
• Conventions used in this tutorial. Some pieces of text will be shown in red. Wherever you see a red piece of text, you should not copy & paste it verbatim into your SSH session, but replace it with something that's specific to your situation:
  • FULLPATHTOHOME: Replace this with the full path to your home directory. You can get to know the full path to home by typing the following command in your SSH client:

    [~]# echo $HOME

  • example.com: Replace this with your own domain name.
  • JoeAdmin: Replace this with the WikiUserName of your site's administrator. E.g.: your own WikiUserName.

Unpacking files

• Download the tarball and untar it:

  [/]# cd
  [~]# cd www
  [~/www]# wget http://sourceforge.net/projects/foswiki/files/foswiki/1.1.3/Foswiki-1.1.3.tgz
  [~/www]# tar xzf Foswiki-1.1.3.tgz
  

• Rename it to something simpler:

  [~/www]# mv Foswiki-1.1.3 foswiki
  

• In the folder ~/www, create a text file named script_foswiki, with the following contents:

  cp foswiki/bin/LocalLib.cfg.txt foswiki/bin/LocalLib.cfg
  cp foswiki/bin-htaccess.txt foswiki/bin/.htaccess
  cp foswiki/subdir-htaccess.txt foswiki/lib/.htaccess
  cp foswiki/pub-htaccess.txt foswiki/pub/.htaccess
  cp foswiki/root-htaccess.txt foswiki/.htaccess
  cp foswiki/subdir-htaccess.txt foswiki/data/.htaccess
  cp foswiki/subdir-htaccess.txt foswiki/locale/.htaccess
  cp foswiki/subdir-htaccess.txt foswiki/templates/.htaccess
  cp foswiki/subdir-htaccess.txt foswiki/tools/.htaccess
  cp foswiki/subdir-htaccess.txt foswiki/working/.htaccess
  echo SetHandler cgi-script > foswiki/bin/.htaccess
  chmod 644 foswiki/pub/.htaccess
  chmod 644 foswiki/.htaccess
  

• Run the commands in script_foswiki with the dot command:

  [~/www]# . script_foswiki
  

Note that this is typically unnecessary

• In foswiki/bin/LocalLib.cfg, set $foswikiLibPath to the full path of your lib directory:

  $foswikiLibPath = "FULLPATHTOHOME/www/foswiki/lib";
  

• In the folder ~/www, create a .htaccess file that redirects all Web traffic to the foswiki/bin/view script

  [~/www]# echo redirect /index.html http://example.com/foswiki/bin/view > .htaccess
  

• In foswiki/pub/.htaccess, comment out the line: php_flag engine off (disable it by putting a '#' in front)

Configuration

Follow Bootstrap instructions in the InstallationGuide Do NOT directly start with bin/configure!

• Run the configure script by entering the following URL in your browser: http://example.com/foswiki/bin/configure
• If all went well, you should see a welcome screen that reports 10 warnings, all belonging to the sections "General path settings". Ignore these warnings, and just click on the button in the bottom right corner: "Save changes".
• A new web page appears. Decide on which admin password you will use, and fill it out twice at the bottom of the page. Click on "Set password and Save changes"
• At the bottom of the resulting page, 1 error and 3 warnings are reported. In the section "Mail and Proxies", fill out your email address at "{WebMasterEmail}".
• In the section "Security and Authentication", subsection "Passwords", you can change "{Htpasswd}{Encoding}" to "md5" for extra security.
• The rest of the warnings you can safely ignore.
• In the section "General path settings", note down the values of the following 2 variables for future use: ScriptUrlPath and DataDir

  ScriptUrlPath: /foswiki/bin
  DataDir: FULLPATHTOHOME/public_html/foswiki/data
  

• Click on the button "Save changes" in the bottom right corner.
• Fill out your password again and click on "Save changes"
• Enter the URL of your website in your browser: http://example.com
• The front page of the installed Foswiki appears!

Protect the configure script

Not needed on Foswiki 2.0. We will choose an Apache-level authentication method for securing the configure script. Basically, we create a user inside Foswiki, and use Foswiki's .htpasswd file to authenticate access to configure.

• In the top left corner of your Foswiki front page, click on "Register"
• Fill out the registration form for your Foswiki site's administrator, e.g. JoeAdmin, with the same password as chosen during configure.
• Change file permissions of the newly created foswiki/data/.htpasswd file:

  [~/www]# chmod 644 foswiki/data/.htpasswd
  

• Overwrite the existing .htaccess file in the foswiki/bin folder with a new one:

  [~/www]# cp foswiki/bin/.htaccess.txt foswiki/bin/.htaccess
  

• In foswiki/bin/.htaccess: replace {ScriptUrlPath} and {DataDir} with their values from configure.
  
  Hint: If vi is your editor of choice, you can perform a search-and-replace of {ScriptUrlPath} by typing the following command inside vi:

  %s/{ScriptUrlPath}/\/foswiki\/bin/g
  

  Mind the backslashes: they are necessary to escape every forward slash in /foswiki/bin. Every occurrence of {DataDir} must be replaced with a similar command.

• In foswiki/bin/.htaccess: edit the block <FilesMatch "configure.*"> as follows:

      SetHandler cgi-script
      Order Deny,Allow
      Deny from all
      Require user JoeAdmin
      Satisfy Any
  

• In foswiki/bin/.htaccess, there are two lines that contain: AuthType Basic. One of these 2 is not commented out. Change that line into:

  AuthType Digest
  

• Make sure foswiki/bin/.htaccess is saved.
• Revisit http://example.com/foswiki/bin/configure to check access control for the configure script. Login as JoeAdmin.
• Your configure script is now secured.