Setup an API development environment

Step 1: Get the source

You can either get the latest and greatest code from SVN or you can use the code from any release.

• If grabbing from SVN, check out https://svn.mindtouch.com/source/public/dekiwiki/trunk to C:\mindtouch\public\dekiwiki\trunk
  • Note, the above URL is the private MindTouch repository. You can also check out the source from the anonymous SourceForge.net SVN repository at the following URL:  https://dekiwiki.svn.sourceforge.net/svnroot/dekiwiki/public/dekiwiki/trunk/
• If using a release tarball, uncompress it and you will have the equivalent of the trunk directory above.

Step 2: Get the MindTouch API configuration

• Take the mindtouch.deki.startup.xml file from your VM (normally found in /etc/dekiwiki/), or the example file at http://developer.mindtouch.com/Deki/Configuration. Put it in the folder C:\mindtouch\public\dekiwiki\trunk\src\bin.
• Change the mindtouch.deki.startup.xml file to reflect your database no longer being at 'localhost':
  <db-server>ip.add.re.ss</db-server>
• Modify the imagemagick lines to point to these files: 
  <imagemagick-convert-path>C:\MindTouch\public\dekiwiki\trunk\src\tools\mindtouch.dekihost.setup\convert.exe</imagemagick-convert-path>
  <imagemagick-identify-path>C:\MindTouch\public\dekiwiki\trunk\src\tools\mindtouch.dekihost.setup\identify.exe</imagemagick-identify-path>
• Set the deki-path:
  <deki-path>C:\MindTouch\public\dekiwiki\trunk\web</deki-path>

Step 3: Visual Studio Configuration

• Open the MindTouchDeki.sln with Visual Studio.
• Do a build, to generate mindtouch.host.exe, which we will use below.
• Right click on the mindtouch.deki project.
• Click Properties.
• Open the "Debug" tab.
• Check "Start External Program" and point it to mindtouch.host.exe, which should now exist in C:\MindTouch\public\dekiwiki\trunk\src\bin\.
• Find the API key from the mindtouch.deki.startup.xml file.
  
• Using that API key, set the "Command line arguments" to:
  apikey API_KEY_GOES_HERE script mindtouch.deki.startup.xml path-prefix @api http-port 8081
• Set the "Working Directory" to: C:\MindTouch\public\dekiwiki\trunk\src\bin\

Step 4: Redirect API requests to your Windows host

• SSH (or use the VM console) into the VM with root access and edit: /etc/apache2/sites-available/deki (you should use vi because it's the best, but if you're new just use pico or nano)
• Find this line:
  

  ProxyPass /@api http://localhost:8081 retry=1
  ProxyPassReverse /@api http://localhost:8081

  Modify it so that it points to your API machine, and not the VM. The best way to do this is to make sure that your VM is running in NAT mode and _not_ Bridged mode. Then, find out what the VM adapter's IP address is on your local machine and fill that in. The new lines might look something like this:

  ProxyPass /@api http://192.168.47.1:8081 retry=1
  ProxyPassReverse /@api http://192.168.47.1:8081

  (If you want to avoid editing this file in the future due to IP changes, just create a host entry in /etc/hosts and use the host name instead)
• Restart apache, and youre done! 
  /etc/init.d/apache2 restart
• Now, edit your LocalSettings.php file in your MindTouch install directory (/var/www/deikiwiki) and add this line:

  $wgDreamServer = "http://192.168.47.1:8081"

Step 5: (Vista/Win7 only) Make a URI reservation to allow HTTPListener to work as a non-admin user

As part of the hyper-sensitive 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 (e.g. not localhost). Hit OK. Click Add, and type the username you generally use when running VS. Click OK, then 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.

Final thoughts

You now have the PHP side and MySQL database running off of the VM while the API is run through Visual Studio. Run the project and start working!