Serving up the Potion Store on Leopard Server

The Potion Store is a fantastic way for Cocoa developers to create their own web stores - after all, it's tailor made for us. Kudos to the Potion Factory for their efforts and for choosing to open source the entire project. You guys totally rock.

In the first post in this series, CodexFab and Cocoa Application Licensing, I discussed some possible licensing schemes for Cocoa apps; and in particular CocoaFob, a recently released project which makes it easy to build secure Potion Store licensing into any Cocoa app. My own derivative project, CodexFab, illustrates an example implementation of the code in CocoaFob.

This post will discuss the other side of the equation: what it takes to get the Potion Store and CocoaFob licensing up and running on your own hardware under Leopard Server. Surprisingly little, actually.

Basically this is a place for me to keep all the code snippets and info I will need in case I ever have to rebuild this server. Hopefully it can be of use to others who take this road.

This article assumes intermediate-level knowledge of the command line, servers and mysql. If you have your own server, I'll take this as a given. Personally, my Ruby, Rails and Unix experience is relatively limited, so this has been a great learning experience for me.

The reasons behind setting up Potion Store on your own hardware will vary. In our case it stems from our web server company's lack of Ruby on Rails support, combined with the convenient availability of a spare Leopard Server machine at my workplace.

First steps

Several documents guided my way in the initial setup of Ruby on Rails. Apple provides a good resource in this article, but it is a little overcomplicated for our scenario. I found the best resource to be the "Working with Ruby on Rails" chapter of the Web Technologies Admin pdf documentation.

Leopard server ships with Ruby on Rails and a host of gems, however it's worth updating to the latest versions before we begin:

sudo gem update

Potion Store

You can grab the latest Potion Store build from github.

You will need to upload this to the directory of your webserver. Then follow closely the steps outlined in the Potion Store ReadMe file.

Integrating CocoaFob licensing

You can grab the latest CocoaFob build from github.

You will need to replace the default licensekey.rb license key generator in your Potion Store /lib folder with the one from the /ruby directory of CocoaFob.

You'll also need to make one small change in Potion Store to /db/migrate/001_create_tables.rb to support the longer license codes that CocoaFob makes.

Modify line 61:

t.column "license_key", :string, :limit => 64

To read:

t.column "license_key", :string, :limit => 128

Then run:

rake db:migrate

From your potionstore directory.

I made one change to CocoaFob's custom /lib/licenceskey.rb file to support multiple products on our store:

Modify line 21 to read:

priv = OpenSSL::PKey::DSA.new(File.read("lib/"+product_code+"/dsapriv512.pem"))

Modify line 33 to read:

pub = OpenSSL::PKey::DSA.new(File.read("lib/"+product_code+"/dsapub512.pem"))

Store your private and public keys for each product under /lib/<product code>/.

Mongrel

My previous experiences with web development have been with php and html. It took me a while to get my head around the fact that Rails has its own web server architecture(s), distinct from Apache. Thankfully the Apple documentation guides you through setting up reverse proxies to serve Mongrel processes via Apache.

This initially sounded clumsy, but I soon came to appreciate the beauty of the arrangement. I ended up with three basic commands to start my Rails process.

For debugging, you simply run from the /potionstore directory:

script/server

And then test the store at http://localhost:3000.

This logs everything that occurs to the terminal. Ctrl-C will exit the process and stop the server.

For development, you run:

sudo mongrel_rails_persist start -p 3001 -c /path/to/potionstore

Which enables robust testing, and instant updates when you change your code.

Potion Store is configured to use the PayPal sandbox while in development, so this is ideal for getting all the bugs worked out without actually allowing live transactions.

When you are finally ready to switch over to production, run:

sudo mongrel_rails_persist start -p 3001 -e production -c /path/to/potionstore

You can stop the Mongrel process at any time using the command:

sudo mongrel_rails_persist stop -p 3001

When you have a Mongrel process running your Potion Store, you can set up a reverse proxy so that Apache serves it up at your designated address. So, for example, your Mongrel process on port 3001 is served on port 80 at the /store directory. Very neat and flexible compared with traditional php/html development, once you have all the pieces in place.

See the Apple documentation for more information on setting up reverse proxies.

Sendmail

Potion Store sends an email with the new license on completion of checkout. The default implementation is only part of the code required for this to work, most likely because it will vary from server to server. I found the following modifications to work on my Leopard server:

Modify /config/environments/*.rb
to add the following code underneath the default code:

config.action_mailer.smtp_settings = {
  :address => "localhost",
  :port => 25,
  :domain => "store.<mydomain>.com"
}

Customisation

Modify Potion Store's /app/views/layouts/store.rhtml file to suit your site. For a developer with php experience, this part seemed very familiar.

Conclusion

Setting up a Potion Store deployment for MachineCodex took me all in all about a week for research, installation and debugging. I have detailed most of the pitfalls I encountered above, hopefully if you find this article it will help you avoid the wasted time and minor frustration I experienced in the process. Now that it's up and running, we love our Potion Store, and I learned a lot!