Installing version 2.1.3 on FreeBSD 11.1 using Apache 2.4

Took me a while to figure it out but this procedure for installation of Foswiki on FreeBSD works pretty reliably:

Installing from the ports collection is nice and quick, so that's what is used here. The editor is nano, apologies to the vi crowd. Need to be root to do all of this and it's assumed that you're ssh'd in to the server.

Read this page in conjunction with this page.

Install Apache 2.4

Start by installing Apache version 2.4:

pkg install apache24

Apache needs to start at the same time that the server boots up so:

nano /etc/rc.conf

and add this line to the end of the file:

apache24_enabled="YES"

Reboot the machine to start the Apache web server, or do a onestart on it. Pull up a browser window to see if it’s working. In the URL bar, just put in 192.168.1.xxx or whatever the IP address of the FreeBSD machine is.

The whole Apache installation is at /usr/local/www/apache24. The file index.html can be edited, this is the page that is displayed in the browser:

nano /usr/local/www/apache24/data/index.html 

Install Foswiki 2.1.3

If everything looks good on the browser, the next step is to install Foswiki:

pkg install foswiki

This creates the Foswiki installation in:

/usr/local/www/foswiki

next to the directory for Apache. Ownership of the Foswiki directory needs to be changed so that Apache can get to it:

chown -R www:www /usr/local/www/foswiki

the first www is the Apache user and the second www is the Apache group. Then change directories:

cd /usr/local/www/foswiki/tools

It’s important that this next command is executed from within this tools directory as the program makes some assumptions regarding this.

perl rewriteshebang.pl

This will give an errror:

Content-type: text/plain

**** ERROR ****   
The following critical dependencies are missing from your installation:
 ... CGI: Can't locate CGI.pm in @INC 
 ... File::Copy::Recursive: Can't locate File/Copy/Recursive.pm in @INC 
 ... JSON: Can't locate JSON.pm in @INC   

Please install these modules and then ensure all dependencies are installed by either:
 - viewing the System.PerlDependencyReport in your local Foswki, or
 - running the CLI shell script tools/dependencies from your server's command line.
You can get a complete list of Perl module dependencies by viewing System.SystemRequirements
on your local system or at http://foswiki.org/System/SystemRequirements.

Foswiki will not operate correctly unless the required dependencies are installed.

Your current library search path @INC contains:
 /usr/local/www/foswiki/lib
 /usr/local/www/foswiki/tools/../bin
 /usr/local/lib/perl5/site_perl/mach/5.24
 /usr/local/lib/perl5/site_perl
 /usr/local/lib/perl5/5.24/mach
 /usr/local/lib/perl5/5.24
 .
 /usr/local/www/foswiki/lib/CPAN/lib   

You can adjust the search path by editing bin/LocalLib.cfg

So three dependencies need to be installed. This directory also contains a tool for checking for missing dependencies:

perl dependencies

displays the same information, but doesn’t change anything, it just performs a check. Although these dependencies can be installed from a CPAN repository for Perl, it’s just as easy to install them from the ports collection:

pkg install p5-CGI
pkg install p5-File-Copy-Recursive
pkg install p5-JSON

A bit of googling and lateral thinking may be required to translate the CPAN names to the FreshPorts names!

Then check dependencies again just to be sure:

perl dependencies

and take a look at the output to see that no dependencies are missing. If all is good the same command can be sent again:

perl rewriteshebang.pl

confirm the changes when it asks, should all be good responding yes throughout. This just makes sure that Foswiki is set up with the correct path to the perl interpreter.

Now go up a level to the main Foswiki directory:

cd ..

so that this is the current directory:

/usr/local/www/foswiki

At this point Apache doesn’t know anything about Foswiki. The Foswiki configuration file has to be put somewhere that Apache can see it. This location is defined in the very last line of httpd.conf. Start a blank, new file in that location.

nano /usr/local/etc/apache24/Includes/foswiki.conf

Now use the Foswiki website automatic configurator to make the text of the foswiki.conf file. Under the section of that web page called "File system paths" the path should be entered as /usr/local/www/foswiki.

Copy the text out of the configurator web page in to the blank file in nano. Be careful to make sure the top few lines are all commented out; all that configuration stuff with the equals signs in must be commented out. There's another line further down that's word wrapped when it shouldn't. It's the line that starts with the word AuthName. If the unmodified file is run the perl interpreter will spit out the line numbers that are a problem. It's an easy fix.

The new foswiki.conf file is now installed in the Apache “Includes" directory.

The rewrite command for short URLs won’t work because the correct module is not enabled in httpd.conf. Open that file up:

nano /usr/local/etc/apache24/httpd.conf

Then hunt for this line and remove the # sign that’s in front of it.

# LoadModule rewrite_module libexec/apache24/mod_rewrite.so

It should now look like this:

LoadModule rewrite_module libexec/apache24/mod_rewrite.so

The cgi module also needs to be enabled in the httpd.conf file:

<IfModule !mpm_prefork_module>
    #LoadModule cgid_module libexec/apache24/mod_cgid.so
</IfModule>
<IfModule mpm_prefork_module>
    LoadModule cgi_module libexec/apache24/mod_cgi.so
</IfModule>

The line that starts with "LoadModule cgi_module" needs to be uncommented, as shown above. Foswiki also needs the "expires" module enabled by removing the # from in front of it, like the others:

LoadModule expires_module libexec/apache24/mod_expires.so

Foswiki is deliberately installed with owner and group permissions not quite ready to go. The perl files in the bin directory need to be executable by the user called www; the config files in the installation need to be readable and writeable by www. Foswiki provides a tool to take care of this: fix_file_permissions.sh in the tools directory; but the file needs to be edited first, like this:

nano tools/fix_file_permissions.sh

This script file has been set up for Linux and needs a little tweak for FreeBSD: change line 9 to read:

OPT=-vv

This echoes the program output to the FreeBSD console. There's a comment in the file that provides a clue. Now do this:

sh tools/fix_file_permissions.sh

To make the changes take effect the apache server needs to be restarted:

service apache24 restart

On a browser window pull up the URL 192.168.1.xxx/foswiki and this will throw up the configuration page.

Foswiki/config

Install p5-LWP-Protocol-https from the ports collection to enable Foswiki to manage extensions:

pkg install p5-LWP-Protocol-https

It takes a while to muddle through the config page but it's self-explanatory for the most part. The most important thing is to set a password for the admin user. Then a new user should be created, yourself, with admin level permissions.

In updating the extensions Foswiki will complain about a few missing dependencies:

• libapreq2 is the equivalent in FreshPorts of Apache2::Request in CPAN
• ap24-mod_perl2 is the equivalent in FreshPorts of mod_perl2 in CPAN
• p5-FCGI is the equivalent in FreshPorts of FCGI in CPAN
• p5-FCGI-ProcManager is the equivalent in FreshPorts of FCGI::ProcManager in CPAN

Other Thoughts

I found Apache (when used with Foswiki) to be a bit sensitive to the network setup. In httpd.conf I left out the server name as Apache seems quite happy to pick it up automatically. But I also made sure that there was an entry in /etc/hosts that connects the name of the FreeBSD machine, specified in /etc/rc.conf, with it's static IP address.

-- StefanRactliffe - 05 Nov 2017

---

Note that the SystemRequirements document has a section on installing dependencies on BSD. It suggests:

     pkg install p5-Algorithm-Diff p5-Archive-Tar p5-Authen-SASL p5-CGI p5-CGI-Session p5-Crypt-PasswdMD5 p5-Digest-SHA p5-Email-MIME p5-Encode p5-Error p5-File-Copy-Recursive p5-HTML-Parser p5-HTML-Tree p5-IO-Socket-IP p5-IO-Socket-SSL p5-JSON p5-Locale-Maketext p5-Locale-Maketext-Lexicon p5-Locale-Msgfmt p5-libwww p5-LWP-Protocol-https p5-URI p5-version 

Thanks for the notes about libapreq2 and ap24-mod_perl2, we didn't have the package names for FreeBSD

Also note that you won't need p5-FCGI-ProcManager when running on Apache. Apache manages the fcgi back-end tasks automatically. The ProcManager is needed for nginx.

-- Main.GeorgeClark - 07 Nov 2017 - 00:53

Commenting is disabled while not logged in