blog.Tiaan.com   Web log of Tiaan Geldenhuys

It is technically possible to run a website on Mono (the open-source .NET development framework) using the Shared Hosting servers at DreamHost. The technique makes use of the pre-installed FastCGI module that is available on DreamHost’s Apache web servers, which is then configured to dynamically start the Mono FastCGI Backend. Just like for any other dynamic FastCGI server (such as for PHP FastCGI), the FastCGI module of Apache would monitor and manage the Mono FastCGI persistent processes and start/stop them as needed, in line with DreamHost’s configured FastCGI policy. The Mono FastCGI Backend is distributed as part of Mono’s XSP package, which needs to be built and installed along with all the other supporting Mono binaries. This procedure is detailed below, and an example Apache configuration is also provided for a basic Mono web-application that contains some standard ASP.NET pages (.aspx files) and a Web Service (.asmx file). With that in place, you can explore the rest of what Mono has to offer on a shared web server.

Compile and Install Mono

The most difficult and time-consuming part of getting the Mono website up and running may be to compile and install the Mono binaries. However, you just need to follow the steps in the shell script shown below to accomplish this. To make sure that everything goes according to plan and to have the opportunity to intervene if something does go wrong, you might want to run this script manually and copy-and-paste it step-by-step into your shell/console (simply check for error message that would be shown above the prompt after each step completes execution). Alternatively, if you insist on running this as an automated script, I would recommend that you insert programmatic error-checks: for example, after each wget, tar, make and configure step, you can insert the line “if [ $? -ne 0 ]; then exit 1; fi”, which would abort the script if something goes wrong. (Either way, there are about 84 places where you should check for successful progress along the way.) Also, note that not all the packages are essential to get Mono running: for example, libxml2 and libxslt are only included so that the xsltproc utility becomes available (which is needed if you want to run some of Mono’s unit-tests after the build). Similarly, if you do not intend to use the Visual Basic .NET (VB.NET) language, the mono-basic package is not needed. Furthermore, if no graphics-related functionality is required by your .NET applications (that is, GDI+ or the System.Drawing namespace), then neither Mono’s libgdiplus package nor its dependencies are needed (such as zlib, libpng, libjpeg/jpegsrc, libexif, libtiff/tiff and giflib). But if you want it all, the complete build-and-install script is as follows (download the mono-2.6.7-build-example.sh script):

#!/bin/sh

# ===================================================================

# Download, build and install the Mono .NET-compatible Framework...

# ===================================================================

# ===================================================================

# Setup and initialization

# -------------------------------------------------------------------

# Define some common variables

# TODO: Remember to use your own domain name (DreamHost directory name)

export DOMAIN="example.com"

mono_dir="${HOME}/mono-2.4.2.3"

mono_src="${HOME}/src/mono-build"

# Create a few directories (maybe not needed, but it shouldn't hurt)

mkdir -p "${mono_dir}"

mkdir -p "${mono_dir}/etc"

mkdir -p "${mono_src}"

# Setup the source environment variables to ensure that any custom 

# pkg-config libraries can be located and progressive compilations 

# can use the C# compiler and other Mono tools

export DYLD_LIBRARY_PATH="${mono_dir}/lib:${DYLD_LIBRARY_PATH}"

export LD_LIBRARY_PATH="${mono_dir}/lib:${LD_LIBRARY_PATH}"

export LIBRARY_PATH="${mono_dir}/lib:${LIBRARY_PATH}"

export C_INCLUDE_PATH="${mono_dir}/include"

export CPLUS_INCLUDE_PATH="${mono_dir}/include"

export ACLOCAL_PATH="${mono_dir}/share/aclocal"

export PKG_CONFIG_PATH="${mono_dir}/lib/pkgconfig:${PKG_CONFIG_PATH}"

export PATH="${mono_dir}/bin:${PATH}"

# ===================================================================

# Get and extract Mono and related packages/extensions

# -------------------------------------------------------------------

cd "${mono_src}"

wget -c "http://ftp.gnu.org/pub/gnu/libiconv/libiconv-1.13.1.tar.gz"

wget -c "http://ftp.gnu.org/pub/gnu/gettext/gettext-0.17.tar.gz"

wget -c "http://iweb.dl.sourceforge.net/project/libexif/libexif/0.6.18/libexif-0.6.18.tar.bz2"

wget -c "http://www.zlib.net/zlib-1.2.3.tar.gz"

wget -c "http://iweb.dl.sourceforge.net/project/libpng/00-libpng-stable/1.2.40/libpng-1.2.40.tar.gz"

wget -c "http://www.ijg.org/files/jpegsrc.v7.tar.gz"

wget -c "ftp://ftp.remotesensing.org/pub/libtiff/tiff-3.9.1.tar.gz"

wget -c "http://iweb.dl.sourceforge.net/project/giflib/giflib%204.x/giflib-4.1.6/giflib-4.1.6.tar.bz2"

wget -c "http://ftp.gnu.org/gnu/bison/bison-2.4.1.tar.bz2"

wget -c "http://xmlsoft.org/sources/libxml2-2.7.6.tar.gz"

wget -c "http://xmlsoft.org/sources/libxslt-1.1.26.tar.gz"

wget -c "http://ftp.gnome.org/pub/GNOME/sources/glib/2.22/glib-2.22.2.tar.bz2"

wget -c "http://ftp.novell.com/pub/mono/sources/libgdiplus/libgdiplus-2.4.2.tar.bz2"

wget -c "http://ftp.novell.com/pub/mono/sources/mono/mono-2.4.2.3.tar.bz2"

wget -c "http://ftp.novell.com/pub/mono/sources/xsp/xsp-2.4.2.tar.bz2"

wget -c "http://ftp.novell.com/pub/mono/sources/mono-basic/mono-basic-2.4.2.tar.bz2"

nice -n 19 tar -xzf "libiconv-1.13.1.tar.gz"

nice -n 19 tar -xzf "gettext-0.17.tar.gz"

nice -n 19 tar -xjf "libexif-0.6.18.tar.bz2"

nice -n 19 tar -xzf "zlib-1.2.3.tar.gz"

nice -n 19 tar -xzf "libpng-1.2.40.tar.gz"

nice -n 19 tar -xzf "jpegsrc.v7.tar.gz"

nice -n 19 tar -xzf "tiff-3.9.1.tar.gz"

nice -n 19 tar -xjf "giflib-4.1.6.tar.bz2"

nice -n 19 tar -xjf "bison-2.4.1.tar.bz2"

nice -n 19 tar -xzf "libxml2-2.7.6.tar.gz"

nice -n 19 tar -xzf "libxslt-1.1.26.tar.gz"

nice -n 19 tar -xjf "glib-2.22.2.tar.bz2"

nice -n 19 tar -xjf "libgdiplus-2.4.2.tar.bz2"

nice -n 19 tar -xjf "mono-2.4.2.3.tar.bz2"

nice -n 19 tar -xjf "xsp-2.4.2.tar.bz2"

nice -n 19 tar -xjf "mono-basic-2.4.2.tar.bz2"

# ===================================================================

# Build packages

# -------------------------------------------------------------------

# libiconv

cd "${mono_src}/libiconv-1.13.1"

./configure --enable-extra-encodings "--prefix=${mono_dir}"

nice -n 19 make

nice -n 19 make install

# gettext

cd "${mono_src}/gettext-0.17"

./configure "--prefix=${mono_dir}"

nice -n 19 make

nice -n 19 make install

# Rebuild libiconv, again after gettext; recommended 

# on the GNU page http://www.gnu.org/software/libiconv/

cd "${mono_src}/libiconv-1.13.1"

nice -n 19 make distclean

./configure --enable-extra-encodings "--prefix=${mono_dir}"

nice -n 19 make

nice -n 19 make install

# libexif

cd "${mono_src}/libexif-0.6.18"

./configure "--prefix=${mono_dir}"

nice -n 19 make

nice -n 19 make install

# zlib

cd "${mono_src}/zlib-1.2.3"

./configure "--shared" "--prefix=${mono_dir}"

nice -n 19 make

nice -n 19 make install

# libpng

cd "${mono_src}/libpng-1.2.40"

./configure "--prefix=${mono_dir}"

nice -n 19 make

nice -n 19 make install

# jpegsrc

cd "${mono_src}/jpeg-7"

./configure "--prefix=${mono_dir}"

nice -n 19 make

nice -n 19 make install

# libtiff

cd "${mono_src}/tiff-3.9.1"

./configure "--prefix=${mono_dir}"

nice -n 19 make

nice -n 19 make install

# giflib

cd "${mono_src}/giflib-4.1.6"

./configure "--prefix=${mono_dir}"

nice -n 19 make

nice -n 19 make install

# bison

cd "${mono_src}/bison-2.4.1"

./configure --without-libintl-prefix "--prefix=${mono_dir}"

nice -n 19 make

nice -n 19 make install

# libxml2

cd "${mono_src}/libxml2-2.7.6"

./configure "--with-iconv=${mono_dir}" \

    "--with-zlib=${mono_dir}" "--prefix=${mono_dir}"

nice -n 19 make

nice -n 19 make install

# libxslt

cd "${mono_src}/libxslt-1.1.26"

./configure "--prefix=${mono_dir}" "--with-iconv=${mono_dir}"

nice -n 19 make

nice -n 19 make install

# glib

cd "${mono_src}/glib-2.22.2"

./configure --with-libiconv=gnu "--prefix=${mono_dir}"

nice -n 19 make

nice -n 19 make install

# libgdiplus

cd "${mono_src}/libgdiplus-2.4.2"

./configure --with-libexif --with-libjpeg \

    --with-libtiff --with-libgif "--prefix=${mono_dir}"

nice -n 19 make

nice -n 19 make install

# ===================================================================

# Build Mono core and extensions

# -------------------------------------------------------------------

# Mono

cd "${mono_src}/mono-2.4.2.3"

./configure "--prefix=${mono_dir}"

nice -n 19 make

nice -n 19 make install

# XSP, including Mono's FastCGI support

cd "${mono_src}/xsp-2.4.2"

./configure "--prefix=${mono_dir}"

nice -n 19 make

nice -n 19 make install

# Basic (alternative Mono language, similar to .NET's Visual Basic)

cd "${mono_src}/mono-basic-2.4.2"

./configure "--prefix=${mono_dir}"

nice -n 19 make

nice -n 19 make install

# ===================================================================

# Cleanup and wrap-up

# -------------------------------------------------------------------

# Remove intermediate source code, since it is no longer needed

cd ~

rm -rf "${mono_src}"

# Create a directory for the web-app launcher script

mkdir -p "${HOME}/${DOMAIN}/cgi-bin"

chmod 751 "${HOME}/${DOMAIN}/cgi-bin"

echo "             *************** INSTALL COMPLETE! ***************"

# ===================================================================

When you build your Mono environment, you may run into an error message similar to the following:

Yikes! One of your processes (xxx, pid 12345) was just killed because your
processes are, as a whole, consuming too much memory. If you believe you've
received this message in error, please contact Support.

If this happens, contact DreamHost Support and kindly request that they temporarily increase your memory allowance; DreamHost Support was very helpful with this and promptly relaxed the constraint (within 5 minutes!). Interestingly though, having analyzed some of the itemized resources logs afterwards for the build period, the maximum amounts of memory used by Mono processes were only about 40% of the maxima used by Java processes.

Once you have successfully completed the installation of Mono, you can add Mono’s executable path to your environment variables by inserting the following line into your ~/.bash_profile file. This way, you would have easy access to the Mono Framework whenever you log into the interactive shell:

PATH=~/mono-2.4.2.3/bin:$PATH

You should now be able to type something like “mono --version” at the command prompt and get back a message starting with “Mono JIT compiler version 2.4.2.3”.  The next steps are to create and configure your Mono website, and to get the basics up and running should take much less effort than the preceding setup.

Configure Apache and the .NET Website

The entire directory structure of the example Mono website is as follows (in an edited and abbreviated format similar to what you’d get from a Unix “ls -alR” command):

/home/username/example.com:
drwxr-xr-x username groupname .
drwxr-x--x username groupname cgi-bin
drwxr-x--x username groupname mono-web
-rw-r--r-- username groupname .htaccess
-rw-r--r-- username groupname index.html

/home/username/example.com/cgi-bin:
-rwxr-x--x username groupname mono-web-launcher.fcgi

/home/username/example.com/mono-web:
-rw-r--r-- username groupname .htaccess
-rw-r----- username groupname Default.aspx
-rw-r----- username groupname Default.aspx.cs
-rw-r----- username groupname Test.aspx
-rw-r----- username groupname WebService.asmx
-rw-r----- username groupname web.config

The contents of the essential configuration files are displayed below, but all the files of the example website can also be downloaded from this archive. If you are going to unzip the archive and use the contained files directly on a Unix box, ensure that the file access permissions are setup the same way as shown above (using the chmod command).

Let us start with the .htaccess file in the website domain directory, which simply contains some Apache configuration settings that will allow the static index.html page (or a dynamic index.php page) to be returned when visiting the “http://example.com/” home URL (there’s nothing fancy about this file):

# Don't show directory listings for URLs which map to a directory

Options -Indexes

# Follow symbolic links in directories

Options +FollowSymLinks

# Specify the default page names

DirectoryIndex index.php index.html

The mono-web-launcher.fcgi file (located in the cgi-bin directory) is where most of the configuration action happens; it is based on Mono’s default “~/mono-2.4.2.3/bin/fastcgi-mono-server2” FastCGI Backend script and has been customized for our specific Mono web-application. The added .fcgi filename extension clearly marks the file as a FastCGI script for Apache (more about this later).  In combination with the monoWrapper handler, which is defined later in the “mono-web/.htaccess” file, this script will launch Mono’s FastCGI Backend for the ASP.NET web-application when one of its pages is accessed. Be sure to change the values of HOME and DOMAIN at the top of the launcher script to match the names of your user’s home and website’s domain directories, respectively:

#!/bin/sh

# Specify the home directory, Mono directory, and the 

# domain name (that is, your DreamHost subdirectory name)

HOME=/home/username

DOMAIN=example.com

MONO_DIR=${HOME}/mono-2.4.2.3

# Define a temporary directory for dynamic compilation 

# using a private directory for added security; also, 

# prevent sporadic run-time errors such as the following:

#   Single file build failed / cannot find metadata file.

# Remember to create this directory and sometimes clear 

# it under controlled conditions as part of maintenance

export TEMP=${HOME}/mono-temp_do-not-delete

export MONO_ASPNET_NODELETE=1

# Include the Mono binaries in the path variable, since 

# the shell PATH is not used within the FastCGI context

export PATH=${MONO_DIR}/bin:$PATH

# Use case-insensitive file-system compatibility mode; 

# don't use this option unless you have to (it is slower)

export MONO_IOMAP=all

# Start the dynamic persistent FastCGI server of Mono 

# and register the web-application with its paths; the 

# FastCGI manager will stop this process when needed 

# according to policy (e.g., after some idle time)

exec mono $MONO_OPTIONS \

  ${MONO_DIR}/lib/mono/2.0/fastcgi-mono-server2.exe \

  /logfile=${HOME}/fastcgi-mono-web.log \

  /loglevels=Warning,Error \

  /applications=/mono-web/:${HOME}/${DOMAIN}/mono-web/ \

  "$@"

When you are initially trying to get the website installed and configured, you might also want to set the loglevels value to All, or Standard, and then monitor the configured Mono Backend log file to see what is happening (for example, located at “~/fastcgi-mono-web.log”). Of course, you can also look at the Apache log files for additional information. Be sure to familiarize you with the command-line options and environment variables that are available on the FastCGI Backend, especially the format of the applications value; for example, read the help info returned by:

mono ~/mono-2.4.2.3/lib/mono/2.0/fastcgi-mono-server2.exe /help

Next up, we have the Apache configuration file that is located in the Mono web-application’s subdirectory (the “mono-web/.htaccess” file):

# Specify default page names, including typical ASP.NET names

DirectoryIndex Default.aspx default.aspx Index.aspx index.aspx \

    Default.htm default.htm Default.html default.html \

    Index.htm index.htm Index.html index.html

# Define the FastCGI Mono launcher as an Apache handler and let

# it manage this web-application (its files and subdirectories)

SetHandler monoWrapper

Action monoWrapper /cgi-bin/mono-web-launcher.fcgi virtual

In addition to the default page names specified in the earlier .htaccess file, this file lists some typical ASP.NET filenames for default pages, such that the ASP.NET page called Default.aspx would be used when visiting the “http://example.com/mono-web/” URL. More importantly, it gives the Mono Backend full responsibility for all file content in this directory (and its subdirectories) by registering our customized launcher script as the Apache FastCGI handler for this web-app root folder. Using SetHandler (instead of AddHandler) has the added benefit that we don’t need to explicitly tell Apache which file extensions may be served (such as .aspx and .asmx) and which ones not (such as .cs and .dll), since the Mono Backend will also take care of that.

Lastly, as far as the website configuration is concerned, we provide a bare-basics web.config configuration file:

<configuration>

  <system.web>

    <!-- TODO: Enable custom errors once things work -->

    <customErrors mode="Off"/>

  </system.web>

</configuration>

Setting the customErrors mode-attribute to Off would help you to get your website going, since it would display detailed error messages when things go wrong. You don’t need any extra settings in the web.config configuration file just to run the example web service and pages, but expand on this as you develop your own ASP.NET website. Also, for security reasons, remember to define your own custom error-pages or at least disable the default remote-debugging error-pages before going live on the Internet.

Add Content to the Website

You can now add ASP.NET web pages, similar to Test.aspx and Default.aspx (with its associated Default.aspx.cs code file), web services and more to your Mono website. The example web service, called WebService.asmx, has been defined like this:

<%@ WebService Language="C#" Class="WebService" %>

using System;

using System.Web;

using System.Web.Services;

using System.Web.Services.Protocols;

[WebService(Namespace = "http://example.com/")]

[WebServiceBinding(ConformsTo = WsiProfiles.BasicProfile1_1)]

public class WebService  : System.Web.Services.WebService 

{

    [WebMethod]

    public string HelloWorld()

    {

        return "Hello World";

    }

    [WebMethod]

    public string GetUniqueIdentifier()

    {

        return Guid.NewGuid().ToString("N");

    }

}

Navigating to its Service Description (WSDL) page at “http://example.com/mono-web/WebService.asmx?page=wsdl” would produce something similar to the following:

Final Thoughts

The shared hosting server that I tested on used the “mod_fastcgi” Apache module as its FastCGI manager. However, even if the newer “mod_fcgid” Apache module would be used (which I think is the case for DreamHost Private Servers and possibly some DreamHost Shared Servers), the example configuration should still work. The only requirement is that the Apache server knows that is must execute *.fcgi files using its FastCGI module, and the Apache server seems to know this already (no “AddHandler fastcgi-script .fcgi” or “Options +ExecCGI” statements were needed in any .htaccess file). Perhaps just make sure that FastCGI (the recommended PHP mode) is turned on for your website in the DreamHost panel (under Manage Domains). Also, for future reference, the test server had the following software pre-installed: pkg-config 0.21 (not the latest, but it worked) and gcc 4.1.2 20061115 for Linux 2.6.29, Debian 4.1.1-21.

I suspect that one may still need to tweak the example .htaccess files to improve security. For one thing, it is perhaps not a good idea to be able to execute the FastCGI launcher by itself directly through an exposed URL (such as “http://example.com/cgi-bin/mono-web-launcher.fcgi”). At the very least one might want to include some random alpha-numeric characters in the launcher filename in an attempt to make it a bit more secure (if that would make much of a difference).

It is great to be able to run Mono on a shared server after having gone through all the trouble of setting it up yourself, but it would be much nicer if DreamHost could also provide a default pre-compiled and installed version of Mono FastCGI, just like they do for PHP FastCGI. Anyway, having Mono makes the development of web applications and web services much nicer than with PHP, in my opinion, and you get to use .NET-based technologies, such as C#, on Unix-based machines. Now that’s what I call... Cool!