Russell Haering

Cast Preview Release

2011-04-25T00:00:00+00:00

For the last few months I've been working on and off for Cloudkick (now Rackspace) on a project that we are calling Cast. I'm happy to announce that this afternoon we're releasing Cast version 0.1. The source has been on Github all along, but with this release we feel that the project has finally progressed to a point where:

We've implemented the functionality planned for the first iteration.
The afforementioned functionality actually works against the current version of Node.js.
We have a website and documented most of the imporant parts.

Thats Great, So What Is It?

In short, Cast is an open-source deployment and service management system.

At Cloudkick we tend to see users deploying their code in one of three ways:

Services are deployed via a configuration management system such as Puppet or Chef.
Services are deployed by some sort SSH wrapper such as Fabric or Capistrano.
Services are deployed to a "Platform as a Service" such as Heroku.

But none of these are perfect. Respectively:

The high overhead in interacting with configuration management systems is fine when they are managing 'infrastructure' (that is, the systems on which you run your services), but tend to impede a smooth "devops" style workflow with fast iterations and easy deployment and upgrades.
SSH wrappers typically work well enough on small scales, but but they feel like a hack, and don't trivially integrate with in-house systems.
Of all the options, people seem to like these the best. The price speaks for itself - Platforms as a Service (PaaS) are hugely valuable to their users. The problem is that these platforms are closed systems, inflexible and not very "sysadmin friendly". When they go down, you're trapped. When the pricing or terms change, you're trapped. If they don't or can't do what you want, you're trapped.

With this situation in mind, what could we write for our users? An Open Platform (optionally, as a Service).

What Can it Do?

Using Cast you can:

Upload your application to a server.
Create 'instances' of your application. Think 'staging' and 'production'.
Manage (start, stop, restart, etc) services provided by your application.
Deploy new versions of your application.
Do all of this from the command line or from a REST API.

We have a lot more interesting features planned. Hint: think "Cast cluster". But if this sounds like something you're interested in, stay tuned, share your thoughts or consider looking into a job at the new San Francisco Rackspace Office

Directory-Backed Resources in Node.js

2011-02-12T00:00:00+00:00

After writing my last post about the flow control techniques we are using in cast I realized that the process of writing the post was probably as valuable to me as the post will be to anyone else (especially since it was on such a well covered topic). It forced me to explicitly state and justify my reasoning, and caused me to rethink a few things in the process. Since then, whenever I've found myself contemplating a design issue I've tried to think of how I would write it up. This post is the logical extension of that plan, that is, an actual writeup of just such an issue.

The Problem

In cast, we maintain very little state in memory between requests. Most state is stored to the filesystem in the form of the directory structures that we use to manage applications, services, etc. As such we have a lot of code dedicated to managing these resources, including the 'Instance' class I mentioned last time (pedants: I know, JavaScript technically has no classes, but thats the pattern we're emulating so thats what I'm going to call them). For a lot of reasons, most of which are outside the scope of this discussion, we've found an Object-Oriented model to be the best way to represent these resources.

There are three main ways that instances of such a class tend to be created:

We create a new resource on the filesystem and return an instace of the class for further operations.
We create a single instance of the class to represent a resource that already exists.
We create a list of class instances to represent the set of all existing resources of this sort on the filesystem.

The problem is that creating a new resource on the filesystem (obviously) requires filesystem operations and when retrieving one or more instances to represent pre-existing resources we almost invariably want to make sure that the resource in question actually exists, again requiring filesystem operations. This means that each of these operations must be done in an asynchronous manner. In short

var foo = new Instance('foo');

is not sufficient to either create a new instance or retrieve one with any assurance that it exists.

The Solution

Once again, the solution itself isn't all that revolutionary: we need factories. While many seem to associate the term with unpleasant memories of Java, factories are pretty standard practice in Node, and as a general matter are a very good thing.

There are two general patterns with factories in Node. The first, and the one that is most common in Node's public APIs, is to return objects that implement the EventEmitter (a sort of general purpose promise - but don't tell anyone I said that) interface, then let the user register callbacks for various events on that object. For example, to create a TCP connection:

var net = require('net');

// Create a connection to google.com on port 80
var goog = net.createConnection(80, 'google.com');

// Wait for the connection to actually open before using it
goog.on('connect', function() {
  goog.setEncoding('utf8');
  goog.on('data', function(chunk) {
    console.log(chunk);
  });
  goog.write('GET /\r\nhost: google.com\r\n\r\n');
});

The other, which is less common in Node itself, is to pass a callback to the factory function, which is called with the instance once it is ready. One case where this pattern still exists is in the Node API is in fs.stat():

var fs = require('fs');

fs.stat('/tmp', function(err, stats) {
  console.log(stats.isDirectory());
});

Note: the pattern of passing a callback directly to a function is quite common in Node, but fs.stat() is the only case I know of where the second argument (ie, the one that isn't 'err') is something other than a primitive or a list of primitives. On reflection that's probably a bad way to distinguish a 'factory', so maybe the above is a bad, example but you get the idea.

This second pattern is more appropriate for our purposes, as the instances will tend to be short lived and would be unlikely to ever emit any other event.

Sticking to this pattern, what we've ended up with is something like our instance API in cast:

// Create instance 'foo' using fooapp version 1.0
deployment.create_instances('foo', 'fooapp', '1.0', function(err, instance) {
  ...
});

// Retrieve instance 'foo'
deployment.get_instance('foo', function(err, instance) {
  ...
}); 

// Retrieve a list of all instances
deployment.list_instances(function(err, instances) {
  ...
});

Factory Factories

I've spent the last week or so reworking our test framework in cast and updating everything to work with Node 0.4.0, but when I get the chance one thing I may try is factoring out all of the common code into a single module. This would include a single class that all such resources could inherit from, which would likely include an 'exists' method to test for existence and (yeah, go ahead and hate me, I'm going to say it anyway) "factory factories" to generate factory methods for retrieving and listing them.

While "factory factories" are commonly cited as a great reason to hate Java, in my opinion JavaScript's 'functions as first-class objects' model makes quite pretty. In this case they could make generation of factory methods for directory-backed resource FooResource look something like this:

...
exports.get_fooresource = dir_resources.get(FooResource);
exprots.get_fooresource = dir_resources.get_list(FooResource);

Flow Control in Node.js

2011-02-07T00:00:00+00:00

Late last summer I began working on Cloudkick's new deployment tool, cast which is written in Node.js. At the time I had only minimal experience with JavaScript, having occasionally used it for frontend work on personal projects. After a crash course from Bjorn, Cloudkick's in-house JavaScript wizard, I was able to write mostly working code.

The Problem

As others have found however, writing a Node app that is maintainable is a lot different than just writing one that works.

In cast, we frequently perform long sequences of filesystem operations. For example, for each application deployed in cast we maintain a symlink to the 'current' version. Because symlinks can be atomically replaced with a call to rename the 'current' link will always point to the single current version of the application.

The sequence of operations we need to perform to update the 'current' symlink is:

Determine the path to the new version. We have a method that can do this for us, but it hits the filesystem so calls to it are asynchronous.
Make sure the new version exists. Again, we're hitting the filesystem so this happens asynchronously as well.
Create a new symlink pointing to the specified version. Another filesystem operation.
Swap the new symlink into place using 'rename'.

The naive solution comes out looking something like this:

Instance.prototype.activate_version = function(version, callback) {
  var self = this;
  var new_version_link = path.join(self.root, 'new');
  var cur_version_link = path.join(self.root, 'current');

  self.get_version_path(version, function(err, vp) {
    if (err) {
      return callback(err);
    }
    path.exists(vp, function(exists) {
      if (!exists) {
        return callback(new Error('Cannot activate nonexistent version \'' + version + '\''));
      }
      fs.symlink(path.resolve(vp), new_version_link, function(err) {
        if (err) {
          return callback(err);
        }
        fs.rename(new_version_link, current_version_link, callback);
      });
    });
  });
};

This isn't too bad, but its already getting unwieldy after only four operations (other methods perform ten or more such operations). There are a few problems here:

We quickly end up with very deep nesting which pushes all our code increasingly further to the right and limits the space left on each line for code.
Inserting a new operation early in the chain forces us add another level of indentation to every subsequent operation. This causes commits to contain massive diffs which can hide other accidental (or, theoretically, malicious) changes and obfuscates the actual changes.
Its just plain difficult to read.

The Solution

This isn't exactly revolutionary, but the first step is to use one of the many flow control modules available for Node. For cast we've been using async and I've grown quite attached to it, but there are a lot of other nice ones available as well. Using async, our 'activate_version' method now looks like this:

Instance.prototype.activate_version = function(version, callback) {
  var self = this;
  var new_version_path;
  var new_version_link = path.join(self.root, 'new');
  var current_version_link = path.join(self.root, 'current');

  async.series([
    // Get the path to the specified version
    function(callback) {
      self.get_version_path(version, function(err, vp) {
        new_version_path = vp;
        return callback(err);
      });
    },

    // Make sure the version exists
    function(callback) {
      path.exists(new_version_path, function(exists) {
        var err = null;
        if (!exists) {
          err = new Error('Cannot activate nonexistent version \'' + version + '\'');
        }
        return callback(err);
      });
    },

    // Create the new link
    function(callback) {
      fs.symlink(path.resolve(new_version_path), new_version_link, callback);
    },

    // Atomically move it into place
    async.apply(fs.rename, new_version_link, current_version_link)
  ], callback);
};

I don't want to turn this into an async tutorial, so check out the documentation (or code) if you're curious about the specifics, but in short we get a number of benefits here:

We describe our list of actions by providing a list of functions: its very intuitive.
We avoid both of the problems I mentioned that result from nesting
We provide a single final callback that is always fired, allowing centralized error handling, logging, etc. Alternatively, if the signatures match, we can pass the method's callback argument to async.
We can use async's 'parallel', 'waterfall' or several other methods to change the behavior without significantly altering the pattern.

Once you're using some sort of flow control library, the some things to keep in mind that keep things manageable:

Don't chain multiple asynchronous calls within one function passed to async. If two calls are part of the same logical operation then chances are you should make that operation its own asynchronous function.
If you have a group of logically related calls that could be parallelized, split them into their own function and use async.parallel() (or some equivalent).
If you need to be able to undo your operations in reverse order, you can build a stack of reverse operations as you go, then execute it with async in the final callback.

Projects, Projects, Projects

2011-01-16T00:00:00+00:00

I'm nearly half way through my senior year here at Oregon State University (if all goes well I should graduate in June), but for the next few months it appears that my life will be dominated by a few major projects and a whole lot of minor ones. Since I haven't been very successful in my efforts to think of a good topic to write about recently, hopefully a brief synopsis of my various projects will work instead.

Major Projects

Fuzzing Linux's USB Subsystem

Among my various projects, this is the one I've spent the least time on so far, but one I'm definitely pretty excited about. One of the major requirements of students in the Honors College here is that each student complete a "Thesis" project. In short, pick a topic, spend a bunch of time on it (doing research, making something, etc) then write a paper about what you did and defend it in front of a panel of experts.

While struggling to decide on a topic (having good ideas is the easy part, you also have to find a faculty member willing to mentor you on the project) I found myself in a guest lecture by Brandon Philips who was speaking about Linux Kernel development. Since I've always thought Kernel hacking would be sort of fun, I sent him an email asking for Kernel-related project ideas. One of his suggestions that caught my interest was creating a hardware device to fuzz Linux's USB implementation and drivers. I'm hoping I can get away with doing this in software against a virtual machine, but I have yet to really pursue it too much.

Mobile Accessibility Project

The other major project I have going for school at the moment is my "Senior Project". I'm working with fellow student Kiel Friedt and our mentor Carlos Jensen to create an Android application, designed for the deaf, that runs in the background and causes then phone to vibrate and display a visual notification when it detects sounds such as sirens or alarms.

Obviously this is pretty ambitious given the limitations of the hardware, but as of last night we have basic real-time signal processing working and can generate notifications upon detection of pre-programmed tones. Obviously we're still a long way from being able to detect and identify alarms or sirens, but it does make for a neat demo of what we're working on.

Cast

Of my major projects this is definitely my favorite, and the only one not directly related to school. Since the latter portion of the summer I've been working with a few other developers at Cloudkick on an open source deployment tool we're calling cast.

Basically, we're creating a service in Node.js that provides a RESTful API for deploying, monitoring and managing applications, regardless of their language or purpose. In future versions we intend to add support for clustering, with peer-to-peer distribution across the cluster and a variety of other neat features to help with large deployments in the cloud or the datacenter.

Minor Projects / Courses

Compiler

This term I'm taking a "translators" course in which, over the course of the term, we are constructing a compiler for a contrived language that Dr. Budd came up with. The compiler itself is written in Java, with various stages due over the course of the term (the lexer was due last week, the parser is due this week, and so on). Combined with the written assignments, it seems like this will probably account for somewhat over half of my time spent on non-major projects this term.

Scientific Visualizations

I'm also taking a scientific visualization course in which it seems that we will be creating a number of visualizations over the course of the term. We use OpenGL, which I have some experience with both from the computer graphics course I took last term and from some playing around I did with it back in highschool (I was going to make the next great first person shooter, or something like that).

Building Android Client Applications

2010-08-20T00:00:00+00:00

I've had the privilege of spending this summer down in San Francisco working as an intern at Cloudkick (side note: if you like the cloud and you're interested in working with an incredible team on some sweet projects, check out our jobs page) working on all sorts of cool projects.

In any case, one of the projects I've been working on this summer is an Android client for Cloudkick. Earlier today I pushed version 0.2.1 (the first public release of the 0.2.x series, after I got cold feet on 0.2.0) of the application to the Android Market, and to celebrate all the lessons I've learned, I wanted to share a few of them. In this case, I'm going to give an overview of how to create an Android client for an existing web service. This won't be a full tutorial (indeed, it will assume that you already know how to create a functional Android application of some sort), but if you're interested the source to Cloudkick for Android is available on GitHub.

Disclaimer

I'm not an experienced Java developer, and I'm certainly not an Android expert, so if it looks like I'm doing something wrong, I probably am. I'd love to know about it though, so if you're feeling nice, drop me a comment.
A lot of this code is taken out of context, so if you want it to actually work, just get the original, functional source code.

Step 1: API Client Library

The first thing you'll need is an API client library of some sort. I started out with something like this.

public class CloudkickAPI {
    private static final String TAG = "CloudkickAPI";
    private static String API_HOST = "api.cloudkick.com";
    private static String API_VERSION = "1.0";
    private final String key;
    private final String secret;
    private final HttpClient client;
    private SharedPreferences prefs = null;

    public CloudkickAPI(Context context) throws EmptyCredentialsException {
        prefs = PreferenceManager.getDefaultSharedPreferences(context);
        key = prefs.getString("editKey", "");
        secret = prefs.getString("editSecret", "");
        if (key == "" || secret == "") {
                throw new EmptyCredentialsException();
        }

        HttpParams params = new BasicHttpParams();
        HttpProtocolParams.setVersion(params, HttpVersion.HTTP_1_1);
        HttpProtocolParams.setContentCharset(params, HTTP.DEFAULT_CONTENT_CHARSET);
        HttpProtocolParams.setUseExpectContinue(params, true);

        SchemeRegistry registry = new SchemeRegistry();
        registry.register(new Scheme("http", PlainSocketFactory.getSocketFactory(), 80));
        registry.register(new Scheme("https", SSLSocketFactory.getSocketFactory(), 443));

        ClientConnectionManager connman = new ThreadSafeClientConnManager(params, registry);
        client = new DefaultHttpClient(connman, params);
    }
}

There are a few things going on here:

The TAG string is useful for logging (I saw this suggested on StackOverflow, I'm not sure if its standard practice or what)
The Cloudkick API requires OAuth authentication, so I retrieve an OAuth key and secret from the preferences storage, which we haven't set up yet. So unless you know how to do that yourself, this isn't going to actually work just yet.
If the credentials are empty, throw a custom exception. This is handy for redirecting the user to the login screen if they haven't attempted a login.
The HTTP Client setup is somewhat more complicated than I would like, but I needed it to support multi-threading. I'm still not positive I got all of the necessary settings, but it seems to work for me.

Right, so this obviously doesn't actually do anything so far, so lets go ahead and make that happen:

private String doRequest(String path) throws BadCredentialsException, OAuthException, IOException {
    HttpResponse response = null;
    StringBuilder body = new StringBuilder();
    try {
        HttpGet request = new HttpGet("https://" + API_HOST + "/" + API_VERSION + path);
        OAuthConsumer consumer = new CommonsHttpOAuthConsumer(key, secret);
        consumer.sign(request);
        response = client.execute(request);
        if (response.getStatusLine().getStatusCode() == 401) {
            response.getEntity().consumeContent();
            throw new BadCredentialsException();
        }
        InputStream is = response.getEntity().getContent();
        BufferedReader rd = new BufferedReader(new InputStreamReader(is));
        String line;
        while ((line = rd.readLine()) != null) {
            body.append(line);
        }
    }
    finally {
        if (response != null && response.getEntity().isStreaming()) {
            response.getEntity().consumeContent();
        }
    }
    return body.toString();
}

public ArrayList<Node> getNodes() throws BadCredentialsException, OAuthException, IOException, JSONException {
    String body = doRequest("/query/nodes");
    ArrayList<Node> nodes = new ArrayList<Node>();
    JSONArray rawNodes = new JSONArray(body);
    int rawCount = rawNodes.length();
    for (int i = 0; i < rawCount; i++) {
        nodes.add(new Node(rawNodes.getJSONObject(i)));
    }
    Log.i(TAG, "Retrieved " + nodes.size() + " Nodes");
    return nodes;
}

So, notable things here:

It is important to consume all content off of the HTTP response, even if an error occurs, otherwise the connection won't be freed up and you will eventually run out of free connections in your pool.
We have another custom exception which gets thrown if a 401 status code is returned, indicating that the user's credentials were invalid (as opposed to empty).
We throw everything. You don't really need to list these out, but it comes in handy later when you want to know what exceptions to look for.
I'm constructing custom Node objects from the returned JSON list. The details aren't really important, but a Node is basically a constructor that fills in a bunch of 'final' fields.

Obviously you'll want more API methods than this, but you get the idea. Each method just calls doRequest() then constructs an object or list of objects to be returned.

Step 2: An Activity

To actually display the data, you'll need an activity. A lot of web API clients spend a lot of time displaying and drilling down lists, so I'm going to use one of those as an example.

public class DashboardActivity extends Activity implements OnItemClickListener {
    private static final String TAG = "DashboardActivity";
    private static final int SETTINGS_ACTIVITY_ID = 0;
    private static final int LOGIN_ACTIVITY_ID = 1;
    private static final int refreshRate = 30;
    private CloudkickAPI api;
    private ProgressDialog progress;
    private ListView dashboard;
    private NodesAdapter adapter;
    private boolean haveNodes = false;
    private boolean isRunning = false;
    private final ArrayList<Node> nodes = new ArrayList<Node>();
    private final Handler reloadHandler = new Handler();
    
    @Override
    public void onCreate(Bundle savedInstanceState)
    {
        super.onCreate(savedInstanceState);
        PreferenceManager.setDefaultValues(this, R.xml.preferences, false);
        dashboard = new ListView(this);
        adapter = new NodesAdapter(this, R.layout.node_item, nodes);
        dashboard.setAdapter(adapter);
        dashboard.setOnItemClickListener(this);
        dashboard.setBackgroundColor(Color.WHITE);
        setContentView(dashboard);
        reloadAPI();
    }
    
    private void reloadAPI() {
        try {
            api = new CloudkickAPI(this);
            haveNodes = false;
        }
        catch (EmptyCredentialsException e) {
            Log.i(TAG, "Empty Credentials, forcing login");
            Intent loginActivity = new Intent(getBaseContext(), LoginActivity.class);
            startActivityForResult(loginActivity, LOGIN_ACTIVITY_ID);
        }
    }
    
    @Override
    protected void onActivityResult(int requestCode, int resultCode, Intent data) {
        if (requestCode == SETTINGS_ACTIVITY_ID) {
            reloadAPI();
        }
        if (requestCode == LOGIN_ACTIVITY_ID) {
            try {
                if (data.getBooleanExtra("login", false)) {
                    reloadAPI();
                }
                else {
                    finish();
                }
            }
            catch (NullPointerException e) {
                finish();
            }
        }
    }
}

This is pretty straightforward, when the Activity is created it sets up the list view which uses a subclassed ArrayAdapter called NodesAdapter (more on that momentarily). Then, it calls reloadAPI() which attempts to instantiate a CloudkickAPI. However if an EmptyCredentialsException is thrown it starts up a LoginActivity. To be honest, the way the LoginActivity in Cloudkick for Android works is probably very dissimilar from anything most people will need (the API it uses was designed to be easily parsed from a C client, the login process requires multiple requests with possible user input between them, etc), but the concept with this is fairly simple: get and validate some sort of credentials from the user, and store the necessary tokens for use by the API client. Then return from the LoginActivity, setting a boolean to indicate that the user actually logged in (as opposed to using the back button to exit the application).

This last bit might seem a little odd, but the idea is that when the user opens the application for the first time and sees the login screen, you (obviously) want them to be able to exit if they don't feel like logging in just then. If you were to simply call reloadAPI() every time the LoginActivity returned, if the user just pressed the back button they would be continuously bounced back to the LoginActivity until they filled in some sort of credentials. So we detect that case by the absence of the "login" boolean in the returned Intent and simply exit if they didn't attempt to login. This is another one of those things that I'm sure there is a better way to handle, but I haven't put much thought into figuring out what it is.

Now ListViews aren't much fun unless you populate them, so lets look at how to do that. Inside of the DashboardActivity we add some methods:

@Override
protected void onResume() {
    super.onResume();
    isRunning = true;
    reloadService.run();
    Log.i(TAG, "Reloading service started");
}

@Override
protected void onPause() {
    super.onPause();
    isRunning = false;
    if (progress != null) {
        progress.dismiss();
        progress = null;
    }
    reloadHandler.removeCallbacks(reloadService);
    Log.i(TAG, "Reloading callbacks canceled");
}

private void refreshNodes() {
    if (api != null) {
        if (!haveNodes) {
            progress = ProgressDialog.show(this, "", "Loading Nodes...", true);
        }
        new NodeUpdater().execute();
    }
}

private class NodeUpdater extends AsyncTask<Void, Void, ArrayList<Node>> {
    private Exception e = null;

    @Override
    protected ArrayList<Node> doInBackground(Void...voids) {
        try {
            return api.getNodes();
        }
        catch (Exception e) {
            this.e = e;
            return null;
        }
    }

    @Override
    protected void onPostExecute(ArrayList<Node> retrieved_nodes) {
        // Get rid of the progress dialog either way
        if (progress != null) {
            progress.dismiss();
            progress = null;
        }
        // Handle errors
        if (e != null) {
            if (e instanceof InvalidCredentialsException) {
                Toast.makeText(DashboardActivity.this.getApplicationContext(), "Invalid Credentials", Toast.LENGTH_SHORT).show();
                Intent settingsActivity = new Intent(getBaseContext(), Preferences.class);
                startActivityForResult(settingsActivity, SETTINGS_ACTIVITY_ID);
            }
            else if (e instanceof IOException) {
                Toast.makeText(DashboardActivity.this.getApplicationContext(), "A Network Error Occurred", Toast.LENGTH_SHORT).show();
            }
            else {
                Toast.makeText(DashboardActivity.this.getApplicationContext(), "Unknown Refresh Error", Toast.LENGTH_SHORT).show();
                Log.e(TAG, "Unknown Refresh Error", e);
            }
        }
        // Handle success
        else if (isRunning) {
            nodes.clear();
            nodes.addAll(retrieved_nodes);
            haveNodes = true;
            adapter.notifyDataSetChanged();
            // Schedule the next run
            reloadHandler.postDelayed(reloadService, refreshRate * 1000);
            Log.i(TAG, "Next reload in " + refreshRate + " seconds");
        }
    }
}

private final Runnable reloadService = new Runnable() {
    public void run() {
        // This happens asynchronously and schedules the next run
        refreshNodes();
    }
};

So this is where things get a bit weird. Obviously you don't want to lock up the UI when you retrieve data from the API, but since we're still (as far as I can tell) mostly stuck doing things synchronously on Android, we need to push API requests into a background thread. So I'm just going to run through what happens here, in the order that it happens:

Whenever the Activity is resumed we set a variable to indicate that its running, then kick off this Runnable called reloadService.
reloadService just calls refreshNodes()
refreshNodes() makes sure the API is non-null (I don't remember why I did that or if I still need that check...). Then if we don't have any nodes yet it pops up a fatty modal dialog box (some day I'm going to replace this with a spinning "Loading" animation in the ListView itself like I just did for the NodeViewActivity). Finally it instantiates and executes a NodeUpdater object.
The NodeUpdater extends AsyncTask, which is a neat little API that Android has for doing tasks in the background. Basically the method doInBackground() is (believe it or not) done in a background thread.
This is all great, but it really messes with error handling. Remember that giant list of Exceptions that the API's getNodes() method can throw? Well we can't modify the UI from this background thread, so normal exception handling patterns sort of go out the window. Instead, if any sort of Exception is thrown, we store it in a field called 'e' for later access.
Once the API call has returned the onPostExecute() method is called, this time in the UI thread. If one of those obnoxious modal loading dialogs exists we kill it off right away. Then, we check whether an exception is stored in that 'e' field and if it is we put it through a big if/elseif where we check its type against various Exception subclasses that we might want the user to know about, and show the user some sort of Toast based on the type of exception.
If no exception occurred and 'isRunning' is still true (ie, the user didn't get bored and leave in the meantime), we replace the contents of the existing (currently empty) node array with the returned list of nodes. Then we set 'haveNodes' so the user won't see that silly modal dialog again, and use a handler to schedule another run of the reloadService in 30 seconds.
When the activity is paused any scheduled API calls are canceled and 'isRunning' is set to false so that any ongoing API calls don't try to update the UI when they return.

Step 3: The List Adapter

In order to make the ListView not suck, we also need to use a custom adapter.

public class NodesAdapter extends ArrayAdapter<Node> {
    private final int resource;
    
    public NodesAdapter(Context context, int resource, ArrayList<Node> nodes)
    {
        super(context, resource, nodes);
        this.resource = resource;
    }
    
    @Override
    public View getView(int position, View convertView, ViewGroup parent)
    {
        RelativeLayout nodeView;
        Node node = getItem(position);

        String inflater = Context.LAYOUT_INFLATER_SERVICE;
        LayoutInflater li = (LayoutInflater)getContext().getSystemService(inflater);

        if(convertView==null) {
            nodeView = new RelativeLayout(getContext());
            li.inflate(resource, nodeView, true);
        }
        
        else {
            nodeView = (RelativeLayout) convertView;
        }
        
        // Set the a color representing the state
        TextView statusView = (TextView)nodeView.findViewById(R.id.node_item_status);
        statusView.setBackgroundDrawable(new ColorDrawable(node.getStateColor()));
        
        // Set the background
        ColorDrawable transparent = new ColorDrawable(Color.TRANSPARENT);
        ColorDrawable opaque = new ColorDrawable(node.color);
        StateListDrawable bg = new StateListDrawable();
        bg.addState(new int[] {android.R.attr.state_selected}, transparent);
        bg.addState(new int[] {android.R.attr.state_pressed}, transparent);
        bg.addState(new int[] {}, opaque);
        nodeView.setBackgroundDrawable(bg);
        
        // Set the name and tags
        TextView nameText = (TextView)nodeView.findViewById(R.id.name);
        TextView tagsText = (TextView)nodeView.findViewById(R.id.tags);
        nameText.setText(node.name);
        tagsText.setText(node.getTagString());
        
        return nodeView;
    }
}

Basically whenever the ListView wants to display a node in the list, it will call getView on the adapter. In this case most of that code is dedicated to setting a crazy background on the list items. If there are a relatively small number of background colors you will need for list items, just do this in XML and save yourself the trouble. But one cool feature of Cloudkick is that you can assign one of a bunch of colors to each of your nodes (just for organizational purposes). In order to make the selector (the orange - with the default theme - thing that highlights list items when you scroll) show through, I had to use a StateListDrawable to make the background transparent when the item was selected or pressed and opaque otherwise. But like I say, most people won't need this so your adapter will probably be much simpler than this.

Step 4: Drill Down

If all your application does is display a ListView, it had better be a really really nice ListView. Even then, you probably want to be able to drill down to get details on those items. This is easy, we just need to add one function to the DashboardActivity:

public void onItemClick(AdapterView<?> parent, View view, int position, long id) {
    Bundle data = new Bundle();
    data.putSerializable("node", nodes.get(position));
    Intent intent = new Intent(DashboardActivity.this, NodeViewActivity.class);
    intent.putExtras(data);
    startActivity(intent);
}

And don't forget that line (already shown above) in onCreate():

dashboard.setOnItemClickListener(this);

When the user clicks a node, the node is serialized into a Bundle which is passed to a NodeViewActivity.

The NodeViewActivity is very similar to the DashboardActivity, with a few modifications:

It extracts the serialized node from the passed Bundle and uses that to instantly populate (part of) the view.
It polls for changes on both the node itself, and its check data. This works pretty much the same way as it does here, there are simply two
It uses a nicer loading animation in the ListView itself, sort of like Gmail, Seesmic (which I really like) and half of the other apps on the market.

And thats basically it. There is a lot of code duplication between Activities, so one thing on my TODO list is attempting to abstract most of that out into a single base class, but I'm not certain when I'll be able to make that happen.

Again, check out the full source over on GitHub, and drop me a comment if you found this helpful, or if it looks like I'm doing something wrong.

Blogging with Mingus

2010-05-17T00:00:00+00:00

This will be the 4th post on this blog announcing that I'm switching to new blogging software - of 6 total posts. Maybe I just like deploying things more than maintaining them. But in this particular case, Wordpress had to go. Every few days it would just die randomly. The php-cgi processes would just lock up until I came in and killed things manually. Wordpress is actually pretty decent from a user perspective, and I suspect the lockups had something to do with the way I was running it or one of the plugins I was using.

I settled on Mingus. Mingus is basically a collection of reusable Django "apps" put together to form a blog. At first I was skeptical, but I have to say I'm impressed. It has an impressive array of built in apps and features. For example the django-request app gives a nice overview of visitors to the site without the need for AWStats or Google Analytics. Of course it has built in Google Analytics support as well. Mingus comes with so many built in features that I have yet to try most of them, and have ended up disabling some.

Mingus is not something a non-technical person could probably set up, but if you know a little about python webapps you could probably get Mingus going in a few minutes. Importing posts, tweaking the layout, etc will take somewhat longer, but Mingus is very hackable and you'll hardly be alone: github currently shows 45 forks of Mingus, including mine.

Emulating an Event-Based Virtualization API

2010-02-22T00:00:00+00:00

For the last few months at the OSL we've been experimenting with a program called Ganeti. Ganeti is a system for managing a virtualization cluster. There are a lot of benefits to using Ganeti, which I'll save for another time, but one of my favorites is that it has an HTTP API. For example (with hostnames redacted)

russell_h@skyship ~ $ curl -k https://localhost:8889/2/nodes
[
    {
        "id": "node1.example.com",
        "uri": "/2/nodes/node1.example.com"
    },
    {
        "id": "node2.example.com",
        "uri": "/2/nodes/node2.example.com"
    },
    {
        "id": "node3.example.com",
        "uri": "/2/nodes/node3.example.com"
    },
    {
        "id": "nod4.example.com",
        "uri": "/2/nodes/node4.example.com"
    }
]

Now I don't know about anyone else, but to me that just screams "web interface".

One thing that has always bothered me about web interfaces to backend systems like this is that the state of the system is constantly changing. In general, when you load up the interface it takes a "snapshot" of the system, and thats what you see until you (or some javascript) poll for an updated version. Compare that to a desktop application like virt-manager which is constantly updating the view, allowing you to make decisions based on the state the system is in, rather than the state it was in. For more on the topic, albeit on a somewhat different scale, I highly recommend George Reese's recent article, Towards Event-Driven Cloud APIs.

One solution is to just poll really often. You can even cache the poll response for a few seconds to avoid hitting the backend API every time someone reloads the page. But thats still relatively inefficient, particularly in situations where there is a high likelihood that nothing has changed.

Short of coding an event based API into Ganeti (an idea I haven't entirely discarded), the best option I could think of was to implement a sort of event-based "middleware". The idea is that a client (web browser) can subscribe to a given backend URI. If there are no existing subscribers to that URI, the contents will be fetched, returned to the client, and cached for some given period, say 5 seconds. Once the cache has expired the backend will be polled again. The result will be compared to the previous, cached result, and if the contents have changed the updated version will be sent to every subscriber before being cached. If someone subscribes to an already "active" URI they will be served the cached contents, as well as any future changes.

The whole system being something of an experiment, I decided to implement it using Friendfeed's Tornado and HTML5 Web Sockets.

A backend URI is represented by its cached contents and the set of callbacks provided by subscribers

class URI(object):
    def __init__(self, content={}, callbacks=[]):
        self.content = content
        self.callbacks = callbacks

These will be used by what I am uncreatively calling a "JSONPushProxy"

class JSONPushProxy(object):
    def __init__(self, baseuri, ttl):
        self.http = AsyncHTTPClient()
        self.ttl = ttl
        self.baseuri = baseuri
        self.uris = {}
        self.ioloop = tornado.ioloop.IOLoop.instance()

    def try_callback(self, callback, *args, **kwargs):
        """
       Wraps a callback for some special error handling (borrowed from
       Tornado)
       """
        if callback is None:
            return None
        if args or kwargs:
            callback = functools.partial(callback, *args, **kwargs)
        def wrapper(*args, **kwargs):
            try:
                return callback(*args, **kwargs)
            except Exception, e:
                # TODO: logging
                raise e
        return wrapper

    def subscribe(self, uri, callback):
        """
       Subscribe to content for a URI relative to the Base URI of this PushProxy.
       New subscribers will receive an immediate content push followed by pushes
       of content every time the regularly scheduled check detect a change.
       """
        # If there are no subscribers to this uri
        if not uri in self.uris:
            # Build a new URI
            new_uri = URI(callbacks=[callback])
            self.uris[uri] = new_uri
            # Do the first fetch run
            self.fetch(uri)
        # Otherwise just append a callback and send the current content
        else:
            self.uris[uri].callbacks.append(callback)
            self.alert(callback, uri, self.uris[uri].content)

    def unsubscribe(self, uri, callback):
        """
       Unsubscribe a callback for a URI
       """
        self.uris[uri].callbacks.remove(callback)
        if len(self.uris[uri].callbacks) == 0:
            # If no one is subscribing remove uri from the dictionary
            del self.uris[uri]

    def fetch(self, uri):
        """
       When running, this will be called periodically to update the cache and
       push it's contents to any subscribers.
       """
        r = HTTPRequest(self.baseuri+uri,
                        prepare_curl_callback=ssl_no_verify)

        self.http.fetch(r, callback=self.try_callback(self.on_response, uri))
        # Schedule the next run if we're still going
        self.ioloop.add_timeout(time.time() + self.ttl,
                                self.try_callback(self.fetch, uri))

    def on_response(self, uri, response):
        """
       Called when an HTTP response is available
       """
        new_content = response.body
        try:
            if new_content != self.uris[uri].content:
                self.uris[uri].content = new_content
                # Push update
                for callback in self.uris[uri].callbacks:
                    self.alert(callback, uri, new_content)
        except KeyError:
            # This can happen if the URI has been disabled since the request
            # was initiated
            pass

    def alert(self, callback, uri, content):
        """
       Call a callback
       """
        try:
            callback(uri, content)
        except Exception, e:
            # Unsubscribe this callback
            self.unsubscribe(uri, callback)
            raise e

Calling that "rough around the edges" would be pretty generous, but it mostly works, and at least shows what I was trying to do.

For getting content to the browser, I used Tornado's new-ish WebSocketHandler

class WebSocket(tornado.websocket.WebSocketHandler):
    def __init__(self, application, request):
        self.uri = None
        self.ganeti = application.settings.get('ganeti')
        super(WebSocket, self).__init__(application, request)

    def open(self):
        self.receive_message(self.on_message)

    def on_message(self, message):
        obj = tornado.escape.json_decode(message)
        if obj['action'] == 'subscribe':
            if self.uri:
                self.ganeti.proxy.unsubscribe(self.uri, self.gnt_callback)
            self.uri = obj['uri']
            self.ganeti.proxy.subscribe(self.uri, self.gnt_callback)
        self.receive_message(self.on_message)

    def gnt_callback(self, url, message):
        to_send = "{\"uri\": \"%s\", \"content\": %s}" % (url, message)
        self.write_message(to_send)

Note that I limited the client to being subscribed to one URI at a time.

As far as what happens client-side, that code is a total mess at the moment, but the idea is this: when the page is loaded, the browser opens a web socket to the handler above. When the user navigates, for example, to the list of Nodes, the browser sends a message over the web socket that looks something like this

'{
   "action": "subscribe",
   "uri": "/nodes"
}'

The response will specify the URI that it is from and the actual contents of the API response. From the contents I build a table that is shown to the user. If we add a node (and assuming someone is viewing the node list), within 5 seconds the JSONPushProxy should pick up on this and message every subscriber, where the table will be re-built with the new data.

There are, however, a few downsides to this approach:

First, the use of Web Sockets, which to my knowledge are only supported by Chrome at this point.

Second, there are some issues with displaying the data client-side: I want the user to be able to sort and filter the table, but most of the libraries I've seen for doing this aren't designed to handle changing data. I've managed to get sorting working with the jQuery Tablesorter plugin, but there seems to be some performance issue that I have yet to diagnose. Even after that, usability issues remain. For example, a user might be about to click on a node when a new node is brought online, shifting the list and causing them to click the wrong one. Not the end of the world, and I'm honestly not sure how this is handled desktop applications, but its something to think about.

WordPress with Nginx and PostgreSQL

2010-02-20T00:00:00+00:00

It took a while, but it has finally become obvious to me that I need to spend less time making my blog work and more time doing interesting things to blog about. In other words, I need a blog that "just works". WordPress.

The two complicating factors are that it needs play nice with nginx and postgres. The solution is to use FastCGI and the PostgreSQL for Wordpress (pg4wp) plugin.

We'll need PHP, with CGI support and spawn-fcgi. On Gentoo:

echo "dev-lang/php cgi" >> /etc/portage/package.use
emerge php spawn-fcgi
# Go have a beer, PHP takes a long time to compile

First we need WordPress

# Create a directory for this installation
cd /var/www
mkdir new.russellhaering.com
cd new.russellhaering.com
# Download WordPress
wget http://wordpress.com/latest.tar.gz
# And extract it
tar -xf latest.tar.gz
rm latest.tar.gz

Then the pg4wp plugin

# Download
wget http://downloads.wordpress.org/plugin/postgresql-for-wordpress.1.1.0.zip
# Extract
unzip postgresql-for-wordpress.1.1.0.zip
# Install
mv postgresql-for-wordpress/pg4wp wordpress/wp-content/plugins/
cd wordpress/wp-content
cp plugins/pg4wp/db.php ./

Now we need to configure spawn-fcgi. Create /etc/conf.d/spawn-fcgi.wp which should look something like this

# The path to the socket
FCGI_SOCKET=/var/run/spawn-fcgi/russellhaering_com

# WordPress uses PHP
FCGI_PROGRAM=/usr/bin/php-cgi

# I believe that with the configuration below 1 child is fine
FCGI_CHILDREN=1

# It is convenient to run as nginx, but you could use a different user
FCGI_USER=nginx
FCGI_GROUP=nginx

# PHP will spawn off this many children
PHP_FCGI_CHILDREN=2

# Evidently PHP processes should be restarted every so often
PHP_FCGI_MAX_REQUESTS=500
ALLOWED_ENV="PATH PHP_FCGI_CHILDREN PHP_FCGI_MAX_REQUESTS"

Then create an nginx vhost

server {
    listen 80;
    server_name new.russellhaering.com;

    index  index.php index.html index.htm;

    location / {
        root   /var/www/new.russellhaering.com/wordpress;  # absolute path to your WordPress installation

        # this serves static files that exist without running other rewrite tests
        if (-f $request_filename){
            expires 30d;
            break;
        }

        # this sends all non-existing file or directory requests to index.php
        if (!-e $request_filename) {
            rewrite ^(.+)$ /index.php?q=$1 last;
        }
    }

    location ~ \.php$ {
        fastcgi_pass   unix:/var/run/spawn-fcgi/russellhaering_com-1;  # port where FastCGI processes were spawned
        fastcgi_index  index.php;

        fastcgi_param  SCRIPT_FILENAME    /var/www/new.russellhaering.com/wordpress/$fastcgi_script_name;  # same path as above

        fastcgi_param  QUERY_STRING       $query_string;
        fastcgi_param  REQUEST_METHOD     $request_method;
        fastcgi_param  CONTENT_TYPE       $content_type;
        fastcgi_param  CONTENT_LENGTH     $content_length;

        fastcgi_param  SCRIPT_NAME        $fastcgi_script_name;
        fastcgi_param  REQUEST_URI        $request_uri;
        fastcgi_param  DOCUMENT_URI       $document_uri;
        fastcgi_param  DOCUMENT_ROOT      $document_root;
        fastcgi_param  SERVER_PROTOCOL    $server_protocol;

        fastcgi_param  GATEWAY_INTERFACE  CGI/1.1;
        fastcgi_param  SERVER_SOFTWARE    nginx/$nginx_version;

        fastcgi_param  REMOTE_ADDR        $remote_addr;
        fastcgi_param  REMOTE_PORT        $remote_port;
        fastcgi_param  SERVER_ADDR        $server_addr;
        fastcgi_param  SERVER_PORT        $server_port;
        fastcgi_param  SERVER_NAME        $server_name;

        # required if PHP was built with --enable-force-cgi-redirect
        fastcgi_param  REDIRECT_STATUS    200;

    }
}

Go ahead and start things up..

/etc/init.d/spawn-fcgi.wp start
/etc/init.d/nginx restart

Now you should be able to perform a fairly standard WordPress installation. Just use your Postgres database and password when it asks for DB info (or when modifying the config file).

Dynamic Blogging

2010-01-26T00:00:00+00:00

So after my brief stint using Hyde I've decided that its just not quite right for me.

That being said I still hoped to avoid the A, M and P pillars of the LAMP stack, so I wasn't going to just roll out a Wordpress or Drupal instance. I investigated a few existing Django blog solutions but in the end decided to just make my own.

So here it is. Its nowhere near done, but as I work I keep finding topics to blog about, so I finally decided to just get something online so at least I can use it in the process.

The application is a collection of Django 'apps' that handle comments, blog posts, navigation and static pages.

The application is running on the CherryPy WSGI Server using Peter Baumgartner's django_cpserver. Public connections are proxied through nginx, which also serves static media and will eventually be used for limited caching. Configuring this was trivial, merely a matter of sropping django_cpserver into the site root, running './manage.py runcpserver' then adding a proxypass line to the nginx config.

Also I've imported the two posts I made on my static blog.

More to come on all of this...

Static Blogging

2009-12-22T00:00:00+00:00

I've decided to give blogging another shot. Since I only have 360MB of RAM on my VPS, and plan to use it for a number of other services, I want to keep resource use to a minimum. I've been playing with nginx and love it, but what to use for the blog? I'm not going to run MySQL just for a blog, which rules out Wordpress and Drupal. I really don't like SQLite. And as much as I like Django (which supports Postgres which I'm running anyway), the Django blogging apps I looked at just weren't quite what I wanted.

So I started looking at static website generators. I've heard a lot of good things about Jekyll, but I'm not ready to install Ruby just to generate a static site. Then I found Hyde. It uses the Django template engine, can parse a bunch of different markup formats and doesn't make a lot of assumptions about how you will use it. It's a little confusing at first and I'm still getting it set up, but I'm going to put the whole thing in a public git repo in case anyone is curious.

Running cgit under nginx

2009-12-22T00:00:00+00:00

Like many in the open source community, I've developed a bit of an addiction to git. I use git for keeping track of class notes, homework, this blog, nearly everything we do on the OSU Open Source Lab Systems team and, of course, coding. I have hosted a number of repositories (mostly for long dead programming projects on GitHub but while it has a lot of great features, sometimes I just want a level of control that github just doesn't offer.

But when you do want to share your git repositories, you probably want a way to browse them via the web. And there just aren't that many options. Gitweb is probably the most popular and runs on kernel.org, with cgit in second. Of the two I prefer cgit because it is light and fast with excellent caching. But both cgit and GitWeb are CGI based, and nginx doesn't support CGI.

The solution I came up with is to route requests through a little program called fcgiwrap. To begin with, you'll need to download and install it.

git clone git://github.com/gnosek/fcgiwrap.git
cd fcgiwrap
make
make install

However fcgiwrap alone can't handle FastCGI requests, so we need to set upsomething like spawn-fcgi. At least on Gentoo this is fairly easy.

echo "www-servers/spawn-fcgi" >> /etc.portage/package.keywords
emerge -av spawn-fcgi
ln -s spawn-fcgi /etc/init.d/spawn-fcgi.cgit
cp /etc/conf.d/spawn-fcgi /etc/conf.d/spawn-fcgi.cgit

Because you might want to do this process for multiple CGI scripts the init script is designed to be symlinked for each instance. Now you need to edit /etc/conf.d/spawn-fcgi.cgit to look something like this

# I used a unix socket since nginx and cgit are on the same machine
FCGI_SOCKET=/var/run/spawn-fcgi/code_russellhaering_com

# Again, I don't need these
FCGI_ADDRESS=
FCGI_PORT=

# Tell spawn-fcgi what program to execute
FCGI_PROGRAM=/usr/local/bin/fcgiwrap

# You don't really need to change any of these
FCGI_CHILDREN=1
FCGI_CHROOT=
FCGI_CHDIR=

# You probably don't want cgit running as root
FCGI_USER=nginx
FCGI_GROUP=nginx

# I'm not sure if this is really essential
ALLOWED_ENV="PATH"

I found that I had to 'chown -R nginx:nginx /var/run/spawn-fcgi since both programs accessing the socket will be running as user nginx.

Of course you'll also need cgit itself

wget http://hjemli.net/git/cgit/snapshot/cgit-stable.tar.gz
tar -xf cgit-stable.tar.gz
make get-git && make
# Create a web root
mkdir -p /var/www/code.russellhaering.com/htdocs
# And copy over the important stuff
cp cgit /var/www/code.russellhaering.com/htdocs/
cp cgit.css /var/www/code.russellhaering.com/htdocs/
cp cgit.png /var/www/code.russellhaering.com/htdocs/

Now edit /etc/cgitrc

# enable caching of up to 1000 output entries
cache-size=1000

# page title for the root page (repo listing)
root-title=Russell's Git Repositories

# description for the root page
root-desc=

# link to css file
css=/cgit.css

# link to logo file
logo=/cgit.png

# root path for cached output
cache-root=/var/cache/cgit

# time-to-live settings: specify how long (in minutes) different pages should
# be cached. specify 0 for instant expiration and -1 for immortal pages

# ttl for root page (repo listing)
cache-root-ttl=0

# ttl for repo summary page
cache-repo-ttl=0

# ttl for other dynamic pages
cache-dynamic-ttl=0

# ttl for static pages (addressed by SHA-1)
cache-static-ttl=0

# allow download of tar.gz and tar.bz2 files
snapshots=tar.gz tar.bz2

include=/etc/cgitrc.local

Notice how I left caching disabled. Thats because I'm going to use the built in nginx fastcgi caching. You'll also need to edit /etc/cgitrc.local - this is what I have right now.

repo.url=russellhaering.com
repo.desc=Hyde configuration for russellhaering.com
repo.path=/var/lib/git/russellhaering.com.git
repo.owner=russell_h
repo.clone-url=git://code.russellhaering.com/russellhaering.com

And of course you'll also need to set up nginx itself.

I added a line like this to the 'http' section of my nginx.conf

# Use up to 10 Megabytes for the 'code' cache, keep inactive cache around for 1h
fastcgi_cache_path /var/cache/nginx levels=1:2 keys_zone=code:10m inactive=1h max_size=100m;

You may need to create and set appropriate permissions on that cache directory

And added a 'server' section like this

server {
    listen 80;
    server_name code.russellhaering.com;

    # Serve static files
    location ~* ^.+\.(css|png|ico)$ {
        root /var/www/code.russellhaering.com/htdocs;
        expires 30d;
    }

    location / {
        rewrite ^/$         /cgit   permanent;
        rewrite ^/cgit/$    /cgit   permanent;

        fastcgi_cache      code;
        fastcgi_cache_valid 200 5m;
        fastcgi_cache_use_stale off;

        fastcgi_pass            unix:/var/run/spawn-fcgi/code_russellhaering_com-1;
        fastcgi_read_timeout    5m;
        fastcgi_index   /;

        fastcgi_param    DOCUMENT_ROOT    /var/www/code.russellhaering.com/htdocs;
        fastcgi_param    SCRIPT_FILENAME  /var/www/code.russellhaering.com/htdocs/cgit;
        fastcgi_param    QUERY_STRING  $query_string;
        fastcgi_param    REQUEST_METHOD  $request_method;
        fastcgi_param    CONTENT_TYPE  $content_type;
        fastcgi_param    CONTENT_LENGTH  $content_length;
        fastcgi_param    GATEWAY_INTERFACE  CGI/1.1;
        fastcgi_param    SERVER_SOFTWARE  nginx;
        fastcgi_param    SCRIPT_NAME  $fastcgi_script_name;
        fastcgi_param    REQUEST_URI  $request_uri;
        fastcgi_param    DOCUMENT_URI  $document_uri;
        fastcgi_param    DOCUMENT_ROOT  $document_root;
        fastcgi_param    SERVER_PROTOCOL  $server_protocol;
        fastcgi_param    REMOTE_ADDR  $remote_addr;
        fastcgi_param    REMOTE_PORT  $remote_port;
        fastcgi_param    SERVER_ADDR  $server_addr;
        fastcgi_param    SERVER_PORT  $server_port;
        fastcgi_param    SERVER_NAME  $server_name;
    }

    access_log /var/log/nginx/code.russellhaering.com/transfer/access_log combined;
    error_log /var/log/nginx/code.russellhaering.com/error/error_log warn;
}

At this point you should be set to go, excepting any permissions, etc that I neglected to mention. Go ahead and try it out

/etc/init.d/spawn-fcgi.cgit start
/etc/init.d/nginx restart

I suppose I should mention that I am seeing an issue that I think is related to the caching, where every so often when you click a link in cgit the address in the address bar updates but the page doesn't actually change. Clicking the link again has always fixed the problem. I looked in the logs and didn't see anything unusual, so it may be an issue in Chromium, but for the moment I'm content to leave it. If you happen to know what this is about and want to share, please do.