Documentation

Cookbook: Setting up ASP.NET

To run ASP.NET applications with Cherokee, you will need to install Mono. The Mono Project is a UNIX version of the Microsoft .NET development platform aimed at enabling UNIX developers to build and deploy cross-platform .NET Applications.

You will specifically need to run the mono-fastcgi-server, since that is the backend needed to set up Cherokee with the FastCGI handler to parse and compile aspx code.

You have several options available to obtain this. If you are lucky enough, it will already be available in your favorite platform.

On Debian Lenny and Sid, and on Ubuntu 8.10+ (Intrepid and Jaunty) you can simply leave to APT the trouble of setting up the dependencies by typing:

# apt-get install mono-fastcgi-server2

The official supported packages can be found at the download site. If your flavor is not there, for Linux you can either:

  • Download the binary installer, which is the release 1.9.1 at the time of writing,

  • Download and compile the sources, available at the sources page. The fastcgi-server is provided by the XSP package.

You can find all sorts of information about the configuration of Mono at the Mono Project web site.

Once you have a FastCGI Mono backend available, we can proceed with the recipe.

Since a Mono Wizard is shipped with Cherokee, the configuration is as simple as clicking on the Wizard, located under the Languages category, and filling up a few required fields. Your application should be up and running. The rest of this document simply details the the recipe that is emulated by the Wizard. If you have any trouble with it, these steps could provide some insight on the reason of the failure to function properly.

Preparations
  1. Define an information source that spawns the fastcgi-mono-server. In our example we will be binding it to the local interface, port 8080, with our application located in /var/www, which is our document root. It will be mapped to / by the FastCGI Mono Server. To do this, we will create a source called mono, and we will set up the interpreter as:

    fastcgi-mono-server2 --socket=tcp:8080 --address=127.0.0.1 --applications=/:/var/www

    Of course you could also define the parameters through environment variables, and simply launch the interpreter as:

    fastcgi-mono-server2

    Lets assume we wanted to do so and also wished to use it through a Unix socket instead of through a host:port combination. You would have to define at least the following variables:

    MONO_FCGI_APPLICATIONS=/:/var/www
    MONO_FCGI_SOCKET=unix
    MONO_FCGI_FILENAME=/tmp/cherokee-mono.socket

    Make sure to set up a relatively high spawning timeout, because it can take its time and you don’t want Cherokee giving up before the process is spawned. A value of 30 seconds should suffice. Obviously this value is way too high to serve contents when the FastCGI Mono backend has not been spawned. It is only meant to be used a security measure. Spawning the process before putting the server into production is highly recommended.

  2. Map your information source to a rule that handles your Mono application. This can be done by setting up the rule for extensions or paths.

    • The first alternative is easily achievable by passing the 11 standard extensions to the FastCGI Mono Server, defining a rule that uses the information source we just mentioned and applies to the extensions: aspx, asmx, ashx, asax, ascx, soap, rem, axd, cs, config, dll. However, this is not the option recommended by the Mono Project since some undesired side effects are obtained, such as exposed files and missing features.

    • The second alternative overcomes this by sending all requests directly to the FastCGI Mono Server, but it comes at the cost of a performance decrease. It is the recommended option.

So, lets get started. The recipe will configure the FastCGI handler using paths, deleting all but the Default rule from our Cherokee configuration.

Steps
  1. First, access your virtual server configuration and go to the Basics tab. Add index.aspx,default.aspx to the list of Directory Indexes.

  2. Then, delete every erasable rule. The only remaining one should be the Default one.

  3. Edit the rule, go to the Handler tab and select the FastCGI handler. Assign it the mono information source. As always, you can set up as many hosts as desired and Cherokee will balance the load among them. If you want to take the alternative path of configuring Mono through extensions instead of paths, simply define a rule that applies to the 11 extensions mentioned above. The handler configuration is completely identical. Either way, make sure the Check file option of the handler is enabled. This is very important. If it is not, FastCGI will not work and you will receive an 500 Internal Server Error.

media/images/cookbook_mono_handler.png
FastCGI handler

And that is all. Once you upload your ASP.NET application to /var/www and launch Cherokee, you should be able to access your application by pointing your web browser to, lets say http://example.net/.

For this recipe, the package asp.net2-examples (provided by Debian and Ubuntu thanks to some APT magic) was used. If you were to copy the examples to /var/www as final step of this tutorial, you should see that Mono is working.

media/images/cookbook_mono_demo.png
Demo in action

When the package is installed, the examples will be placed in /usr/share/asp.net2-demos. Copy those to /var/www and you are ready to make the test.

Alternatively you can avoid copying any files and simply spawn the FastCGI Mono Server with the real path of the examples, like this:

fastcgi-mono-server2 --socket=tcp:8080 --address=127.0.0.1 --applications=/:/usr/share/asp.net2-demos

In case you can’t find the mentioned examples, you could always copy the following program to /var/www/index.aspx just to make sure your Mono setup is working.

<%@ Page Language="C#" Debug="true" %>
<html>
   <body>
       <h1>Hello World!!!</h1>
       <%
          // This block will execute in the Render_Control method
          Response.Write("Check out the family tree: <br> <br>");
          Response.Write(this.GetType().ToString());
          Response.Write(" which derives from: <br> ");
          Response.Write(this.GetType().BaseType.ToString());
          Response.Write(" which derives from: <br> ");
          Response.Write(this.GetType().BaseType.BaseType.ToString());
          Response.Write(" which derives from: <br> ");
          Response.Write(
            this.GetType().BaseType.BaseType.BaseType.ToString());
          Response.Write(" which derives from: <br> ");
          Response.Write(
            this.GetType().BaseType.BaseType.BaseType.BaseType.ToString());
       %>
   </body>
</html>