Posterous theme by Cory Watilo

Installing Spree on Windows 2003 Server with IIS 6, Thin, Rails 3.0, Ruby 1.9.2 and IIRF

[Edit 12/2011] Added how to install the rmagick gem on Windows.  Forgot that the first time, I had to install the development headers for ImageMagick and learn the command to install rmagick on its own.

Note: The template on my blog currently cuts off long quoted lines, so you can't see all of the commands here. You can still copy and paste correctly. I'm seeing about switching templates to work better. Sorry.

The Spree Commerce project is one of the best open source Ruby on Rails commerce web applications available. That's rather easy to say, since there aren't really a lot of such projects, but Spree is rather good. Built on straightforward core functionality and leveraging Rails' foundation for extensibility, Spree has a small but healthy community and enjoys active development that keeps up with new Rails developments. If you're looking for a Rails 3 commerce site, Spree should definitely be a contender.

This article is certainly not meant to be a review of Spree though. Rather this is a log of my experience getting Spree set up on Windows. Since Windows still at this point seems to be somewhat of a second-class citizen for Ruby and Rails, there were a number of hoops to jump through, although it wasn't a terrible experience by any means.

By way of giving credit to the Ruby community for recognition of this fact, I will plug the RailsInstaller project, which got me up the curve of installing Rails on Windows. While I ended up uninstalling Railsinstaller and installing all of the various components myself later (so that I could mix and match them, which is more difficult with RailsInstaller), I still owe RI the debt of identifying many of the pieces for me and proving that it would all work before I decided to invest more time into it.

Things you need

I'm using the versions listed here. Since I haven't completely tested this, I can't guaran.

During the process, you will also be installing:

Nice to have

It also helps to have a good text editor like Sublime Text 2 (commercial) or Notepad++ (free open source).

Steps

For all installs, if an option is not mentioned, that means go with the default.

I use ZipInstaller to install some of these, so it is first. You don't have to use ZipInstaller, but it makes managing apps and uninstalling nicer.

Install ZipInstaller

Using ZipInstaller 1.21

  1. Download zipinst.zip (near bottom of page, with help in zip)
  2. Double-click zipinst.zip
  3. Double-click zipinst.exe
  4. Select zipinst.zip, click Continue
  5. Select Install for All Users and Remember Settings
  6. Click OK
  7. Run ZipInstaller from Start Menu
  8. Click Options
  9. Select Add ZipInstaller to context menu
  10. Click OK
  11. Cancel out of ZipInstaller

Now all zip files have a context menu entry to run ZipInstaller on them.

Install Ruby

Using RubyInstaller 1.9.2

Note: as of this time, the spree developers don't claim 1.9.2 compatibility, so you may be better off with 1.8.7, which is officially supported.

  1. Download rubyinstaller-1.9.2-p180.exe
  2. Run the installer
  3. Check the box to add the Ruby executables to your path

Update RubyGems and rake

After the install is complete, open a command prompt and issue the commands:

gem update --system
gem install rake

which updated my system to RubyGems 1.8.5 and rake 0.9.2. The rake update is required, but the gems update is just good practice.

If you want you can add --no-ri --no-rdoc to any gem install command to skip installing the developer documentation

Install DevKit

Using DevKit 4.5.1

If you don't want to use ZipInstaller, just unzip the files to C:\DevKit.

  1. Download DevKit-tdm-32-4.5.1-20101214-1400-sfx.exe
  2. Create DevKit subdirectory and extract to there
  3. Zip all the files in the directory (not the directory itself) and use ZipInstaller to install to C:\DevKit (say no when ZipInstaller says it's detected an installer inside)
  4. Open a command prompt and go to C:\DevKit
  5. Run ruby dk.rb init
  6. Run ruby dk.rb install

Note that the download site has instructions for installing DevKit for more than one Ruby install, if you want to go that route.

Install Git

Using Git 1.7.4

  1. Download Git-1.7.4-preview20110204.exe
  2. Run the installer
  3. No Explorer integration for me
  4. Select Run Git from the Windows Command Prompt
  5. [Edit] Set the HOME environment variable to point to your [username] directory (or and Settings[username]) by going to Start Menu > Computer, right-click and select Properties, then Advanced and under User variables, make a new home variable.

Note that Git on Windows is sensitive to the location, since that location is assumed by other tools in the git toolbox. If you don't make it in that location, you're liable to run into a mismatch and be scratching your head as to why it's failing to authenticate.

Install Image Magick

Using Image Magick 6.7.0

  1. Download ImageMagick-6.7.0-8-Q16-windows-dll.exe
  2. Run the installer
  3. When the options page comes up, select to install the development headers

Install SQLite

Using SQLite 3.7.6.3

  1. Download sqlite-shell-win32-x86-3070603.zip and sqlite-dll-win32-x86-3070603.zip
  2. Extract to C:\Ruby192\bin

Optional: Install SQLite2009 Pro Enterprise Manager

Using SQLite2009 Pro Enterprise Manager 2011.05.20

This is the most complete and easiest to use SQLite GUI, although I also like SQLite Administrator. Enterprise Manager has a definite edge in presentation though.

Note that in order to see your SQLite database files in the open file dialog, you have to rename their extension to .db3. You could do this for your development and test databases by changing the filenames and updating your database.yml file, but I prefer to copy the files off to another location and rename them there.

  1. Download SQLite2009Pro-v3.7.6.3.zip
  2. Unzip and run the installer

Install MySQL

Using MySQL 5.5.13

If you already have MySQL installed on your server but it does not have the InnoDB storage engine configured, you can run the Instance Configuration Wizard to turn on the engine. Use the settings below. You do not have to do anything to your existing schemas in the db. Any new schemas will have InnoDB available, which is what you want.

  1. Download mysql-5.5.13-win32.msi
  2. Run the installer
  3. Choose middle server size option (medium memory usage)
  4. Required: Choose default InnoDB storage engine

When the install is complete, copy \lib\libmysql.dll to C:\Ruby192\bin

Install MySQL Workbench

Using MySQL Workbench 5.2.34

  1. Download mysql-workbench-gpl-5.2.34.1-win32.msi
  2. Run the installer

Configure MySQL

When the install is complete, open MySQL Workbench, connect to the database and create a new schema called spree_production.

Install Rails 3.0

Using Rails 3.0.9

Note: working directory doesn't matter when installing gems, they will automatically go in your Ruby install directory.

  1. Open a command prompt
  2. Issue the command:

gem install rails -v 3.0.9

Note: the documentation part of the install failed with an error but it should still run.

Install mysql2

Using mysql2 0.2.8 gem

Still at the command prompt, issue the command:

gem install mysql2 -v 0.2.8 -- '--with-mysql-dir="C:\Program Files\MySQL\MySQL Server 5.5"'

There are more recent versions in the 0.2 line (currently 0.2.10), but some won't compile on Windows.

Install rmagick

Still at the command prompt, issue the command:

gem install rmagick -- '--with-opt-dir="C:\Program Files\ImageMagick-6.7.0-Q16"'

This one will take a while.

Install EventMachine

Issue the command:

gem install eventmachine --pre

Install Thin

Issue the command:

gem install thin

Install Spree

Using Spree master edge

Change directory to the parent directory of your future rails project Issue the command:

rails new spree -d mysql
  1. Now find the Gemfile in the root of your spree directory (for our purposes, let's call it C:)
  2. Open it in a text editor
  3. Before the line for gem 'mysql2', insert the line:

    gem 'sqlite3'

Change the line for mysql2 to specify the version:

gem 'mysql2', '0.2.8'

At the end of the file, add the line:

gem 'spree', :git => 'git://github.com/spree/spree.git'

I also use spree_flexi_variants, so I add:

gem 'spree_flexi_variants', :git => 'git://github.com/jsqu99/spree_flexi_variants'

Save the file.

At the command line, change to the spree directory and issue the command:

bundle install

I like using SQLite for development and test since I can copy the files easily to other environments. To do so, paste in these values, completely replacing the old ones:

development:  adapter: sqlite3  database: db/development.sqlite3  pool: 5  timeout: 5000# Warning: The database defined as "test" will be erased and# re-generated from your development database when you run "rake".# Do not set this db to the same as development or production.test:  adapter: sqlite3  database: db/test.sqlite3  pool: 5  timeout: 5000

Otherwise add the database login password to the existing environments. Don't forget to create the schemas in the db as well.

Also, add the password for the account to the production environment.

Note: It is customary to create a separate, more limited account than the root account, which you would use to connect to the MySQL database in a more secure fashion. I don't go into the details of how to do that here. These instructions are provided AS IS and I'm not liable for any issues that may arise from following them. You've been warned.

Issue the commands:

rake db:createrails g spree:siterake spree:installrake spree_sample:installrake spree_flexi_variants:installrake db:bootstrap

Test the installation by using the command:

thin start

then point your browser at http://localhost:3000/. You should see the default spree install.

This does the install for the development environment. You still need to initialize the production environment:

set RAILS_ENV=productionrake db:migraterake db:seedrake db:admin:create

Put the site under version control

git init

Replace the .gitignore file contents with:

.bundledb/*.sqlite3*log/*.log*.log/tmp/doc/*.swp*~.project.DS_Store

Run:

git add .git commit -m "Initial commit"

Install SRVSTART

Using SRVSTART 1.1

  1. Download srvstart_run.v110.zip
  2. Right-click and run ZipInstaller

Configure SRVSTART

In C:\Program Files\SRVSTART, create the file, srvstart.ini and add the lines:

[spree1]startup=c:\ruby192\bin\ruby.exe C:\ruby192\bin\thin -p 3001 startstartup_dir=e:\spreedebug=0debug_out=>e:\spree\log\thin.log

This will start spree in development mode on port 3001. To switch to production mode, add -e production before start on the startup line.

Note: You can only stop this service when the ruby interpreter it spawns is the direct child of srvstart (it kills the child). This precludes you from running thin.bat, or using bundle exec thin start to run thin. Perhaps you could use bundle exec if it called ruby to start thin, as above, but I didn't play with that.

Install Windows Service Commander

Using Windows Service Commander 1.0.6

  1. Download windows-service-commander-setup.exe
  2. Run the installer

Configure Windows Service Commander

  1. Run Windows Service Commander
  2. Select the Tools > Install new service... menu
  3. Click Next >
  4. For path to the service executable, enter:

c:\Program Files\srvstart\srvstart.exe svc spree1 -c "C:\Program Files\srvstart\srvstart.ini"

  1. Click Next >
  2. For Name, enter 'spreeThin1'
  3. For Display Name, enter 'spreeThin1'
  4. For Description, enter 'Spree commerce web app server'
  5. Click Next >
  6. Click Next > again
  7. For Startup, select Automatic
  8. For Error, select Normal (this is what Bitnami does)
  9. Click Next >
  10. Select Start the service immediately
  11. Click Finish

The service should start immediately. Check Process Manager to see your ruby executable. Test the server by going to http://localhost:3001/ with your web browser. You should see the default spree site.

The service can now be started and stopped with either Windows Service Commander or the regular Services Administrative Tool. Stopping the service means killing ruby outright, which is not very graceful, so be aware that on a high volume site you may kill spree in the middle of writing something important. This is why it's important to use a real database such as MySQL rather than SQLite on the back end in this configuration, which should keep you from borking your db entirely when you stop the service.

Create your website

In IIS manager, make a new website for spree. Point it to C:\spree\public.

If you are running multiple sites, you may need to add a host header for your site so you can listen to port 80 along with other web sites on IIS.

For SSL port, set 443.

Note: if you are running ASP.NET 4.0 or above, you will need to create a new application pool and assign the website to that application pool. Verify that the spree site is not using ASP.NET 4.0 (1.1 is fine) when you do so. This will prevent interference from ASP.NET 4.0's extensionless URL rewriting. See the following URL for a method of disabling extensionless URL rewriting entirely in ASP.NET 4.0 if you can't use another application pool:

http://www.asp.net/learn/whitepapers/aspnet4/breaking-changes#0.1__Toc256770153

Install IIRF

Using IIRF 2.1.1.25

The 2.1 latest stable gave an installation error for me, so I used the previous 2.1.1.25 version.

  1. Download Iirf2.1.msi
  2. Run the installer
  3. Choose the spree website you made in the last step (unless you need rewriting on all of your sites, which I don't recommend)

Configure IIRF

Create the file C:\spree\public\iirf.ini and add the lines:

StatusInquiry ONRewriteLogLevel 3RewriteLog ..\log\iirfRewriteCond %{REQUEST_FILENAME} -fRewriteRule ^.*$ - [L]RewriteCond %{HTTPS} onRewriteHeader X_FORWARDED_PROTO ^$ httpsProxyPass ^/(.*)$ http://[your hostname]:3001/$1ProxyPassReverse / http://[your hostname]/

Check the status of IIRF by visiting http://[your hostname]/iirfstatus

After you have a working spree installation, don't forget to ratchet the LogLevel down to 0 or 1.

Optional: Configure hosts file

If you need to use host headers but are not yet in DNS, you can use the hosts file to locally define the IP for your site.

Open C:\WINDOWS\system32\drivers\etc\hosts and append with a space the fully-qualified domain name of your site on the same line as localhost.

Optional: Install IIS 6 Resource Kit Tools

Using IIS 6 Resource Kit Tools 1.0

If you don't already have a certificate installed for your site, you'll need one for SSL access to the administrative portion of your site. The IIS 6 Resource Kit Tools can help you do this.

  1. Download iis6rkt.exe
  2. Run the installer

  3. In IIS Manager, right-click the spree website and click Properties
  4. Under the Web Site tab, click the Properties button next to the log format dropdown
  5. Note the digits after 'W3SVC' in the log file name, this is the site ID
  6. Close the IIS manager dialogs
  7. Go to Start > IIS Resources > SelfSSL > SelfSSL
  8. Run selfssl /T /N:CN=[your FQDN] /S:[your site id]
  9. Respond y

Note: This will overwrite any existing certificate for your site, so use care on a production server.

Notes on the Install

If you have difficulties with the site, the logs are all in C:\spree\log. Between the iirf log (make sure you are checking the latest dated 'live' one), the production log for spree and the thin log (stop and start of the spreeThin service), you should have a good picture of what's happening.

I suggest becoming familiar with the reference materials for some of the important pieces:

I used the next-to-latest release of IIRF because of installation errors but I didn't try working around it by, say, replacing the dll with the latest one after installing the old one. Not enough time and it didn't seem like there were relevant changes to the latest code.