Getting Started With SCGI

This is just a quick HOWTO document showing you how to get your Ruby On Rails application running under the SCGI Rails Runner server. I’ve heard of a few people who are testing this out for production deployment, so feel free to try it out and give me feedback. Some people have had problems with Typo in the past, but I test with Typo and it works for me.

What Is SCGI

SCGI is an alternative protocol for a web server to run an application under the CGI system, but without starting the application over and over again. It’s like FastCGI but is much simpler to implement and simple is always a good thing.

Running your Ruby On Rails application under the SCGI Rails Runner (SRR) will make it easy for you to run your application independent of the fronting web server, and should give you great performance without a lot of the management headaches associated with FastCGI and Rails.

Install

There are two requirements before you start:

cmdparse 2.0.0 or greater.
highline 1.0.1 or greater.

You can install both via RubyGems, but the latest gems for SRR should include them as dependencies.

After that, installation couldn’t be easier. You can either install via the RubyGem I provide or install directly from the source.

To install SRR the easy way simply download the gem and install it directly:

wget http://www.zedshaw.com/downloads/scgi_rails/scgi_rails-VERSION.gem gem install scgi_rails-VERSION.gem

Where VERSION is the version you want to install. That should do it for just about everyone.

If you’re allergic to RubyGems or have the need to install directly, then you can do the following:

wget http://www.zedshaw.com/downloads/scgi_rails/scgi_rails-VERSION.tar.bz2 tar -xjf scgi_rails-VERSION.tar.bz2 cd scgi_rails-VERSION sudo ruby setup.rb

If you don’t know what any of those commands do then just install the gem or learn to use Unix.

Win32 Notes

See Win32 specific page for more information.

The main things to know when running this all under Win32 are:

Windows does not support POSIX signals so always pass -S to scgi_ctrl config.
Windows doesn’t have POSIX fork so don’t start your processor with scgi_ctrl start. Instead use scgi_service in a command window.
I’m working on a service installer that should help with all of these problems.

Setup SCGI in Rails

Once you’ve installed it you should get three commands:

scgi_ctrl—Controls individual SCGI processors and configures them.
scgi_service—Runs an SCGI processor. scgi_ctrl actually handles starting this unless you’re on Windows.
scgi_cluster—Does basically the same thing as scgi_ctrl but to a whole bunch of processors at once.

The first thing you need to do is configure your processor using scgi_ctrl config. To do this simply go to your Rails application’s directory. Read that again! Not the app/ directory, but the one right above that where you can see config/, etc. Once you’re in the right directory just do:

scgi_ctrl config

This will configure your first processor for the default options. Check the file config/scgi.yaml for what those defaults are. Use scgi_ctrl help config to find out what options are available.

NOTE:  Did you give a good password?  You'll need to remember this for later.  The password prevents
people from accessing the SCGI processor's control protocol without your permission.  Without it
anyone who can connect to port 8999 (by default) could mess with your Rails application.

An important thing is that if you just want to change one option then use scgi_ctrl config -M <new options> which will merge (-M) your previous config with the new options.

After you’ve got the processor configured you just need to start it up. On any POSIX system you do:

scgi_ctrl start

But on Windows you need to do:

scgi_service

After that you can check the log/scgi.log to see if it’s listening and then move to configuring you web server of choice.

Additional Commands

The following is a list of the available scgi_ctrl commands and what they do:

config—Configure the SCGI processor cluster
help—Provide help for individual commands
list—List the currently running SCGI processors
monitor—Monitor the application
reconfig—Reconfigure the SCGI servers with a new config
restart—Restart the application
start—Start the application
status—Get status
stop—Stop the application
version—Show the version of the program

Cluster Management

In the previous version there was a feature called simple clustering. This feature is currently removed until I can nail down some stability issues. Instead I’ve created a simple way to setup clustering using the scgi_cluster tool. This tool basically configures as many children as you want and then manages them all for you just like if you were running scgi_ctrl on each one.

To configure three children to run in a cluster is pretty easy from the SRR perspective:

scgi_cluster config -c 3

This will create a series of config/scgi-#.yaml files (where # is replaced with a child number). Each of these files can be used with scgi_ctrl to directly control that child if it’s not behaving correctly:

scgi_ctrl -c config/scgi-0.yaml stop -f

Which just says, “Force the processor defined in config/scgi-0.yaml to stop now.”

Once you’ve configured your processors you can start them all with:

scgi_cluster start

This will start all of the processors up for you to run. An important thing to know is that they listen on ports starting at 9999 and going up from there. So these three would listen on 9999, 10000, 10001. The control protocol will then listen on ports 1000 lower than this: 8999, 9000, 9001. Make sure you use the -p option to change how this is done, or just edit the configs directly if you need something truly odd.

Once the cluster is up you have all of the previous commands available. If you need to know which ones are running, then look for the config/scgi-children.yaml and config/scgi-cluster.yaml files.

The only difficult part at this point is configuring your web server to access the cluster on all the different ports. Refer to the configuration documentation for you web server for more information on this.

Configuring Web Server

There are three pages of information for your particular web server configuration with SCGI:

These configurations are mostly just simple ones based on borrowed information from others. The Lighttpd configuration is the one I use the most, and was given to me by Jan the Lighttpd as the option.

Also look in the source package samples directory for examples for each config. They aren’t complete but they should give you a clue.

Testing It All Out

Well, hopefully you have something you want to try out, so hit the web server at a URI that Rails will answer and see if it works.

Graceful Restart And Status

So you’ve got this massive banking application running that must always work and never lose a user’s request. In addition to this you’re a cowboy developer who insists on restarting production systems at will, exerting your power over your customers like Zues over the ancient world. It’s your code dammit and you have the need-no, the right-to do whatever the hell you want without telling anyone else what’s going on. Fuck planning dammit, you’re a smart motherfucker.

Ok, first off you’re an idiot. You must plan your upgrades if you want to keep your customers. Developers like you piss me off to no end. Your myopic view of the whole operation only means you’re too stupid to take your ass out of your little chair in your little cubicle, march it down the hallway, and tell the other people on your team that you’re going to destroy the world. What would be optimal is if you could make sure you do the changes and restarts on a planned schedule that involves all parties agreeing that the system will go down, what will change, and how to back it out.

But, hey, I just write software right? What the hell do I know? Since you’re going to want to shutdown and restart your systems at will anyway to make up for your lack of planning, here’s how you can do it “gracefully”. You should be seriously warned that you should never depend on this being 100% flawless, and anyone telling you their “graceful restart” will never lose a request is full of shit.

It’s pretty easy to do a graceful restart:

scgi_ctrl restart

And with the cluster tool:

scgi_cluster restart

If any of the processors seem to get jammed up then you’ll need to restart them directly with their individual config file:

scgi_ctrl -c config/scgi-0.yaml restart -f

You should then watch the log/scgi.log file to make sure they shutdown and restart. They will wait until all of the requests are handled and they will redirect new request to /busy.html. After all the requests are handled (or you force them to stop) then the whole command will be rerun to do the restart. This means that if you change code and then do a restart all of the new code and configs will get picked up.

With the scgi_cluster shutdown it’s important to watch the logs. If one of the processors doesn’t exit (happens sometimes), then you need to force it. The good thing is that all requests it handles will get the /busy.html page.

Stopping

Stopping is pretty easy:

scgi_ctrl stop

And you can do the -f option to force it. The same is true for the scgi_cluster command.

The /busy.html Redirect

One questionable feature is the /busy.html file redirects. Whenever the server is overloaded (based on the -m (maxconns) option) or in the process of a graceful shutdown/restart it will send all new requests to /busy.html.

You should create this page so that people can see a friendly message rather than nothing. Under lighttpd they will even get an infinite redirect which is just lighttpd’s problem.

The reason /busy.html was chosen rather than a 503 status (which is the correct status) is that lighttpd and Apache didn’t support passing back a 503 status to the client. They both scrubbed the status out and did their own thing, which ended up being a pretty nasty 500 message or worse.

By redirecting to /busy.html you can give a nice message and let them try the request again.