Deploying to Mono - Install FreeBSD 9

From Visual WebGui Wiki

Overview

In this article we will discuss how to install a basic FreeBSD 9 Beta operating system, install Apache2, Mono and mod_mono and finally configure mod_mono so it will be able to run a basic Visual WebGui application in this environment. The article is a part of a series of articles describing how to use Mono in Linux/Unix environment to run Visual WebGui application. The main article is Deploying to Mono.

Installing FreeBSD 9 and Mono 2.10

For this test, a base FreeBSD 9 beta system was installed off of their installation ISO.

More information on various parts of the installation process can be found in the Other references section of this article.

Ports package distribution - full source compilations

FreeBSD uses a package distribution and installation system called ports. It differs from many of the other package distribution systems in that the ports do (usually) not contain the binaries for the packages you are installing, rather they contain a reference to the necessary source code and the installation process involves (auto) downloading of the source, configuring the options, compiling to binary form and installing the package. This may sound like a complicated process, but really it is not, as most of the process is completely automatic, with only the option selection that needs manual intervention.

By default, the ports repository of software packages, contains the version of each package that was most recent when the repository was created. This can in some cases be a quite old version of some packages and in our case, the default installed ports have a version of Mono that we know has been updated with better support for ASP.NET, especially ASP.NET 4.0. To get more recent versions of software packages, FreeBSD has a utility called portshaker, that can be used to get the most recent version of the source code for the package(s) you are installing. We will use portshaker in the instructions that follow, and the instructions will include the portshaker installation instructions, as well as other instructions.

In addition to initial installation of the required packages, we will install WebMin web management tool with is a great tool for server management, especially for novice users.

Please note that installing any port that depends on other ports, means those other ports will be downloaded and installed. For big packages, you may be prompted several times for configuration options, which will halt the compilatiion process until you respond to the option prompt. In some cases, default configuration is acceptible and for those cases, please see this article here on how to set autoresponse that will accept the defaults for all ports installed. Unless otherwise specifically noted, the default configuration of all installed ports was used for this test.

Update the operating system kernel with the most recent patches

freebsd-update fetch
freebsd-update install

Update the ports repository

The following commands will get your ports repository up to date, in case there have been any updates since the installation media (ISO) was created:

portsnap fetch extract
 
# or if extract has been run before
portsnap portsnap fetch update

Installing portshaker to update the ports repository

This will update your ports repository to the most recent version available of each software, which may be newer than supplied by the default ports repository. This is necessary to get Mono 2.10 installed on FreeBSD 9 beta, as there is an older version you get from the default repository.

cd /usr/ports/ports-mgmt/portshaker-config
make BATCH=yes install
 
portshaker

Installing the portmanager utility - for easy updates of installed ports

When an installed package gets updated in the ports repository, the installed package itself does not get updated. The portmanager is a handy tool for upgrading installed packages if their ports version is more recent than the installed version. To inststall this utility you use:

cd /usr/ports/ports-mgmt/portmanager
make install clean

After this package is installed, you can issue the following command to update all installed packages from the ports repository:

portmanager -u

As a sidenote, you can get a list of all installed packages with:

pkg_info

WebMin installed from ports repository

# Install it
cd /usr/ports/sysutils/webmin
make install clean
 
# Configure it
/usr/local/lib/webmin/setup.sh
 
# Start it
/usr/local/etc/rc.d/webmin/start

And finally, as usual, to invoke WebMin web management, use a browser to open http://yourserver/WebMin:10000

Apache2 installed from ports repository

To install Apache2 use:

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

To configure it to start at bootup, please view the references section, but to get it running right away use:

kldload accf_http
apachectl start

Mono installed from ports repository

cd /usr/ports/lang/mono
make install clean
 
cd /usr/ports/lang/mono-basic
make install clean
 
cd /usr/ports/devel/mono-addins
make install clean
 
cd /usr/ports/devel/mono-tools
make install clean

Mod-Mono install for Apache2 from ports repository

The above installation of Mono will install the Mono framework on your FreeBSD system. To be able to run you Visual WebGui or ASP.NET web applications within Apache2, the mod_mono Apache2 module needs to be installed. This module is a part of the FreeBSD ports repository, so you can simply issue the command:

cd /usr/ports/www/mod_mono
make install clean

Tools for locating the necessary files - locate

For those users that don't quite know their way around this operating system and do not know where exactly the necessary files are located, it may be good to learn how to use a very simple, but very handy command, the locate command. With very minor effort and preperation, you can use this command to locate (almost) any file on your server.

As an example, to locate the mod_mono_server2 on disk, you can simply issue the following command, which will give you a list of locations where this file/folder can be found:

locate mod-mono-server2

Before the locate command can be used, the system must update or build the database of filenames it uses for it's searches. For the purpose of updating this database with the most recent information, use:

/usr/libexec/locate.updatedb

This locate.updatedb command is on many/most system run every hour, but very recently after you have made some changes to the filesystem, you can run this command manually to make sure the locate database is up to date.

Apache2 and mod_mono configuration

The above installation procedure will install Apache2, Mono and mod_mono in it's default installation.

There will be a /usr/local/etc/apache22 folder created and on that folder, the following gets created as a part of the installation:

/usr/local/etc/apache22/httpd.conf - The main Apache configuration file
/usr/local/etc/apache22/Includes - A folder for additional configuration files. All files with a name that ends in ".conf" will be read alphabetically by the Apache2 configuration process (included from httpd.conf).
/usr/local/etc/apache22/Includes/mod_mono.conf - The default mod_mono configuration file.

Modifying the default httpd.conf Apache2 configuration file

For this test, Apache2 virtual hosting was configured, using multiple virtual hosts on same IP address and same port.

If needed, you should edit the httpd.conf file as suits your preferences. In this test, changes made to that file was to ensure the following was set in the configuration:

NameVirtualHost *:80
Listen 80
ServerName FreeVWG.mydomain.com

It should be noted here that for some applications you may need to adjust the default access rights on folders and/or files to support your specific application. Folders that will need to be writable may need to have "chmod 777" to allow everyone to write, or equal access rights adjustment for the owner of the process, to allow the web application to write on that folder.

Seperate folder for Visual WebGui applications

According to the default httpd.conf file, the default folder for the server is /usr/local/www/apache22/data.

For this test and for simplicity, a seperate folder was created on /usr/local/www/apache22/vwg, for storing Visual WebGui application.

Mod_mono config for Visual WebGui applications

Note that many of the mod_mono configuration settings used here, can be configured to apply globally, per VirtualHost, per folder and/or per application. MonoServerPath is a good example of such a setting and can easily be configured to support different .NET versions on a per application basis. Please refer to mod_mono and Apache2 documentation for more info.

To keep the default mod_mono.conf file unchanged, a new file was created on the /usr/local/etc/apache22/Includes folder. Remember from above, that default httpd.conf file loads all *.conf files from the Includes folder as a part of the config. To make sure our Visual WebGui configuration file is loaded last, after all other configuration has already been read (especially mod_mono.conf), you can name the file something like "x01_vwg-mod_mono.conf". The contents of the file used for this test are the following:

AddType application/x-asp-net .wgx
 
<VirtualHost *:80>
  ServerName FreeVWG.mydomain.com
  ServerAlias FreeVWG
  ServerAdmin web-admin@FreeVWG.mydomain.com
  DocumentRoot /usr/local/www/apache22/vwg
  MonoAutoApplication enabled
 
  MonoServerPath FreeVWG /usr/local/bin/mod-mono-server4
  MonoDebug FreeVWG true
  MonoSetEnv FreeVWG MONO_IOMAP=all
 
  AddMonoApplications FreeVWG "/:/usr/local/www/apache22/vwg"
  AddHandler mono .wgx
  SetHandler mono
 
 
  <Location "/">
    MonoSetServerAlias FreeVWG
    Allow from all
  </Location>
 
  <Directory /usr/local/www/apache22/vwg>
    Options Indexes FollowSymLinks
    AllowOverride None
    Order allow,deny
    Allow from all
  </Directory>
 
  <Location /mono>
    SetHandler mono-ctrl
    Order deny,allow
    Deny from all
    Allow from 127.0.0.1
  </Location>
</VirtualHost>

Special web.config concerns for Visual WebGui on FreeBSD

Visual WebGui on FreeBSD requiresthat you configure uiCulture within the globalization tag of your web.config. If the uiCulture setting is missing, your application will not work and your browser will show an empty form. Mono does support multiple cultures, so there is no preference for the uiCulture you should set, you just have to set it.

Typical globalization setting in your web.config might look like this:

<configuration>
    <globalization requestEncoding="utf-8" responseEncoding="utf-8"
                   culture="en-US"
                   uiCulture="en-US"
                   />
</configuration>

What is next

Now that you have installed and configured the base operating system and the required Apache2 and Mono components, you can now continue to the deployment part of the process. Before you do that, please make a note of the operating system specific locations of the files and folders that are most relevant for this process:

/usr/local/etc/apache22 - Folder that stores Apache2 configuration files
/usr/local/etc/apache22/httpd.conf - File which is the main Apache2 configuration file (which you will change)
/usr/local/etc/apache22/Includes - Folder for additional configuration files. All files with a name that ends in ".conf" will be read alphabetically by the Apache2 configuration process (included from httpd.conf).
/usr/local/etc/apache22/Includes/mod_mono.conf - File that contains the default mod_mono configuration, and is installed as a part of mod_mono installation.
/usr/local/etc/apache22/Includes/x01_vwg-mod_mono.conf - File that you created and contains the Visual WebGui specific configuration for mod_mono and Apache2.
/usr/local/www/apache22/vwg - Folder that you created and where you will deploy and run your Visual WebGui application from. The x01_vwg-mod_mono.conf references this folder.

At this point you are ready to learn more about the mod_mono configuration directives and how to deploy your Visual WebGui application. Please head over to the Mono directives - What do they mean section of the main article on deploying to Mono.

Other references