Installation Guide: Foswiki 1.1.9 on Windows 2012 R2, IIS 8.5, Active Directory and ActivePerl

Introduction

This document is a guide to the settings which I used to get a trial Foswiki install running under windows. If it doesn't work for you then please don't blame me but hopefully it will be enough to get you started

Assumptions

• You have a windows 2012 R2 server set up with default settings.
• You are on a windows domain and you want to use Active Directory for authentication.
• You have already set up a domain name for your Foswiki site and pointed this to the IP of your server.
• You have a mail server and you know the name of it.

Limitations

• Migrating content from a previous install is not covered in this guide. It's fairly easy to do once you have got things running though.
• Permissions and security - Locking down the configure page is covered but managing page/web permissions is covered in the Foswiki Documentation.

The Guide

1. Install IIS

• Server manager -> add roles & features
• Web server (IIS)
• Add Windows Authentication
• Accept other defaults
• Restart server

2. Install/Extract Files

• Install notepad++ or your preferred advanced text editor.
• Run Active Perl 5.16.3 installer package from the ActivePerl website
  • Accept all defaults
• Extract Foswiki files to C:\foswiki\wwwroot
• Create new folder C:\foswiki\weblogs

3. Setup IIS

• Open IIS manager
• Add new website
  • Site name: Foswiki
  • Physical path: C:\foswiki\wwwroot
  • Host name: your.domain.name
• Update log folder
  • Open ‘Logging’, change directory to C:\foswiki\weblogs
    • Actions->Apply
• Add Perl support to IIS
  • Run PowerShell with administrative privileges
  • At the command prompt, type CD C:\perl64
    • Type ap-iis-config add all
    • You may see some ‘use of uninitialized value’ errors but they are safe to ignore and don't appear to affect functionality
    • Open IIS manager and highlight the foswiki website
    • Open handler mappings -> edit Perl CGI for .pl
    • Change Executable
      • from: C:\Perl64\bin\perl.exe "%s" %s
      • to: C:\Perl64\bin\perl.exe -T "%s" %s
• Set up AD authentication
  • Open Authentication
  • Disable ‘Anonymous Authentication’
  • Enable ‘Windows Authentication’
• Add MIME types
  • .oft - application/vnd.ms-outlook
  • .sql - text/plain
• Disable custom errors to allow Foswiki custom error codes
  • Open ‘Error Pages’
  • ‘Edit Feature Settings’
  • Select ‘Detailed errors’

4. Update Foswiki files

• Open C:/foswiki/wwwroot/bin and rename LocalLib.cfg.txt to LocalLib.cfg
  • You may need to turn off ‘Hide extensions for known file types’
• Edit LocalLib.cfg
  • Replace: $foswikiLibPath = ‘/absolute/path/to/your/lib’;
• With: $foswikiLibPath = ‘C:/foswiki/wwwroot/lib’;
• Add .pl to all extension-less files in /bin
• Perform the following text change on all .pl files in /bin:
  • Replace: @INC = ( '.', grep { $_ ne '.' } @INC );
• With: unshift @INC, "C:/foswiki/wwwroot/bin/";
• Remove windows permissions to /bin/configure.pl for all users except ‘SYSTEM’ and ‘Administrators’ to prevent unauthorised access
• Add read/write permissions for ‘Domain Users’to the following folders
  • /data
  • /lib
  • /pub
  • /working

5. Configure Foswiki

• Open IE
• Disable ‘Enhanced Protected Mode’ in Internet Options ->Advanced -> security
• Open http://your.domain.name/bin/configure.pl
• Go to ‘General path settings’
  • Set {DefaultURLHost} to https://your.domain.name
  • Set {ScriptSuffix} to .pl
• Click Save Changes and enter a secure password
• Click Set Password and Save Changes
• Go to ‘Security and authentication’
  • Set {LoginManager} to ApacheLogin
  • Set {PasswordManager} to None
  • Tick {Register}{AllowLoginName}
• Go to ‘Mail’
  • Set {WebMasterName} to Systems Development
  • Set {WebMasterEmail} to your.email@your.domain
  • Set {SMTP}{MAILHOST} to your.mail.server
• Click Save Changes , provide your password and save.

6. Create Wiki Users List

• Open http://your.domain.name/bin/view.pl/Main/WikiUsers
• Enter a list of your user's domain names and the name which you want to appear in the wiki e.g.
  • StevenHill - YOURDOMAIN\steven.hill - 2013-01-13
• Note: If you have a lot of users you will probably want to set up a script for this

7. Create Scheduled Tasks (optional if you want MailerContrib to work)

• Extract scheduled task batch files (attached) to C:\Foswiki\
• Create a new scheduled task and point it to C:\Foswiki\MailerContrib.bat
• Set the schedule to 0:00 every day
• Create a new scheduled task and point it to C:\Foswiki\UpdateStats.bat
• Set the schedule to 1:00 every day
• Note: feel free to play around with the times to suit

References and related documentation

• FoswikiOnWindowsIISAndPerl
• http://docs.activestate.com/activeperl/5.10/bin/ap-iis-config.html

If you found this guide useful then buy me a VirtualBeer