Handling 404 Errors

Ramaze has a built-in controller action to handle 404 errors; it presents a vanilla page stating ‘No action found at: /xyz‘. Overriding this action is easy and well documented but there are a couple of things that might want to consider.

First, if you would like all 404 errors across your application to be handled by a single action, you will need to add your handling code to the base controller.

Second, using a view file corresponding to the controller action does not quite work. While the view is correctly rendered when the 404 occurs directly under a path mapped to the 404 handler’s controller (eg. /my_missing_action) it is not rendered for 404 errors occurring under paths mapped to other controllers (eg. /users/my_missing_action).

A workaround for this is to use the render_file method to manually render a view you’ve created. I have not done due diligence on this problem so I cannot tell you why it occurs – maybe it is a bug or maybe (likely) I’m missing something. If anyone has an explanation or a better work around I’d love to hear it.

Source for a Custom 404 Handler

Handling Exceptions

Routing Exceptions

Ramaze also has a built-in exception handler which presents a developer-friendly stack trace (one which I’m sure you will want to hide for the end-users). The Ramaze Google Group discussions here and here talk about how to override this default handler. It boils down to using Rack::RouteExceptions.route(exception, to); a method that takes the type of exception to route and the path of the action to route it to.

For example, to route all exceptions to the same controller you could use (as stated by Lars Olsson here):

Rack::RouteExceptions.route(Exception, MyController.r(:error))

Alternatively, to handle all IOError exceptions separately you could use:

Rack::RouteExceptions.route(IOError, MyController.r(:io_error))
Rack::RouteExceptions.route(Exception, MyController.r(:error))

Note the order of the calls to route is important. You must route the most specific exceptions first or they will be routed to more general handlers specified before them.

Unlike the 404 error handler, using a standard view file does work here.

The Exception Object

To obtain the exception object within the controller action you can call:

@error = request.env[Rack::RouteExceptions::EXCEPTION]

Source for a Custom Exception Handler

What You Need

I’ve included the version number of the software I’ve tested this setup with but I suspect this configuration will work with newer versions as well (and probably older versions too).

1. RACK (web server interface)
   • 1.0.1
2. Unicorn (http server)
   • 0.95.2
3. Nginx (front end reverse proxy server)
   • 0.6.36
4. God (process monitoring)
   • 0.7.13
5. Ramaze (web framework)
   • 2009-05

Some Assumptions

While the config files below make the following assumptions you should be able to handle any discrepancies by altering the paths or changing the run user.

1. Nginx is configured to read configuration files from its conf/sites-enabled directory
   • Add include <path to nginx install>/conf/sites-enabled/*; to the http section of your primary Nginx config file to enable this
2. Your website will run under the www-data user
3. The Nginx, Unicorn and God config files exist within the config directory of your Ramaze website
4. The RACK config file (config.ru) is in the root of your website
5. You’ve created the log and tmp/pids directories underneath the root of your website

Configuring the Pieces

1. RACK

This config file is actually a very simple ruby file, its main purpose in this situation is to load your website’s app.rb via the require statement. This in turn loads the rest of your site.

3. Unicorn

While I’ve commented the major parts of the configuration file inline, I highly recommend checking out the Unicorn website and this sample configuration file for more details/features.

2. Nginx

You can find more info about configuring Nginx here. If assumptions #2 & #4 are true then you’ll need to create a symlink in the <path-to-nginx-install>/conf/sites-enabled/* directory to your Nginx config in the config directory under the root of your website. You can do this by executing

ln -s /var/www/apps/my.domain.com/config/nginx.conf <path-to-nginx-install>/conf/sites-enabled/my.domain.com

4. God

As with the RACK and Unicorn config files, this one is also written in Ruby. The God home page has a much more detailed breakdown of the config file and is definitely worth a read.

Flicking the Switch

Once you have your configuration files in place and your website on your target server you’re going to need to turn it all on. The first step is to tell God to keep an eye on your Unicorn process and the second step is to cycle Nginx forcing it to pickup your new website’s config file.

Alerting God

The first thing to do is start God and have it monitor your master Unicorn process for your new website. If God is not already running you can start it using:

god --log-level=debug

To have it start monitoring your Unicorn process, execute the following:

sudo god load /var/www/apps/my.domain.com/config/god.conf

Cycling Nginx

Cycling Nginx is something that cries out for a script so here is a simple one:

Dealing with Errors

After flicking the switch for the first time under this setup I’ve run into a 502 bad gateway error multiple times. Each time it was because I had forgotten to create the required tmp/pids or log directories under the website root. If you do run into a 502 its probably because Unicorn had trouble starting up or Nginx is not pointing to the right spot.

Debugging

Check the God logs for your website by executing:

god --log-level debug log my.domain.com

That will tell you if God has managed to start the Unicorn process successfully. If it has then checkout the Unicorn error logs in the log directory of your website. If it cannot start the process and doesn’t indicate why then try executing the Unicorn startup command in a shell directly (that should at least give you the error message Unicorn is generating).

The title of this blog post is a little inaccurate as what I’m actually going to describe are Etanni partials but considering Etanni is the default template engine in Innate/Ramaze 2009-10 I figured “Ramaze Partials” was a fair generalization.

Etanni partials are easy to work with and as Pistos points out below they are documented in the rdocs. That said, when I went about looking for info on them (using Google) I missed the rdocs and could only find brief mentions of a “render helper” in the blogosphere. My hope is that this post will make it easier to find this information.

The Render Helper

This render helper can be found in the Innate code base – it is clearly commented and worth a look if you’ve got a few minutes. There are 3 methods that this helper provides to aid you in the creation of your partials:

1. render_partial
2. render_view
3. render_file

I will only cover render_partial as it is the only one that I’ve needed to use thus far.

render_partial

render_partial(action_name, variables = {})

The action_name parameter references a controller method and the variables parameter is a hash which is turned into members which are locally accessible within that method. Note that action_name doesn’t have to actually have a method declaration within a controller – it can simply be the name of a view.

Example

Here is the example code for a rendering contact information via an Etanni partial: