Developing for MindTouch Vista/Win7 style
I had the once-in-a-three year opportunity recently to setup a fresh development environment here at MindTouch. Unfortunately this opportunity over-extended its welcome as I started running into various quirks which made the process more painful than it probably should have been. I’ll vent calmly explain these issues here so should you ever need to debug or build on MindTouch / Dream under Vista or Win 7 it’ll be smooth sailing.
So how does this apply to me?
There are several reasons why you may want to setup an MindTouch API dev environment.
- You’d like to extend your MindTouch installation by writing a C# extension or authentication provider or by modifying an existing one
- You’d like to write your own HTTP based service (independently of MindTouch) using the Dream framework
- You’d like to fix a MindTouch API bug and submit a patch so it can maybe get included in the next release
- You’re an API developer employed by MindTouch
Note that there are many ways to customize and extend the functionality of your install without ever needing to do this. You can customize the look and feel by modifying the skin, write custom DekiScripts within pages and add new DekiScript XML functions to build mashups and generate reports, build PHP hooks to extend the UI functionality, and discover already working extensions and scripts in the app catalog.
The setup
You’ll need to have a working UI and MySql database running in order to do effective API development including extensions, auth services, etc. The quickest way to set that up is to download a VM (or perhaps make a snapshot of your live environment if it’s a VM). If you need the UI code to be the bleeding edge freshest you can follow this guide to switch a VM to trunk but this probably isn’t necessary for you (no need to update the Mono C# API bits there though). Note that you’ll want to have a consistent codebase on the UI side as well as the API so be sure you’re running either the same release (or trunk) on both sides.
This guide by crb will get you the API code and get you to a point where you can point your browser to the UI and it will access the MindTouch API you’ve installed on your Windows box allowing you to see the changes you may be making.
Well that was easy.. So whats the problem?
URI Reservation aka ‘Why does Dream/MindTouch API only start with Admin rights?’
As part of the hypersensitive brute force approach to security taken by Vista the concept of URI reservation was introduced for what I’m guessing is an attempt to add a hoop for malware to jump through before listening on a socket that speaks HTTP. The Windows core http.sys library restricts the root namespace (i.e. ‘/’) of HTTP URI’s to require administrator access or explicit rights. Lots has been written about this but you’ll never know about it until you run into an issue. In Dream’s case it’s an Access Denied error when starting up as a non-admin. This means that if you’re going to be starting Dream from Visual Studio then VS itself has to run as Admin. This causes some annoying problems like not being able to drag in or out of the window from explorer as well as potentially serious security issues you may become victim of by running code as admin.
The ‘proper’ way to fix it is to add a URL reservation for Dream. Download the HTTPNamespaceManger tool described here, unzip it, and run it as admin. Click Add and type the URL “http://{yourip}:8081/” where {yourip} is an IP that your UI is able to access as well (so not localhost). Hit Ok. Click Add and type the username you generally use when running VS and click Ok. Click Ok again and quit the tool. Modify the mindtouch.host.exe command line startup arguments by appending “ip {yourip}:8081″ with {yourip} substituted by the ip you entered above. Start the project again from within VS and hopefully the error is gone.
Using the ip cmd line argument for Dream tells it what IP to bind to rather than it trying to bind to all of them which is sure to fail unless a reservation exists for each. Dream released with Noatak will have a change to ensure that it doesn’t exit when it couldn’t bind to one of the IPs.
Changes to 64-bit applications are not allowed!?
So you’ve solved that problem and you think you’ve conquered all that MS has thrown at you’re about to make a code change in an active debug session and this error pops up.
It turns out that since you’ve installed a 64bit OS, you can’t actually do any live debugging on a .net process unless it’s explicitly compiled as 32bit. Only the startup assembly (in this case mindtouch.host.exe) needs to be explicitly set to 32bit mode via its project properties (build -> platform target -> x86). We’re considering either shipping with an additional mindtouch.host.x86.exe compiled for 32bit only or switching our default build of mindtouch.host.exe to 32bit. Please comment here or on the forum if you have any strong opinions on one of these approaches.
Hope this guide helps someone. Big thanks to crb for putting together some of the core documentation for doing this! As always, feel free to find us at irc.freenode.net #mindtouch or post on the forums if you have questions.
You’re welcome, as always, but I really only just tidied up the guide. Looks like Guerric and you lot all actually wrote it!
(And even if I get any credit, I was setting up the environment so MaxM could talk me through building an OpenID service, so the credit was all his anyway. :)
November 19th, 2009 at 12:52 amHallo! Netter Artikel, ich habe mir mal deinen Blog gebookmarkt.
January 8th, 2010 at 8:49 am