FreeBSD 7.0 Deki Installation Guide

1. IMPORTANT NOTICE

This content was contributed to the Deki Wiki developer community. It has not been reviewed for technical accuracy by MindTouch. If you find an error please contact me or use the comment field at the bottom of the document.

2. Overview

I wanted to install Deki on FreeBSD 7.0 for a jailed multi-tenant production server. This install guide covers just getting Deki installed and running on FreeBSD for one instance of Deki and does not offer a guide to jailed multi-tenant installation. I make no warranty about this guide other than it worked for me.

The guide assumes you can log into your server and assume the role of superuser to install the required software and that you are familiar with installing software from ports. If you need further help on installing ports and server software for FreeBSD 7.0 I would refer you to the excellent book Building a Server with FreeBSD 7 by Bryan J. Hong.

If your server has all the prerequisites installed skip to step 4.

 

3. Fresh Install - This guide is for a fresh install of Deki and assumes you don't have the following installed. If you do have some of them installed just make sure you install the required dependancies and move on to the Deki installation instructions below.

Prerequisites: I did a fresh install with the following software packages using their FreeBSD ports:

• Apache 2.x
• PHP 5.x and PHP Extensions
• MySQL 5.x
• Mono 1.2.x
• And the following: IMAGEMAGICK, HTML2PS, HTML2TEXT, HTMLDOC, LINKS, PDFTOHTML, WV

 

3.1    Install Apache 2.x

For this guide I've installed Apache 2.2.x

Notes: It is very important that when you "make config" you select the proxy options available. Apache is installed in the following:

- Configuration files path: /usr/local/etc/apache22
- Web server data path: /usr/local/www/apache22/data

 Ok, let's get started, use the following commands to install Apache remembering to select the following proxy options when in the config option screen; Enable mod_proxy, mod_proxy_connect, mod_proxy_ftp, mod_proxy_http.

 

cd /usr/ports/www/apache22
make config
make install clean
rehash

 

3.2 Install PHP 5.x

Notes: Make sure you select the APACHE and MULTUBYTE options from the config options screen

Ok, let's install PHP

cd /usr/ports/lang/php5
make config
make install clean
rehash 

 

Install PHP Extensions

Notes: Make sure to select the following options from the config options screen: CURL, GD, MBSTRING, MCRYPT, MHASH, MYSQL, ZLIB.

Also note that when Posix is installed and if you are installing version 5.2.6 it has a known vulnarability but is considered minor and can still be installed but will require you to use this command to install it: make -DDISABLE_VULNERABILITIES install. If your install of PHP Extensions fails because of Posix you can install Posix separately with the above command and then reinstall PHP Extensions.

Ok, let's install the PHP Extensions

cd /usr/ports/lang/php5-extensions
make config
make install clean
rehash

 

3.3 Install MySQL 5.0.x

cd /usr/ports/databases/mysql50-server
make -D BUILD_OPTIMIZED install clean
rehash

Post install commands to create root password, setup conf file and start MySQL

mysql_install_db --user=mysql
mysqld_safe &
mysqladmin -u root password 'newpassword'
mysqladmin -u root -h my.domain.com password 'newpassword'

Note my-medium.cnf can be substituted for a more robust config if needed but this should do

cp /usr/local/share/mysql/my-medium.cnf /var/db/mysql/my.cnf

Now we'll make sure MySQL starts up on any server restart by editing the rc.conf file and add 'mysql_enable="YES"' to the file and save.

ee /etc/rc.conf

3.4 Install Mono 1.2.x

cd /usr/ports/lang/mono
make install clean

 

3.5 Install Other Dependancies

Install IMAGEMAGICK

cd /usr/ports/graphics/ImageMagick
make install clean
rehash

Install HTML2PS

cd /usr/ports/print/html2ps-a4
make install clean
rehash

Install HTML2TEXT

cd /usr/ports/textproc/html2text
make install clean
rehash

Install HTML2DOC

cd /usr/ports/textproc/htmldoc
make install clean
rehash

Install LINKS

cd /usr/ports/www/links
make install clean
rehash

Install PDFTOHTML

cd /usr/ports/textproc/pdftohtml
make install clean
rehash

Install WV

cd /usr/ports/textproc/wv
make install clean
rehash

 

4.0    Installing Deki From the Source Files

Download Deki and upload to your home directory or anywhere you want on your server. I've used Deki Jay Cooke 8.05.2b for this example.

 

Ok, let's start the install process. In the directory you uploaded the Deki source do the following:

tar xfvz Deki_Wiki_8.05.2b_Jay_Cooke_source.tar.gz
cd Deki_Wiki_8.05.2b_Jay_Cooke_source
mkdir /usr/local/www/apache22/data/dekiwiki
cp -r web/*  /usr/local/www/apache22/data/dekiwiki
chown -R www /usr/local/www/apache22/data/dekiwiki

 

4.1   Configure Apache

Edit the ./config/deki-apache.conf file:

Change the following values according to your setup:

 

ServerName YourServerName
DocumentRoot "/usr/local/www/apache22/data/dekiwiki"

<Directory "/usr/local/www/apache22/data/dekiwiki">

Now we need to create sites-available and sites-enabled directories and copy the config file:

 

mkdir /usr/local/etc/apache22/sites-available
mkdir /usr/local/etc/apache22/sites-enabled
cp config/deki-apache.conf /usr/local/etc/apache22/sites-available/deki
ln -s /usr/local/etc/apache22/sites-available/deki /usr/local/etc/apache22/sites-enabled/001-deki

 

Now we need to edit the Apache configuration file to include our new site. Using your favorite editor such as ee:

 

ee /usr/local/etc/apache22/httpd.conf

add the include path to Deki sites-enabled

Include etc/apache22/sites-enabled 

 

 

4.2   Create Log File Paths for Deki and API

 

mkdir /var/log/apache2
mkdir /var/log/dekiwiki
touch /var/log/dekiwiki/deki-api.log
chown www /var/log/dekiwiki/deki-api.log

 

4.3   Create Mono .wapi Directory

mkdir /usr/local/www/apache22/data/.wapi
chown www /usr/local/www/apache22/data/.wapi

 

4.4   Create the Deki Wiki Init Script

Mindtouch provides several scripts for various platforms to get initialize Deki using Mono howerver none of them work for FreeBSD. So I had to write one myself that worked for FreeBSD. First we need to change diretories to where we're going to create the script.

cd /usr/local/etc/rc.d/

now using your favorite editor let's create the script file

ee dekiwiki

now copy and paste or type the following into your editor

#!/bin/sh
#
# $FreeBSD: ports/lang/mono/files/mono.sh.in,v 1.2.5.1_1 2008/07/25 22:46:14 clement Exp $
#
# Init file for Deki Wiki host daemon by Marc Boucher -- marc.boucher at onorbit.com
#


# PROVIDE: mono
# REQUIRE: LOGIN
# KEYWORD: shutdown

. /etc/rc.subr

name="mono"
rcvar=`set_rcvar`

# variables

prog="MindTouch Deki Host Service"
DEKIHOST_CONF="/etc/dekiwiki/mindtouch.host.conf"


# conditionals

if [ ! -f $DEKIHOST_CONF ]; then
    echo "$DEKIHOST_CONF does not exist"
    exit 1
fi

. $DEKIHOST_CONF

# set default values if not specified in $DEKIHOST_CONF

if [ ! -f "$MONO" ]; then
    echo "Please specify the full path to your mono binary"
    exit 1
fi

if [ ! -d "$BIN_DIR" ]; then
    echo "Please specify the path to your DekiWiki bin directory"
    exit 1
fi

if [ -z "$APIKEY" ]; then
    echo "Please specify your APIKEY"
    exit 1
fi

if [ -z "$PATH_PREFIX" ]; then
    PATH_PREFIX="@api"
fi

if [ -z "$HTTP_PORT" ]; then
    HTTP_PORT="8081"
fi

if [ -z "$IP" ]; then
    IP="localhost"
fi

if [ -z "$HOST_EXE" ]; then
    HOST_EXE="$BIN_DIR/mindtouch.host.exe"
fi

if [ -z "$SCRIPT" ]; then
    SCRIPT="/etc/dekiwiki/mindtouch.deki.startup.xml"
fi

if [ -z "$NOTTY" ]; then
    NOTTY="notty"
fi

if [ -z "$CONNECT_LIMIT" ]; then
    CONNECT_LIMIT="-5"
fi

if [ -z "$LOGDIR" ]; then
    LOGDIR="/var/www/dekiwiki"
fi

if [ -z "$LOGFILE" ]; then
    LOGFILE="$LOGDIR/deki-api.log"
fi

# more variables
MONO_ARGS="${HOST_EXE} apikey ${APIKEY} script ${SCRIPT} path-prefix ${PATH_PREFIX} http-port ${HTTP_PORT} ip ${IP} connect-limit ${CONNECT_LIMIT} ${NOTTY}"


# commands
command="/usr/local/bin/${name}"
command_args="${MONO_ARGS} >> ${LOGFILE} 2>&1 &"

load_rc_config $name
run_rc_command "$1"

save, close and set the permissions and your script is ready to go.

chmod 555 /usr/local/etc/rc.d/dekiwiki

 

Now we have to edit the rc.conf (system configuration file) so that Mono starts whenever the server boots up:

 

ee /etc/rc.conf

add the mono enable line

mono_enable="YES"

and in case you don't already have this, add this line

apache22_http_accept_enable="YES"

 

Congratulations you are now ready for the web install portion of the setup.

 

 

5.0   Setup with Web Installer

Open up and browserand go to one of these addresses depednign on you setup your config files:

http://dekiwiki/config/index.php

http://YourServerIP/config/index.php or

http://www.yourdomain.com/config/index.php

 

Follow the  prompts fof the web install.

 

5.1   Post Web Install

We need to copy the Mindtouch conf files your created during the web installer phase and clean up a bit.

 

cd /usr/local/www/apache22/data/dekiwiki/config
mkdir /etc/dekiwiki
cp -p mindtouch.host.conf /etc/dekiwiki
cp -p mindtouch.deki.startup.xml /etc/dekiwiki
cp -p LocalSettings.php /usr/local/www/apache22/data/dekiwiki

and lastly start Deki

/usr/local/etc/rc.d/dekiwiki start

 

March 20, 2009 - Addendum

When upgrading to PHP 5.2.9 you may encouter an error that prevents Deki from loading. The error found in your /var/log/httpd-error.log may look like this:

 

PHP Warning:  PHP Startup: Unable to load dynamic library '/usr/local/lib/php/20060613/<wbr/>pcre.so' - /usr/local/lib/php/20060613/<wbr/>pcre.so: Undefined symbol &quot;php_pcre_free&quot; in Unknown on line 0
 

This is because the upgraded php5-pcre port does not have the "Bundled PCRE" option selected. To fix this problem you need deinstall the port then make config and select the "Bundled PCRE" option and then make reinstall.

cd /usr/ports/devel/php5-pcre
deinstall
make config (make sure to select "Bundled PCRE")
make reinstall

Restart Apache and Deki and you're good to go.