Most of our server platforms are running Linux of one kind or another. Occasionally requirements arise that FreeBSD platforms are needed to allow projects to proceed. In this article we present a record of a recent setup for our test server running FreeBSD 8.1 as a guest on VMware. It covers installation of Apache, MySQL, and PHP for preparation of installing Joomla! 1.5.

Here we assume you have already had a basic installation of FreeBSD 8.1 on your machine, virtual or otherwise. And, of course, you have to be the root user to add packages and modify configurations. We will go ahead and describe the installation and setup of necessary packages so that Joomla! 1.5 can be successfully installed.

Update the ports tree

Even though we tried to rely on the package repository exclusively for our installations, there are situations we had to make use of the ports tree. So it's better to have up-to-date ports tree. The commands for fetching complete ports tree are:

# portsnap fetch
# portsnap extract 

It takes a little while to retrieve and uncompress the directory structure. Please be patient. Once it's done, you should see a full ports tree at /usr/ports.

Install Apache 2.2.x HTTP server

Apache 2.2 can be installed from the package repository using

# pkg_add -r apache22 

Once Apache 2.2 is installed, comment out LoadModule lines in file /usr/local/etc/apache22/httpd.conf to disable any modules you are not using. For instance, many auth* modules can be disabled for a public server, except authz_host is required for the Order directive.

Near the end of the file /usr/local/etc/apache22/httpd.conf, please uncomment these two lines and others you feel appropriate, for example, the line for SSL.

Include etc/apache22/extra/httpd-mpm.conf
Include etc/apache22/extra/httpd-default.conf 

To let Apache start automatically when the system starts, enter this command:

# echo apache22_enable=\"YES\" >> /etc/rc.conf 

Also enable AcceptFilter suport in FreeBSD kernel:

# echo apache22_http_accept_enable=\"YES\" >> /etc/rc.conf 

That takes care of loading accf_http kernel module at system startup. To manually load the module, use

# kldload accf_http 

The utility of accf_http is such that a server will not have to context switch several times before performing the initial parsing of the request. Use this command to check whether the accf_http kernel module is successfully loaded:

# kldstat | grep accf_http 

To start Apache HTTP server, you may restart the system or enter command:

# service apache22 start 

You can point your browser to that server's URL and see whether Apache is serving the default page.

Install mod_fcgid

To make running PHP scripts more efficient and less memory hungry, we will utilize mod_fcgid. It's a Apache module for FastCGI execution. There is not a precompiled mod_fcgid package for Apache 2.2 in FreeBSD 8.1, thus we will install it from the ports tree.

# cd /usr/ports/www/mod_fcgid
# make install
# make clean 

Append following lines to other LoadModule lines in /usr/local/etc/apache22/httpd.conf to enable mod_fcgid:

LoadModule fcgid_module libexec/apache22/mod_fcgid.so
<IfModule>
    AddHandler fcgid-script .fcgi
</IfModule>

Next time Apache starts, it will load fcgid_module. Later we will configure PHP to run under fcgid_module.

Install PHP 5.3.x

The Current PHP5 package in FreeBSD 8.1 contains PHP 5.3.2, which has FastCGI support compiled in. Also, PHP 5.3.2 includes an FPM (FastCGI Process Manager) API which is supposedly more efficient at managing PHP processes. But, for now, we chose not to enable FPM and simply install the precompiled package.

# pkg_add -r php5

Make sure the installed PHP CGI interpreter indeed has FastCGI support:

# php-cgi -v

You should see something like this:

PHP 5.3.2 with Suhosin-Patch (cgi-fcgi) (built: Jun 12 2010 00:11:09)
Copyright (c) 1997-2009 The PHP Group
Zend Engine v2.3.0, Copyright (c) 1998-2010 Zend Technologies

Notice the cgi-fcgi in parentheses denotes the FastCGI support.

You need a PHP configuration file php.ini located in /usr/local/etc. The file php.ini-production is a good starting point.

# cd /usr/local/etc
# cp php.ini-production php.ini

Now edit time zone setting in php.ini. Open /usr/local/etc/php.ini, and look for date.timezone line in the [Date] section. Modify that line to reflect your server's time zone. For instance,

[Date]
date.timezone = "America/New_York"

This stops Apache complaining about time zone setting, and is a safe practice.

Next, set session.save_path in php.ini to a proper directory on your server. While this is not necessary for running Joomla! 1.5, it prevents a warning message from showing during installation. Please edit /usr/local/etc/php.ini. In [Session] section, uncomment the line session.save_path and set it to, say, /var/tmp.

[Session]
session.save_path = "/var/tmp"

Now we need to make PHP work with mod_fcgid. Create a file named fcgid-php.conf in /usr/local/etc/apache22/Includes with the following lines:

<IfModule>
    # Cause the PHP interpreter to handle files with a .php extension.
    AddHandler fcgid-script .php
    AddType text/html .php    

    # Add index.php to the list of files that will be served as directory
    # indexes.
    DirectoryIndex index.php    

    # Where to look for the php.ini file?
    #DefaultInitEnv PHPRC        "/etc/php5/cgi"    

    # Maximum requests a process handles before it is terminated
    MaxRequestsPerProcess       1000    

    # Maximum number of PHP processes
    MaxProcessCount             10    

   # Number of seconds of idle time before a process is terminated
    IPCCommTimeout              240
    IdleTimeout                 240    

    # Command used to spawn FCGI server processes
    FCGIWrapper /usr/local/bin/php-cgi .php
</IfModule>

Create a file /usr/local/www/apache22/cgi-bin/phpinfo.php with a single line:

<?php phpinfo(); ?>

Point your browser to http://<your domain name>/cgi-bin/phpinfo.php. It should show the PHP information page if everything works as supposed.

There are some additional PHP extensions which are nice to have. Some of them are required by certain popular Joomla! 1.5 extensions, and some are required in the coming Joomla! 1.6.

# pkg_add -r php5-mysqli
# pkg_add -r php5-mbstring
# pkg_add -r php5-json
# pkg_add -r php5-dom

Install MySQL 5.1.x

Presently MySQL 5.5 is the newest version on FreeBSD 8.1 repository. But, since it is still in beta, we will use MySQL 5.1 instead.

# pkg_add -r mysql51-server

This will have both MySQL 5.1 server and client installed.

There are several legitimate locations where MySQL configuration file, my.cnf, can be placed. We will put it in the directory /usr/local/etc. You can copy an appropriate sample configuration file from /usr/local/shared/mysql to become /usr/local/etc/my.cnf. Then please edit /usr/local/etc/my.cnf and add following lines in their corresponding sections:

[client]
default-character-set = utf8

[mysqld]
# Comment this line out if you don't want to use InnoDB as the default engine.
default-storage-engine = innodb
default-character-set = utf8
default-collation = utf8_general_ci

You must also uncomment those lines begins with innodb_ when InnoDB is set to be the default database engine.

To enable MySQL to start at system boot-up, do this

# echo mysql_enable=\"YES\" >> /etc/rc.conf

MySQL server can be started manually with the command:

# service mysql-server start

Don't forget to set MySQL's root user password:

# mysqladmin -u root password <password you want>

Of course, you will enter your own desired password in place of <password you want>.

Install Joomla! 1.5

At last we come to the purpose of this guide. The installation of joomla15 package for FreeBSD will automatically fetches and installs any dependent packages. However, one of the required packages, pdflib, doesn't exist on the FreeBSD package repository. You will have to compile and install it from the portage before you proceed to install joomla15 package.

# cd /usr/ports/print/pdflib
# make install
# make clean

Albeit the joomla15 package contains Joomla! 1.5.18 which is an outdated version, we will use it to bring in all the dependencies, and later update it to the most recent version.

# pkg_add -r joomla15

You will see a long list of packages get installed due to dependencies.

To download the latest version of Joomla! 1.5, you can visit http://www.joomla.org/download.html and find and fetch the latest version of the file format you want. For instance,

# fetch http://joomlacode.org/gf/download/frsrelease/12610/53419/Joomla_1.5.20-Stable-Full_Package.tar.bz2

We then remove all the files in the directory /usr/local/www/joomla15, which are installed by joomla15 package, and replace them with files from the latest Joomla! 1.5 version.

# rm -rf /usr/local/www/joomla15/*
# cd /usr/local/www/joomla15
# tar -jxvf /<your download folder>/Joomla_1.5.20-Stable-Full_Package.tar.bz2

Please substitute the filename of the version you downloaded for the one in the last command.

Let's adjust the owner and permission of those files.

chown -R www:www *
chmod -R o-rwx *

Create your Joomla! 1.5 site

Leave the directory /usr/local/www/joomla15 alone, and make a copy of it for your site. For example,

cd /usr/local/www
cp -Rp joomla15 <your site>
chown www:www <your site>

For Aapache HTTP server must know about this site, we will create a NameVirtualHost for it. First, edit /usr/local/etc/apache22/httpd.conf, and uncomment the line

Include etc/apache22/extra/httpd-vhosts.conf

Open the file /usr/local/etc/apache22/extra/httpd-vhosts.conf, comment out all the lines for VirtualHost examples. Add the following lines to the file:

#
# <your site>
#
<VirtualHost *:80>
    ServerAdmin webmaster@<your domain name>
    DocumentRoot "/usr/local/www/<your site>"
    ServerName <your domain name>
    ServerAlias www.<your domain name>
    ErrorLog "/var/log/<your site>-error_log"
    CustomLog "/var/log/<your site>-access_log" common
    <Directory "/usr/local/www/<your site>">
        Order Allow,Deny
        Allow From All
        AllowOverride All
        Options Indexes FollowSymLinks ExecCGI
    </Directory>
</VirtualHost>

Please replace <your site> and <your domain name> with your own values.

Check Apache HTTP server configureation:

# /usr/local/etc/rc.d/apache22 configtest

Fix any configuration problems, and then restart Apache.

# service apache22 restart

Before running Joomla! 1.5 installer, you need to create a MySQL database and a database user with proper permission to access that database. To create MySQL database, issue the command:

# mysqladmin -u root -p create <your db>

You will be asked to enter the password for MySQL root user.

Now let's use the MySQL client program to create a user and grant that user permissions.

# mysql -u root -p

Once you are at the client program's command prompt, enter this command:

mysql> grant all privileges on <your db>.* to <db user>@localhost identified by '<db password>'

There <your db> is the newly created MySQL database, <db user> is the username used to access that database, and <db password> is the password for that user.

Additional customizations

At this point you can point your browser to your site's URL as entered in VirtualHost configuration, and follow the steps to get your Joomla! 1.5 site installed. After installation, you can log onto the administrator backend for further customizations.

You may want to configure SEO settings to get search engine optimized URLs for your Web site. First, enable these two features in the Global Configuration.

Search Engine Friendly URLs
Add suffix to URLs

The URLs of links on your site should become something similar to http:/<your domain name>//index.php/joomla-license.html.

If after you enabled Search Engine Friendly URLs and got broken Web pages when following a link on your site, please make sure the file configuration.php in your Joomla! 1.5 directory has the $live_site variable correctly set. For example,

var $live_site = 'http://<your domain name>';

To remove the string index.php in the URL, you will have to enable the last SEO setting:

Use Apache mod_rewrite

And copy or rename htaccess.txt to .htaccess. In the file .htaccess, if the following line gives error, please comment it out.

Options +FollowSymLinks

That's because we have already the line in the VirtualHost configuration. Your Apache configuration probably doesn't allow changing Options, and we have already set the FollowSymLinks option in the VirtualHost configuration. You may have to restart your HTTP server to see the effects of the changes.