Josh Nock

Code Craftsman

Sinatra (Ruby) on IIS 7.5+ with HttpPlatformHandler

Here's an instruction guide (or should I say a documentation of my experience) to get a ruby-based web app running on a Windows server under Internet Information Services (IIS) version 7.5 and higher.
Specifically, "How to install Dashing ​​on Windows Server with IIS 7.5+."

What's Dashing? you might ask. Well here's a quote from their website.

"Dashing is a Sinatra based framework that lets you build beautiful dashboards."

Now I know you're probably thinking Sinatra/Ruby on Windows under IIS? 

what?

Ouch, but why?


Background:

At work, we wanted to have a live dashboard with a data feed from our build server and our project management server (rallydev). We set up a Raspberry Pi with ubuntu-mate; we installed dashing with ease, and we pulled down a git repository with our customized work. We used RubyMine to develop locally on our windows laptop and committed the work to a remote repository, which the raspberry pi was able to access. This is the result:

DEvOps_Dashboard_current.png
It's current location overlooking the cube farm:

DEvOps_Dashboard_currentLocation.jpg

Goal:

Have the dashboard accessible from each developer's computer without the need to physically walk by Big Brother. Have the site under IIS so that when the server crashes or reboots IIS restarts the site automatically, eliminating the need to log into the command prompt on the server and restart the dashing app.

Requisites:

Only windows servers were available for this installation, so I chose to install it on the server we were already choosing to use for internal tools that we have set up; such as a Nuget Server.


Steps:

  1. go to RubyInstaller.org > Downloads
  2. Install version 2.2.x, which is more stable than the newer 2.3.x

    this should add Ruby's bin to the PATH environment variable, to check, open a command prompt and type the following
    C:\Users\you>ruby -v

    it should respond with something like this:
    C:\Users\you>ruby -v
    ruby 2.2.4p230 (2015-12-16 revision 53155) [x64-mingw32]

  3. Install Ruby Installer Dev kit (on the same page as the regular ruby installer) this is needed for Dashing.
  4. The devkit runs an extractor, which will ask you for the permanent location for the devkit, I chose to install it under the ruby folder, which on the server looked like c:\Ruby22-x64\devkit
  5. Open a command prompt and CD to the devkit directory and run the following commands:
    C:\Ruby22-x64\devkit>ruby dk.rb init

    This creates a config.yml file which lists the location of your ruby installation. It never seems to find the location for me; maybe it's my choice of devkit location. open the config.yml file located in the devkit directory and make sure last line is the location of your ruby install. For my instance it looks like this

    RubyInstaller_DevKit.png

    next run the following command from the same command prompt
    C:\Ruby22-x64\devkit>ruby dk.rb install
  6. Install Dashing - you'll need to install the Dashing ruby gem so that you can create your starter instance of the site.
    1. With the command prompt still open type the following command:
      C:\Ruby22-x64\devkit>gem install dashing

      It doesn't matter where you run this command within the command prompt as 'gem' is a ruby command that is now accessible anywhere, and the 'gem' that is installed is installed globally under the Ruby installation directory.

    2. Create directory for your new dashboard: I use C:\websites\
    3. Here is a blog post about best practices for not using the default c:\inetpub\ directory.
    4. don't forget to give the user group "IIS_IUSRS", the "read & execute", "List folder contents", and "Read" persmissions on your new directory.
    5. Open command prompt and CD to this new directory.
    6. Run the following dashing command
      C:\websites>dashing new sweet_dashboard_project
    7. CD into this new directory
    8. Run the following ruby gem command:
      C:\websites\sweet_dashboard_project>bundle
    9. Now lets tests that the website works outside of IIS, run the following command:
      C:\websites\sweet_dashboard_project>dashing start
    10. Open a browser (this site wont work in IE) and navigate to localhost:3030
  7. Install HttpPlatformHandler v1.2 ​on IIS using WebPlatform Installer
    1. Here is a great blog post by Scott Hanselman about this IIS plugin - Announcing: Running Ruby on Rails on IIS8 (or anything else, really) with the new HttpPlatformHandler - Scott Hanselman
    2. And here is a video presentation on Channel 9 by Scott Hanselman
  8. Create the web.config file needed to run the website
    1. open the directory you created for the website e.g. C:\websites\sweet_dashboard_project\
    2. create a new file web.config
    3. edit the file to have the following:

      <?xml version="1.0" encoding="UTF-8"?>
      <configuration> <system.webServer> <handlers accessPolicy="Read, Script"> <add name="httpplatformhandler" path="*" verb="*" modules="httpPlatformHandler" resourceType="Unspecified" requireAccess="Script" /> </handlers> <httpPlatform stdoutLogEnabled="true" stdoutLogFile="c:\logs\dashing.log" startupTimeLimit="20" processPath="C:\Ruby22-x64\bin\ruby.exe" arguments="&quot;C:/Ruby22-x64/bin/dashing &quot; start -p %HTTP_PLATFORM_PORT% -e production"> <environmentVariables> <environmentVariable name="HOME" value="C:\Users\<<%%YOURUSERNAME%%>>\" /> <environmentVariable name="EXECJS_RUNTIME" value="Node" /> </environmentVariables> </httpPlatform> </system.webServer> </configuration>

    4. In the config file please change the environment variable for HOME to your user directory (the user you installed ruby with) as ruby will need access to the .gem folder located there. On the C:\users\%yourusername%\.gem folder I also granted IIS_IUSRs user group, the same (execute, list and read) permissions as in step six to this folder.
      Also, on the httpPlatform element I have the logging enabled for initial debugging, and I'm outputting the logs to a simple c:\logs\ location that the IIS_IUSRS has read write access to.

    5. SETTINGS: To explain the settings in <httpPlatform></httpPlatform>, processPath points to the underlying process that will run your website, in this case it is the ruby executable that will run dashing, which is based on the Sinatra framework. You can point this at any executable that will handle http requests. The arguments setting is obviously intended to pass any argument the executable will need when IIS starts the process. There are also stdoutLogEnabled and stdoutLogFile setting which should be self explanatory, and there are more variables shown above and even more available, so please check the HttpPlatformHandler documentation online. Environment variables set in this section will be accessible to the running process, so you can provide them here as opposed to actually adding them to the servers environment variables which you may not have access to with permissions.

  9. Install NodeJS
    1. Go to Node.js website, download and run the installer.

      The reason for installing NodeJS is to provide and alternate coffeescript compiler for ExecJS, I ran into encoding issues using the default cscript. and while using NodeJS is not ideal for this stack, the server I'm using is more than powerful enough, and it works flawlessly.

    2. After installing Node, you'll need to restart the server.
  10. Configure IIS for the new site.
    1. open Internet Information Services manager
    2. right-click on the server name and click add website.
      add_website.png
    3. type in the name you want to give the website for Site Name
    4. Select the directory we setup as the physical path, this directory should have our web.config we created, sitting in it.
    5. If you have other websites under the default website then you'll want to pick another port name or add a host name to this site for IIS to differentiate the incoming http requests.
    6. I also set the application pool to No managed framework and Classic, as this site will not be attempting to access any .net framework components.
      final_iis.png
  11. You're finished!! Navigate to the url for your new site and you should see the sample. For more customizations, you'll have to read up on the Dashing documentation, possibly install RubyMine (which I recommend for easier development)
    sample.png

Ta Da!

blog comments powered by Disqus