How to set up Orchard CMS 1.7.3 on Mono 3.8.0

Comprehensive guide how to step-by-step run Orchard on Mono (Updated: February 2015)

Officially, Orchard CMS does not support Mono. There are no promises and no known plans to make it compatible. But being an Open Source project, it encourages developers worldwide to give it a try.

Challenge

On December 2014 I was given an assignment to set up a running Orchard CMS configuration on a Linux machine. It was intended to run an updated version of our company site – currently it available at www.softelegance.com and uses Orchard CMS 1.7.3 and Mono 3.8.0. As other company’s systems and services were already running on Linux (and some already using the Mono platform), the decision was to reuse the same system.

Thus the prerequisites were:

• OpenSUSE Linux 12.3
• Mono 3.8.0
• Apache 2.2.22

To complicate things more, I was just superficially familiar with Linux OS – enough to remotely login, adjust a line in particular service config and restart it, but never installed and configured anything from zero or work on a Linux desktop on daily basis. On the other hand, I have deep experience in the .NET development on Windows, that should help.

Resources

Fortunately, the community has made a great work already by investigating and addressing the Orchard CMS issues on Mono platform. I had just to read the articles, forum discussions and examples:

• Running Orchard on Mono – outdated and just partially applicable instructions, but a good starting point;
• Orchard now works on Mono – a long forum discussion with a lot of excessive and partially obsolete information, but contains answers and hints nearly to all issues;
• Orchard On Mono – a working Orchard site running on Mono, that contains (unfortunately, incomplete) scripts, hints and instructions on running Orchard on Mono;
• zamphion/orchard-mono – the files (patches, setup) to patch Orchard CMS for Mono (referred from the prior site).

In addition, searching for any newbie questions on Linux configuration, packages installation, compiling and configuration usually brought quick results. Nevertheless, custom and sometimes non-obvious tweaking still were required.

Step-by-step

Packages Installation

The following packages are needed: mono-complete, monodevelop, apache2-mod_mono. They can be simply installed from the main repository using Yast. In addition, a MySQL server is needed.

Modifying Mono

There is one known incompatibility in the Mono runtime, not fixed in Mono 3.8.0 yet, that affects Orchard: the Server.MapPath method does not recognize ‘~’ character in the paths, thus breaking the AutoFac Inversion of Control container on which Orchard heavily depends.

Thus we need to download the Mono sources tarball of respective version, apply following change to it and build:

mcs/class/System.Web/System.Web.Hosting/HostingEnvironment.cs

In principle, it is possible to configure a parallel Mono environment for the patched version. As I have not managed to make it work quickly and I did not needed the original package, I’ve simply replaced the System.Web.dll file in the /usr/lib/mono/gac and /usr/lib/mono/4.5 directories with the patched version. In addition, it’s require to:

• Resolve the “Access denied” error to the path “/etc/mono/registry” – create the directory and chmod it as needed;
• Copy the mod-mono-server4.exe, xsp.exe and other .exe files from /usr/lib/mono/4.0 to /usr/lib/mono/4.5, if there are no such files in /4.5 yet;
• Copy or adjust the /usr/bin/mod-mono-server4 script to use the /usr/lib/mono/4.5/mod-mono-server4.exe.

Building Orchard

The latest Orchard version, 1.8.x, is entirely incompatible with current Mono version, as it uses the .NET 4.5 System.Web.Security.MembershipPasswordAttribute that is not implemented in Mono yet. Thus, download the last .NET 4.0 Orchard version (1.7.3) and unpack it to some directory (/usr/local/orchard, for example).

Extract patches to orchard/src/MonoizeOrchard/Orchard.Mono.Patches. Review and execute them one by one.

Download WIP scripts, review them one by one, put into orchard/src/, execute.

One more change: the default Orchard.FileSystems.Media.ConfigurationMimeTypeProvider class relies on the IIS MIME types API that is not available in Mono. Download some file extensions to MIME types mapping list, for example this one, and rewrite src/Orchard/FileSystems/Media/ConfigurationMimeTypeProvider.cs to use that static list.

Start monodevelop, open src/Orchard.sln. Build All (F8). Fix errors by commenting out missing namespaces and properties and adding missing references such as System.Data, until the whole solution builds without errors.

Note: you can build it from command line using mdtool build Orchard.sln command.

After building and before first site access, delete the src/Orchard.Web/bin/NHibernate.SqlAzure.dll file – it would prevent the site from launching under Mono.

Setup Orchard in Apache

Note: it is also possible to run ASP.NET sites in nginx, but I have not managed to get decent performance in that case, so I have used the apache2 configuration.

Basically, you need to setup the vhost configuration as in the example below:

(The /ua sub-path here is configured to serve plain html and other files that bypass the ASP.NET handler).

Setup MySQL

In the installed MySQL server, create an empty database and the user with GRANT ALL permissions to it. For example, database orchard and user ‘orchard’@’localhost’.

When first accessed, Orchard CMS asks for the database configuration. Specify the MySQL connection string

Data Source=localhost;Database=orchard;User Id=orchard;Password=….

If everything goes well, Orchard CMS starts and automatically populates the database objects.

Deploying Orchard Modules and Themes

Orchard CMS relies on the NuGet packages for deploying the modules. Under Windows it is possible to automatically download Modules and Themes from the online Gallery and instantly apply them to Orchard without restarting. With Mono the NuGet installation is not working, so the Modules and Themes must be installed manually:

• Download the .nupkg file from the Orchard Gallery and unpack it (it is just a renamed .zip file);
• Copy the Content\Modules and Content\Themes folder contents into Orchard.Web\Modules and Orchard.Web\Themes, respectively;
• Delete or rename Web.config files from those folders;
• Edit the .csproj file – most Modules and Themes contain references to the Orchard.Core.dll, Orchard.Web.dll and sometimes other module dlls as ProjectReference items. Change them to respective file References (..\..\bin\Orchard.Core.dll etc.);
• Compile the module (mdtool build ….csproj);
• Fix the compatibility bugs, if any (many latest module versions are using the latest Orchard 1.8.x features already, so they have to be downgraded to 1.7.3);
• Copy compiled dlls from the module’s bin/ folder to src\Orchard.Web\App_Data\Dependencies directory (copy the newly created dlls only, do not overwrite existing ones);
• Restart Apache (service apache2 restart from the command line).

The Module/Theme should now be available in the /Admin Web UI for enabling and configuration.

Conclusion

Running Orchard CMS under Mono/Linux is quite possible but requires dealing with a lot of annoying compatibility issues. Unless you have strong reasons to use Linux instead of officially supported Windows environment, going through the described process is not recommended.

The result

Working instance of Orchard on Mono available: