Webtypes - Home

Globalizing Mephisto (Part 4)

2007-05-21T15:15:00Z

Another update to the plugin means that rather than using subdomains you can now define the locale via a path parameter e.g.

12	http://webtypes.com/es/2007/5/15/globalizando-mephisto-3-partehttp://webtypes.com/es/admin/articles/edit/2

Read on to see how …

Welcome to the fourth part of the Globalizing Mephisto article series which shows you how to enable the definition of the active locale via a path parameter rather than via subdomains.

Part 1 – Installation and usage for single site mephisto
Part 2 – Deployment and production issues
Part 3 – Installation and usage for multi site mephisto
Part 4 – Using a path parameter to define the locale

When I first posted about the mephisto_i18n plugin on the mephisto forum some people mentioned that they thought using subdomains to define the active locale wasn’t very handy, especially for mephisto instances on shared hosts.

In response to that feedback, I’ve now updated the plugin to allow locale definition either via:

subdomains (default)
path parameter

Using the ‘path parameter’ mode means you can have urls like this:

http://webtypes.com/
http://webtypes.com/es
http://webtypes.com/es/2007/5/15/globalizando-mephisto-3-parte
http://webtypes.com/es/sobre
http://webtypes.com/es/admin/articles/edit/2

Enabling path parameter mode in 3 easy steps

Update environment.rb

Add the following line to your environment file:

Mephisto::I18N.locale_definition = :path

Update routes.rb

Replace the call to:

Mephisto::Routing.connect_with map

with

Mephisto::I18N::Routing.connect_with map

in your routes file.

Update your liquid templates (optional)

Optionally, modify any hard-coded links in your liquid templates like so:

before

<a href="/{{'blog' | t: 'urls'}}">{{'Weblog' | t}}</a>

after

<a href="{{i18n.l}}/{{'blog' | t: 'urls'}}">{{'Weblog' | t}}</a>

NOTE: This assumes you’ve already installed the plugin for a single site or multi site globalized mephisto.

What has been done for you automatically…

When in path parameter mode and the active locale is not the base locale then:

The plugin automatically rewrites urls generated via the url_rewriter which means that all links using link_to and family are automatically correctly localized.
The article/section & site urls (tag/search) are automatically prepended with the correct language code which means most of the links of your site will just work.

Please do try out this mode and, as usual, I appreciate your feedback.

Saimon Moore (also in Greek, Spanish & Catalan :)

Globalizing Mephisto (Part 3)

2007-05-15T13:33:00Z

For those of you who asked about multi site support for this plugin, this is now available. Read on to find out how to convert to a globalized multi-site mephisto …

Welcome to the third part of the Globalizing Mephisto article series where I’ll be talking about how to use this plugin with a multi site mephisto instance.

Part 1 – Installation and usage for single site mephisto
Part 2 – Deployment and production issues
Part 3 – Installation and usage for multi site mephisto
Part 4 – Using a path parameter to define the locale

I’ve updated the plugin to provide full multisite support:

All rake tasks now have multi site support, allowing you to easily convert an existing globalized single site mephisto instance into a multisite instance with little effort.
You can now also specify separate list of supported locales for each site so that site 1 can support english, french and german, site 2: spanish & catalan and site 3: klingon, esperanto and elfish.
SupportedLocales now loads the locales lazily.

Single-site to multi-site.

Create a new site instance

Create a new site instance. e.g. via something like:

123	s = Site.create(:host => "webtypes.com", :title => "Webtypes", :subtitle => 'We do web, and you?')s.sections << Section.create(:name=>"Home", :path =>'', :template=>"home.liquid")s.save

Add the following to environment.rb:

123	Site.multi_sites_enabled = true SupportedLocales.define_by_key('saimonmoore.net',['el-GR', 'es-ES', 'ca-ES'],'en-GB')SupportedLocales.define_by_key('webtypes.com',['es-ES','nl-NL'],'en-GB')

Create subroots

If you haven’t already globalized your mephisto then follow the same steps as before what are you referring to? ensuring the first step in this list has been done which list?. If you’re upgrading a single site globalized mephisto then just execute:

12	svn up vendor/plugins/mephisto_i18nrake mephisto:i18n:ui:setup_subroots

This will create all the necessary subroots within /public/cache/saimonmoore.net, /public/cache/webtypes.com. It’ll also add symlinks to public/assets so that within your site, you can just access /assets/2007/10/3/myimage.png.

This is how my public directory looks after running setup_subroots for a multisite-enabled mephisto:

(Note: I’ve retained the previous subroots from my single instance site (the ca,es,el directories, but in a multisite system the base doc root is /public/cache/site_host)

saimon@iris:~/dev/projects/saimonmoore.net$ ll public/
total 32K
-rw-r--r-- 1 saimon  619 2007-04-20 17:04 404.html
-rw-r--r-- 1 saimon  684 2007-04-20 17:04 500.html
drwxr-xr-x 6 saimon  160 2007-05-14 13:57 assets/
drwxr-xr-x 3 saimon  304 2007-04-20 17:04 ca/
drwxr-xr-x 5 saimon  136 2007-05-14 14:02 cache/
-rwxr-xr-x 1 saimon  479 2007-04-20 17:04 dispatch.cgi*
-rwxr-xr-x 1 saimon  859 2007-04-20 17:04 dispatch.fcgi*
-rwxr-xr-x 1 saimon  479 2007-04-20 17:04 dispatch.rb*
drwxr-xr-x 5 saimon  120 2007-04-20 17:04 documents/
drwxr-xr-x 3 saimon  304 2007-04-20 17:04 el/
drwxr-xr-x 3 saimon  304 2007-04-20 17:04 es/
-rw-r--r-- 1 saimon    0 2007-04-20 17:04 favicon.ico
drwxr-xr-x 4 saimon   96 2007-05-11 13:46 images/
-rw-r--r-- 1 saimon 3.3K 2007-04-20 17:04 install.html
drwxr-xr-x 4 saimon   96 2007-04-20 17:04 javascripts/
-rw-r--r-- 1 saimon   99 2007-04-20 17:04 robots.txt
-rw-r--r-- 1 saimon  631 2007-04-20 17:04 sitemap.txt
drwxr-xr-x 4 saimon  136 2007-05-14 09:27 stylesheets/


saimon@iris:~/dev/projects/saimonmoore.net$ ll public/cache/
total 0
drwxr-xr-x 6 saimon 400 2007-05-14 14:02 saimonmoore.net/
drwxr-xr-x 5 saimon 376 2007-05-14 14:02 webtypes.com/


saimon@iris:~/dev/projects/saimonmoore.net$ ll public/cache/saimonmoore.net/
total 0
lrwxrwxrwx 1 saimon  24 2007-05-18 13:48 404.html -> ../../../public/404.html
lrwxrwxrwx 1 saimon  24 2007-05-18 13:48 500.html -> ../../../public/500.html
lrwxrwxrwx 1 saimon  38 2007-05-18 13:48 assets -> ../../../public/assets/saimonmoore.net/
drwxr-xr-x 3 saimon 232 2007-05-18 13:50 ca/
drwxr-xr-x 3 saimon 232 2007-05-18 13:50 el/
drwxr-xr-x 3 saimon 232 2007-05-18 13:50 es/
drwxr-xr-x 3 saimon  72 2007-05-18 13:54 images/
drwxr-xr-x 3 saimon  72 2007-05-18 13:54 javascripts/
drwxr-xr-x 3 saimon  72 2007-05-18 13:54 stylesheets/


saimon@iris:~/dev/projects/saimonmoore.net$ ll public/cache/webtypes.com/
total 0
lrwxrwxrwx 1 saimon  24 2007-05-18 13:48 404.html -> ../../../public/404.html
lrwxrwxrwx 1 saimon  24 2007-05-18 13:48 500.html -> ../../../public/500.html
lrwxrwxrwx 1 saimon  35 2007-05-18 13:48 assets -> ../../../public/assets/webtypes.com/
drwxr-xr-x 3 saimon 232 2007-05-18 13:50 es/
drwxr-xr-x 3 saimon  72 2007-05-18 13:54 images/
drwxr-xr-x 3 saimon  72 2007-05-18 13:54 javascripts/
drwxr-xr-x 3 saimon 232 2007-05-18 13:50 nl/
drwxr-xr-x 3 saimon  72 2007-05-18 13:54 stylesheets/

saimon@iris:~/dev/projects/saimonmoore.net$ ll public/cache/webtypes.com/javascripts/
total 0
lrwxrwxrwx 1 saimon 39 2007-05-18 17:35 mephisto -> ../../../../public/javascripts/mephisto/

saimon@iris:~/dev/projects/saimonmoore.net$ ll public/cache/webtypes.com/images/
total 0
lrwxrwxrwx 1 saimon 34 2007-05-18 17:35 mephisto -> ../../../../public/images/mephisto/

saimon@iris:~/dev/projects/saimonmoore.net$ ll public/cache/webtypes.com/stylesheets/
total 0
lrwxrwxrwx 1 saimon 39 2007-05-18 17:35 mephisto -> ../../../../public/stylesheets/mephisto/

Update your webserver

Finally update your webserver to point to the new subroots. For those using the very recommended nginx server that would be:

server {
    listen       80;

   #Spanish locale: es subdomain
    server_name es.webtypes.com;

    root /var/www/apps/saimonmoore.net/current/public/cache/webtypes.com/es;
    ...
}

showing the change needed for the ‘es’ (spanish) virtual host. Update the rest of the virtual hosts as necessary.

Other fixes

Fixes for the automatically generated “switch locale” links via:
```
{{ i18n.switch_to_locale_links }}
```
These no longer break when browsing the archives/tags, searching for articles or using any custom controllers. WARNING!: As a result of this change it is necessary to update your schema (which basically localizes site.search_path/tag_path) via:
{{ rake mephisto:i18n:update_schema }}
Also, in order for the search feature to be correctly localized, you need to ensure the search form submit url is localized (and the view translation is the same as the model translation of site.search_path )

e.g.
<form method="get" id="sform" action="/{{'search' | t: 'urls'}}">
Note the use of the ‘urls’ namespace….
Within the admin interface, when switching to the base locale, the locale switcher will automatically switch to www.mydomain.com rather than e.g. en.mydomain.com if base locale is english.
Moved certain rake tasks related to schema changes to the mephisto:i18n namespace.
Updated rake tasks. mephisto:i18n:un/install_schema to accept the LANGS environment variable to easily add more languages to the schema.
It’s no longer necessary to manually add the session domain (ActionController::CgiRequest::DEFAULT_SESSION_OPTIONS.update(:session_domain => ’.saimonmoore.net’)) to environments/production.rb as this is now automatically done for you.
Various fixes to the Translations module including ordering entries case-insensitively, fixing bug where interpolated keys weren’t being found (‘bla %s ..’), now the search function searches translated text rather than keys.

Custom controllers

If you’re using a mephisto plugin that injects it’s own custom controller and routes (.e.g the contact form plugin) and you’d like to localize it’s url, then simply add something like the following to your routes file:


ActionController::Routing::Routes.draw do |map|
  map.contact_form 'contact' >> :urls, :controller => 'contact_form', :action => 'contact_form'
  map.contact_submit 'contact_submit', :controller => 'contact_form', :action => 'contact_submit', :conditions => { :method => :post }
  Mephisto::Routing.connect_with map
end

Note: The urls in the routes are localized so you need to translate them in the translations tab. This relies on code from the following plugin which has been incorporated into this plugin.

Known bugs/limitations

Currently if multisite mode is enabled, you have to use “SupportedLocales.define_key()” to define the supported locales for each site, even if both site will support the same locales. i.e. You have to duplicate the entries:

12	SupportedLocales.define_by_key('saimonmoore.net',['es-ES','nl-NL'],'en-GB')SupportedLocales.define_by_key('webtypes.com',['es-ES','nl-NL'],'en-GB')

I’ll try and fix this soon so you can just define:

SupportedLocales.define(['es-ES','nl-NL'],'en-GB')

and both sites will support the same locales.

Future plans

There’s been talk on the mephisto forums about using an alternative localization library to localize mephisto which will make it’s way into trunk. I’ve already expressed my opinions on that issue so I won’t regurgitate here, suffice to say that if that happens I will still be supporting and maintaining the globalize-plugin. Of course, it’ll be a complete pain and I’ll have to do a quite a bit of hacking but I’m commited to this (since I use it for my own client applications) so I’ll be maintaining it no matter what.
“Upgrade for support with the next version of globalize”. We’re pushing through a lot of changes for the next version of globalize and this will soon be available. When this happens I’ll be updating this plugin for compatibility with the new globalize.
“Edge-Rails support”. I’ve decided to only maintain support for use of the plugin with Rails 1.2.x for now. When the next major release of rails occurs, I’ll update the plugin. That said, anyone wanting to provide patches for edge-rails support is more than welcome. (Patches are generally welcome :)
“Support for allowing your readers to translate your content for you”. I’m working on a separate plugin for mephisto to allow you to do this. It’ll obviously depend on this one but I’d rather keep it separate for now. Or should I just bundle it together?
“Support for publishing/hiding content without translations”. Currently, untranslated content is visible and shown in the base language. With this feature, you’ll be able to selectively hide/show content that has no translation for a whole locale or on an individual basis. I’m also toying with the idea of providing place holders for untranslated content.

Sites running the mephisto_i18n plugin

We’ve got 4 sites up using this plugin:

amicsmuseuprecolombi.org
webtypes.com / saimonmoore.net (multisite)
ktiniatreio.gr

Other sites

onlinevortex.com & bitmapped.onlinevortex.com. (This site by Carlos Mendoza is running a slightly customized version of the plugin to allow specifically named domains to indicate the language rather than using the language code prefix)

If you’ve got a site running this plugin, please let me know so I can add it to the list. Also if you’ve set it up using a different webserver/app server configuration, I’d like to know about it too. Just leave a comment here

Prefer to use a path parameter to define the active locale? Read Part 4

Saimon Moore (also in Greek, Spanish & Catalan :)

Globalizing Mephisto (Part 2)

2007-03-21T08:40:00Z

I’ll be walking you through, the deployment issues that arise with the setup enforced by the plugin covering topics such as web server configuration (nginx) and mongrel hacking …

Welcome to the second part of the Globalizing Mephisto article series where I discuss various deployment issues surrounding the use of this plugin.

Part 1 – Installation and usage for single site mephisto
Part 2 – Deployment and production issues
Part 3 – Installation and usage for multi site mephisto
Part 4 – Using a path parameter to define the locale

I’ll be walking you through, the deployment issues that arise with the setup enforced by the plugin.

Document Roots and Virtual Hosts

As I mentioned in my previous article, the mephisto_i18n plugin maintains the current locale of a session by assuming that the top level subdomain of the host indicates the language part of the locale.

e.g.


  example.com => base locale is currently active (e.g. English )
  es.example.com => 'es' locale is currently active (e.g. Spanish )
  fr.example.com => 'fr' locale is currently active (e.g. French )

So the web server needs multiple virtual hosts, one for each of the languages to be supported.

e.g


  * RAILS_ROOT/public               (Holds the base locale's doc root)
  * RAILS_ROOT/public/es             (Holds the 'es' locale's doc root)
  * RAILS_ROOT/public/fr             (Holds the 'fr' locale's doc root)

In the previous article we’ve seen how the rake tasks provided by the plugin, make setting up these doc roots a piece of cake, and from now on I’m assuming that you’ve got all that setup and mephisto is globalized and running well in development mode.

Setting up the web server

So we need to setup the web server to hande multiple document roots. You need to have a server that has support for name-based virtual hosts. These days any decent web server should have this baked in.

Mine’s a cup of nginx

My current preferred web server is Nginx (go here for details in other languages) so I’m going to show you the configuration I use for this particular web server.

Of course, any web server that can handle virtual hosts will do. e.g. Apache , Lighttpd

The nginx config file usually resides at /usr/local/nginx/conf/nginx.conf

The following nginx.conf assumes there are 4 different virtual hosts. One each for the en,es,ca and fr locales. It also assumes that Catalan (ca) is the base locale.

Additionally, it redirects all requests for any unrecognised subdomains (as well as the base locale subdomain) to www.

e.g. requests coming to somesubdomain.example.com will be redirected to www.example.com Also if we assume catalan is the base locale, requests for ca.example.com will be redirected to www.example.com

Just leave the last virtual host out if you don’t want this redirection to occur.

Also, I’m showing the whole nginx.conf here including the virtual hosts, but what i like to do for production is to put the different server directives for a specific site in their own file and use an include directive to pull it in.

e.g. /usr/local/nginx/conf/apps/saimonmoore.net.conf

and just add:


include apps/saimonmoore.net.conf;

within the http directive. (I usually add it at the bottom). Within each app config I also include the call to the upstream directive


upstream mongrel_saimonmoore.net {
   server 127.0.0.1:8080;
   server 127.0.0.1:8081;
}

Here is the full example nginx.conf file though:


  # user and group to run as
  #user  www-data www-data;
  # number of nginx workers
  worker_processes  2;

  # pid of nginx master process
  pid        /var/log/nginx/nginx.pid;

  # Number of worker connections. 1024 is a good default
  events {
      worker_connections  1024;
  }

  # start the http module where we config http access.
  http {
    # pull in mime-types. You can break out your config
    # into as many include's as you want to make it cleaner
      include       conf/mime.types;
      # set a default type for the rare situation that
      # nothing matches from the mimie-type include
      default_type  application/octet-stream;

      # configure log format
      log_format  main  '$remote_addr - $remote_user [$time_local] $status '
                        '"$request" $body_bytes_sent "$http_referer" '
                        '"$http_user_agent" "$http_x_forwarded_for"';

      # main access log
      access_log  /var/log/nginx/access.log  main;
      # main error log
      error_log  /var/log/nginx/error.log info;

      # no sendfile on OSX uncomment
      #this if your on linux or bsd
      #sendfile        on;

      # These are good default values.
      tcp_nopush     on;
      keepalive_timeout  65;
      tcp_nodelay        on;

      # this is where you define your mongrel clusters.
      # you need one of these blocks for each cluster
      # and each one needs its own name to refer to it later.
      # To determine how many mongrels are necessary follow:
      # http://mongrel.rubyforge.org/docs/how_many_mongrels.html
      upstream mongrel_example.com {
          server 127.0.0.1:8080;
          server 127.0.0.1:8081;
      }

      # output compression saves bandwidth
      gzip on;
      gzip_comp_level 2;
      gzip_min_length  1100;
      gzip_buffers     4 8k;
      #gzip_proxied any;
      gzip_types       text/plain text/html text/css application/x-javascript text/xml application/xml application/xml+rss text/javascript;

      #server_names_hash_bucket_size 32/64/128
      server_names_hash_bucket_size 64;

      #vhosts for example.com
      #
      #root /var/www/apps/example.com/current/public;
      #Spanish locale: es subdomain
      server {
          listen       80;

          server_name es.example.com;

          root /var/www/apps/example.com/current/public/es;

          access_log  /var/log/nginx/host.access.log  main;
          rewrite_log on;

          if (-f $document_root/maintenance.html){
            rewrite  ^(.&#42;)$  /maintenance.html last;
            break;
          }

          location /index2 {
            rewrite (.&#42;) / permanent;
          }

          location / {
            proxy_set_header  X-Real-IP  $remote_addr;
            proxy_set_header  X-Forwarded-For $proxy_add_x_forwarded_for;
            proxy_set_header Host $http_host;
            proxy_redirect false;

            # If the file exists as a static file serve it directly without
            # running all the other rewite tests on it
            if (-f $request_filename) {
              break;
            }

            # check for index.html for directory index
            # if its there on the filesystem then rewite
            # the url to add /index.html to the end of it
            # and then break to send it to the next config rules.
            if (-f $request_filename/index.html) {
              rewrite (.&#42;) $1/index.html break;
            }

            # this is the meat of the rails page caching config
            # it adds .html to the end of the url and then checks
            # the filesystem for that file. If it exists, then we
            # rewite the url to have explicit .html on the end
            # and then send it on its way to the next config rule.
            # if there is no file on the fs then it sets all the
            # necessary headers and proxies to our upstream mongrels
            if (-f $request_filename.html) {
              rewrite (.&#42;) $1.html break;
            }

            if (!-f $request_filename) {
              proxy_pass http://mongrel_example.com;
              break;
            }
          }
      }

      #French locale: fr subdomain
      server {
          listen       80;

          server_name fr.example.com;

          root /var/www/apps/example.com/current/public/fr;

          access_log  /var/log/nginx/host.access.log  main;

          if (-f $document_root/maintenance.html){
            rewrite  ^(.&#42;)$  /maintenance.html last;
            break;
          }

          location /index2 {
            rewrite (.&#42;) / permanent;
          }

          location / {
            proxy_set_header  X-Real-IP  $remote_addr;
            proxy_set_header  X-Forwarded-For $proxy_add_x_forwarded_for;
            proxy_set_header Host $http_host;
            proxy_redirect false;

            if (-f $request_filename) {
              break;
            }

            if (-f $request_filename/index.html) {
              rewrite (.&#42;) $1/index.html break;
            }

            if (-f $request_filename.html) {
              rewrite (.&#42;) $1.html break;
            }

            if (!-f $request_filename) {
              proxy_pass http://mongrel_example.com;
              break;
            }
          }
      }

      #English locale: en subdomain
      server {
          listen       80;

          server_name en.example.com;

          root /var/www/apps/example.com/current/public/en;

          access_log  /var/log/nginx/host.access.log  main;

          if (-f $document_root/maintenance.html){
            rewrite  ^(.&#42;)$  /maintenance.html last;
            break;
          }

          location /index2 {
            rewrite (.&#42;) / permanent;
          }

          location / {

            proxy_set_header  X-Real-IP  $remote_addr;
            proxy_set_header  X-Forwarded-For $proxy_add_x_forwarded_for;
            proxy_set_header Host $http_host;
            proxy_redirect false;

            if (-f $request_filename) {
              break;
            }

            if (-f $request_filename/index.html) {
              rewrite (.&#42;) $1/index.html break;
            }

            if (-f $request_filename.html) {
              rewrite (.&#42;) $1.html break;
            }

            if (!-f $request_filename) {
              proxy_pass http://mongrel_example.com;
              break;
            }
          }
      }

      # Catalan locale: www
      server {
          listen       80;

          server_name www.example.com;

          root /var/www/apps/example.com/current/public;

          access_log  /var/log/nginx/host.access.log  main;

          if (-f $document_root/maintenance.html){
            rewrite  ^(.&#42;)$  /maintenance.html last;
            break;
          }

          location /index2 {
            rewrite (.&#42;) / permanent;
          }

          location / {
            proxy_set_header  X-Real-IP  $remote_addr;
            proxy_set_header  X-Forwarded-For $proxy_add_x_forwarded_for;
            proxy_set_header Host $http_host;
            proxy_redirect false;

            if (-f $request_filename) {
              break;
            }

            if (-f $request_filename/index.html) {
              rewrite (.&#42;) $1/index.html break;
            }

            if (-f $request_filename.html) {
              rewrite (.&#42;) $1.html break;
            }

            if (!-f $request_filename) {
              proxy_pass http://mongrel_example.com;
              break;
            }
          }
      }

      #Catalan locale: tld
      server {
          listen       80;

          server_name example.com;

          root /var/www/apps/example.com/current/public;

          access_log  /var/log/nginx/host.access.log  main;

          if (-f $document_root/maintenance.html){
            rewrite  ^(.&#42;)$  /maintenance.html last;
            break;
          }

          location /index2 {
            rewrite (.&#42;) / permanent;
          }

          location / {
            proxy_set_header  X-Real-IP  $remote_addr;
            proxy_set_header  X-Forwarded-For $proxy_add_x_forwarded_for;
            proxy_set_header Host $http_host;
            proxy_redirect false;

            if (-f $request_filename) {
              break;
            }

            if (-f $request_filename/index.html) {
              rewrite (.&#42;) $1/index.html break;
            }

            if (-f $request_filename.html) {
              rewrite (.&#42;) $1.html break;
            }

            if (!-f $request_filename) {
              proxy_pass http://mongrel_example.com;
              break;
            }
          }
      }

      #Catalan locale: any other subdomain (redirected to www)
      server {
          listen       80;

          server_name ca.example.com &#42;.example.com;
          rewrite  ^(.&#42;) http://www.example.com$1  permanent;
      }
  }

By the way, you can find this file within the resources/config directory in the mephisto_i18n plugin.

Here doggyâ€¦

So once we’ve got the web server all configured, it’s time to take the dog for a walk. :) Unfortunately, this pup is going to be a tad stroppy. Right, enough with the dog lingo, let’s get down to details.

Mephisto is great. However, it likes to serve files.

- That’s not bad is it, I hear someone say.

Not at all, except when you’ve got multiple document roots. Your web server should be configured to forward any request for non-static content to mongrel. That’s fine, mongrel receives the request, and creates a rails process to handle it.

However, by default Mongrel will also attempt to serve static content if it receives a request for something available in the RAILS_ROOT/public (your application’s document root).

This “feature” allows it to be used as is (without the need for a separate web server) while developing normal applications and works great.

But imagine the scenario where a request comes in for:


http://example.com

The web server checks the base locale’s doc root (RAILS_ROOT/public), doesn’t find any index.html and forwards the request to mongrel.
Let me represent that as:


http://example.com => [nginx] RAILS_ROOT/public/index.html ? serve : forward (forward)

(Is that understandable?)

Mongrel also checks but doesn’t find any index.html in the application doc root (RAILS_ROOT/public – which is the only one mongrel knows about), so it creates a rails process which caches the result as RAILS_ROOT/public/index.html.

This is then returned to the web server for serving to the client’s browser. i.e.


http://example.com/index.html (via nginx) => [mongrel] RAILS_ROOT/public/index.html ? serve : pass_to_rails (pass_to_rails)

Ok, so now we’ve cached the home page for the base locale. Let’s refresh the browser and ask for the same page. In short hand:


http://example.com => [nginx] RAILS_ROOT/public/index.html ? serve : forward (serve)

i.e. the web server correctly found RAILS_ROOT/public/index.html in the doc root for the base locale and served it. “yoopee” for page caching.

But now our viewer wants to see the home page in spanish, so we clicks on the “switch locale” link in the home page which sends a request for:


http://es.example.com

The web server receives this and correctly identifies the doc root for the es domain as RAILS_ROOT/public/es. i.e.


http://example.com => [nginx] RAILS_ROOT/public/es/index.html ? serve : forward (forward)

index.html in the RAILS_ROOT/public/es doc root isn’t found so it forwards to mongrel.

Mongrel being a very alert puppy, checks to see if it can serve any static content.

Since it hasn’t got any idea about multiple doc roots, it checks the only doc root it knows about which is RAILS_ROOT/public. i.e.


http://es.example.com/index.html (via nginx) => [mongrel] RAILS_ROOT/public/index.html ? serve : pass_to_rails (serve)

Mongrel finds the index.html created for the base locale, and although alert, it’s not a very bright puppy so it goes ahead and serves that rather than as we’d hope; create a rails processes to cache:


http://es.example.com/index.html => RAILS_ROOT/public/es/index.html

So what has happened here is that the client asked for


http://es.example.com/index.html (RAILS_ROOT/public/es/index.html)

but actually got served


http://example.com/index.html (RAILS_ROOT/public/index.html)

Lay!

This is a bit of a problem :) and I’m sure there are a number of ways to solve this (.e.g. use fcgi/scgi) but if you want to keep using mongrel, then you need to be able to tell mongrel that you don’t ever want it to serve static content ever again.

This way the web server is responsible for serving existing static content and mongrel is responsible for creating the static content only.

Currently (as far as I know), mongrel doesn’t have this capability nor does it support virtual hosts.

Ideally it should support virtual hosts but as it was a lot simpler, I created my own hacked version of mongrel (and the mongrel_cluster gem) to allow for an extra configuration option (dont_serve_static default: false).

When this is set to true, mongrel will diligently create rails processes for every single request that it receives, which solves our little problem nicely.

You can find these hacked versions of mongrel here

To install:


#kill mongrel if its running
sudo /etc/init.d/mongrel_cluster stop
sudo gem uninstall mongrel mongrel_cluster
cd /tmp
wget http://www.webtypes.com/projects/files/basecamp/webtypes/webtypesthebusiness/mongrel_with_dont_serve_static.tar.gz
tar xvfz mongrel_with_dont_serve_static.tar.gz
cd mongrel_with_dont_serve_static
rake package
sudo gem install pkg/mongrel-1.0.1.gem
#Successfully installed mongrel, version 1.0.1

the same for mongrel_cluster :


cd projects/mongrel_cluster/
rake package
sudo gem install pkg/mongrel_cluster-0.2.1.gem
#Successfully installed mongrel_cluster, version 0.2.1

Once you’ve got that installed, then just modify you mongrel_cluster.yml to something like:


---
user: saimon
cwd: /var/www/apps/saimonmoore.net/current
port: "8080" 
environment: production
group: deploy
address: 127.0.0.1
pid_file: log/mongrel.pid
servers: 2
dont_serve_static: true

Note the dont_serve_static: true. That’ll tell mongrel to just do as it’s told and create rails processes.

Conclusion

Well, between these two articles, you should be able to globalize mephisto quite easily. If you have any doubts, questions, feedback or bug reports then feel free to leave a comment here.

Hope this provides a decent i18n solution for people using Mephisto.

P.S. I’m planning on writing a third article about tips an tricks with localising your templates and other tid bits. Perhaps, we could offer alternative globalized versions of the main mephisto themes?

Want a globalized multi site mephisto? Read Part 3

Saimon Moore (also in Greek, Spanish & Catalan :)

Globalizing Mephisto

2007-03-18T13:56:00Z

In this article I hope to walk you through the successful installation of the mephisto_i18n plugin. This plugin converts mephisto into a fully internationalized cms …

This is the first part of a four-part series on Globalizing your Mephisto application.

Part 1 – Installation and usage for single site mephisto
Part 2 – Deployment and production issues
Part 3 – Installation and usage for multi site mephisto
Part 4 – Using a path parameter to define the locale

In this article I hope to walk you through the successful installation of the mephisto_i18n plugin.

In the forthcoming article I’m going to cover getting your web server properly configured and other issues related to the plugin.

Background history

From the clients requirements, we knew that our latest project had to have a decent cms tool. Since we wanted to write this using rails, we searched around and after having looked at a few possibilities we settled on Mephisto.

However, one other important requirement was for the site to be available in multiple languages (at least spanish, catalan, english and french). We knew we had more or less just the one real option, the Globalize plugin.

So I set about to “Globalize” Mephisto.

Globalizing Mephisto

As Mephisto is still in beta (though currently it’s stable for production use) I didn’t want to modify mephsito code directly, rather I set about writing a rails plugin which would monkey patch mephisto to add globalize support.

I decided to use subdomains to indicate the current locale of the application, mostly because it was a lot easier. Otherwise, I’d have had to add in the locale extra parameter all over the place in mephisto code.

So I decided to setup a system where by:


example.com/ www.example.com => base locale is current
es.example.com => es (spanish) locale is current
fr.example.com => fr (french) locale is current

i.e. Several virtual hosts, each of which would have their own document roots:


RAILS_ROOT/public       => doc root for base locale
RAILS_ROOT/public/es    => doc root for es locale
RAILS_ROOT/public/fr    => doc root for fr locale

With the version of Globalize at that time being 1.1, the going was quite tough, mainly because of the select/include limitations enforced by Globalize’s external storage mechanism. As time went on it became progressively more and more difficult to override the mephisto code with the globalize limitations without touching the mephisto code itself (which was my aim).

The story now diverges to the creation of the Globalize internal storage mechanism which is nicely described here so I won’t go into any more detail, suffice to say that with this new way of storing translations, it suddenly became a lot easier to globalize the mephisto models and I quickly got to the point where all my tests were passing.

I then had to deal with things like caching & sweeping for multple doc roots, permalinks and other bits and pieces.

For our application, I then went on to create another couple of plugins to add in extra functionality specific to our application but for the needs of this article that’s enough history for now.

I’ve since cleaned up the plugin a lot, added in rake tasks to simplify the operation of migrating to the globalized system and integrated a number of extra features from our application specific code.

So let me take you through what’s necessary to migrate your mephisto installation to a fully internationalised Mephisto instance.

It just so happens, I want to do the same thing for my own personal blog so I’m going to walk you through what I did to get my own site migrated.

Migrating http://saimonmoore.net; step by step

So my current site is running a stock mephisto instance (Rev:2812).

Note: This plugin has only really been tested with Rails 1.2.x but there are changes in trunk (.e.g multiple controller view paths) that will simplify this plugin a bit but I haven’t got round to testing it with trunk yet.

Let’s go…

We start off by installing Globalize release for-1.2

Installing the Globalize plugin

Open up a shell and type:


$script/plugin install -x http://svn.globalize-rails.org/svn/globalize/branches/for-1.2
A    /home/saimon/dev/projects/saimonmoore.net/vendor/plugins/for-1.2/test
A    /home/saimon/dev/projects/saimonmoore.net/vendor/plugins/for-1.2/test/unit
A    /home/saimon/dev/projects/saimonmoore.net/vendor/plugins/for-1.2/test/view_picking_test.rb
A    /home/saimon/dev/projects/saimonmoore.net/vendor/plugins/for-1.2/test/render_test.rb
...
Obtained revision: 91
(in /home/saimon/dev/projects/saimonmoore.net)
Globalize has not been setup yet. Generate a migration via script/generate globalize or run rake globalize:setup

Note that the globalize install has detected that the globalize project files haven’t been installed yet and suggests a couple of ways for you to get them in your db.

Before we setup the globalize tables I’m just going to rename the plugin to globalize as it was saved as for-1.2


$svn pe svn:externals vendor/plugins/
globalize http://svn.globalize-rails.org/svn/globalize/branches/for-1.2
$svn up
Obtaining external item in 'vendor/plugins/globalize'
A    vendor/plugins/globalize/test
A    vendor/plugins/globalize/test/unit
...
$rm -fR vendor/plugins/for-1.2
$svn ci vendor/plugins

Let’s check that globalize was installed properly. We should see the globalize rake tasks:


$rake -T | grep globalize
rake globalize:create_tables              # Create Globalize database tables
rake globalize:drop_tables                # Drops Globalize database tables
rake globalize:load_locale_data           # Load locale data
rake globalize:purge_locale_data          # Purge locale data
rake globalize:reset                      # Reset the Globalize data
rake globalize:setup                      # Create Globalize database tables and load locale data
rake globalize:teardown                   # Remove all globalizedata
rake globalize:test                       # Run tests
rake globalize:upgrade_schema_to_1_dot_2  # Upgrade to Globalize 1.2 schema

Looking good…

So let’s create and populate the globalize tables:


$rake globalize:setup
(in /home/saimon/dev/projects/saimonmoore.net)
NOTICE:  CREATE TABLE crear una secuencia implÃcita `globalize_countries_id_seq` para la columna serial `globalize_countries.id`
NOTICE:  CREATE TABLE / PRIMARY KEY crear el Ãndice implÃcito `globalize_countries_pkey` para la tabla `globalize_countries`
NOTICE:  CREATE TABLE crear una secuencia implÃcita `globalize_translations_id_seq` para la columna serial `globalize_translations.id`
NOTICE:  CREATE TABLE / PRIMARY KEY crear el Ãndice implÃcito `globalize_translations_pkey` para la tabla `globalize_translations`
NOTICE:  CREATE TABLE crear una secuencia implÃcita `globalize_languages_id_seq` para la columna serial `globalize_languages.id`
NOTICE:  CREATE TABLE / PRIMARY KEY crear el Ãndice implÃcito `globalize_languages_pkey` para la tabla `globalize_languages`

I’m also going to update db/schema.rb:


$rake db:schema:dump

That’s globalize installed. On to the next step which is installing the mephisto_i18n plugin.

Installing the Mephisto_I18n plugin


$script/plugin install -x svn://rubyforge.org/var/svn/sidirodromos/plugins/mephisto_i18n/trunk
A    /home/saimon/dev/projects/saimonmoore.net/vendor/plugins/mephisto_i18n/test
A    /home/saimon/dev/projects/saimonmoore.net/vendor/plugins/mephisto_i18n/test/unit
A    /home/saimon/dev/projects/saimonmoore.net/vendor/plugins/mephisto_i18n/test/unit/asset_test.rb
...

The plugin install hook prints out the plugin’s INSTALL file for us so we can immediately see what the next steps are.

Before we continue let’s have a look at the rake tasks available to us:


$rake -T | grep 18
rake mephisto:i18n:bootstrap                      # Bootstrap translations / Bootstrap translations
rake mephisto:i18n:set_plugin_order               # Modify config.plugins order in environment.rb to add this plugin last
rake mephisto:i18n:ui:modify_mephisto_resources   # Modify mephisto resources as needed for i18n UI
rake mephisto:i18n:ui:rename_index_file           # Rename the public/index.html file
rake mephisto:i18n:ui:restore_index_file          # Restore the public/index.html file renamed by mephisto:i18n:ui:rename_index_file task
rake mephisto:i18n:ui:restore_mephisto_resources  # Restore the mephisto resources modified by mephisto:i18n:ui:modify_mephisto_resources task
rake mephisto:i18n:ui:setup                       # Setup resources for i18n plugin / Setup resources for i18n UI plugin
rake mephisto:i18n:ui:setup_subroots              # Create the subroots according to the currently supported locales
rake mephisto:i18n:ui:teardown                    # Undo changes caused by the mephisto::i18n:ui:setup task
rake mephisto:i18n:ui:teardown_subroots           # Remove the subroots created by mephisto:i18n:ui:setup_subroots task

As you can see there are quite a few tasks there to help out with the installation process.

Setting up your application for mephisto_i18n.

Well, we’ve already installed globalize and created it’s tables, so let’s continue the installation with the following step which is:

"Setup the plugin order in environment.rb".


$cat config/environment.rb | grep config.plugins
  # config.plugins= %W( exception_notification ssl_requirement )


$rake mephisto:i18n:set_plugin_order


$cat config/environment.rb | grep config.plugins
  config.plugins= %W(a_gems acts_as_paranoid acts_as_versioned attachment_fu dialog_helper filtered_column filtered_column_code_macro filtered_column_flickr_macro globalize labeled_form_helper liquid manage_fixtures mephisto mephisto_converters mocha permalink_fu request_routing simply_bdd simply_helpful white_list mephisto_i18n)

The “mephisto:i18n:set_plugin_order” task has modified the config/environment.rb file to ensure that the mephisto_i18n plugin is loaded after all the other plugins have loaded.

To do so it creates a list of the existing plugins in the plugins directory, sorts it and tags on the mephisto_i18n plugin at the end.

Don’t worry if you’ve already set the config.plugins option, the task will not delete your current plugin order, but rather check for the mephisto_i18n and tag it on at the end.

Warning: This task assumes you’re running mephisto trunk so it’s expecting the config.plugins property to be there (either commented or uncommented)

Next step according to the INSTALL document:

“Define your base locale and supported locales”

I want to support English, Spanish, Catalan and Greek in my blog, with English being the base locale.

So edit the config/environment.rb to look something like this:


$tail -n3 config/environment.rb
include Globalize
SupportedLocales.define(['gr-GR', 'es-ES', 'ca-ES'],'en-UK')

We’re now ready to globalize the mephisto tables which couldn’t be easier.

“Globalize the Mephisto tables”

Just run:


$script/runner 'Mephisto::Plugins::MephistoI18n.install'
./script/../config/../vendor/plugins/mephisto_i18n/lib/globalize/supported_locales.rb:291:in `setup': Language for code: gr-GR doesn't exist! Check globalize tables. (RuntimeError)    from ./script/../config/../vendor/plugins/mephisto_i18n/lib/globalize/supported_locales.rb:289:in `collect'
from ./script/../config/../vendor/plugins/mephisto_i18n/lib/globalize/supported_locales.rb:289:in `setup'
    from ./script/../config/../vendor/plugins/mephisto_i18n/lib/globalize/supported_locales.rb:68:in `initialize'
    from ./script/../config/../vendor/plugins/mephisto_i18n/lib/globalize/supported_locales.rb:44:in `new'
    from ./script/../config/../vendor/plugins/mephisto_i18n/lib/globalize/supported_locales.rb:44:in `define'
    from ./script/../config/../config/environment.rb:95
    from /usr/lib/ruby/site_ruby/1.8/rubygems/custom_require.rb:27:in `gem_original_require'
    from /usr/lib/ruby/site_ruby/1.8/rubygems/custom_require.rb:27:in `require'
    from /usr/lib/ruby/gems/1.8/gems/rails-1.2.2/lib/commands/runner.rb:39
    from /usr/lib/ruby/site_ruby/1.8/rubygems/custom_require.rb:27:in `gem_original_require'
    from /usr/lib/ruby/site_ruby/1.8/rubygems/custom_require.rb:27:in `require'
    from script/runner:3

Oops what happened there? Ah I see the problem. ‘gr’ is not a valid language code. The correct code is ‘el’ for greek. Quick fix and …


$tail -n3 config/environment.rb
include Globalize
SupportedLocales.define(['el-GR', 'es-ES', 'ca-ES'],'en-UK')


$script/runner 'Mephisto::Plugins::MephistoI18n.install'
Run 'script/runner -h' for help.

Hmm…. that didn’t work either. If you get this, this is just a typo in the INSTALL document which I’ve now corrected.

The correct command is:


$script/runner 'Mephisto::Plugins::I18n.install'
Adding globalize columns
-- add_column(:assets, "title_el", :string)
   -> 0.1035s
-- add_column(:contents, "title_el", :string)
   -> 0.0166s
-- add_column(:contents, "excerpt_el", :text)
   -> 0.0284s
-- add_column(:contents, "body_el", :text)
   -> 0.0164s
....

You can rollback these changes at any time via:


$script/runner 'Mephisto::Plugins::I18n.uninstall'
-- remove_column(:assets, "title_el")
   -> 0.3864s
-- remove_column(:contents, "title_el")
   -> 0.0209s
-- remove_column(:contents, "excerpt_el")
...

Let’s save these changes to the schema.rb file:


$rake db:schema:dump

Have a look at the db/schema.rb file to see the changes the plugin has made to the mephisto tables.

Finally, the last part of the installation has to do with setting up the different document roots for each of the virtual hosts (each representing one of the non-base locales).

“Setting up the Mephisto I18n resources”

Thankfully, another rake task sets this all up for us nicely:

I’m going to show you what changes the task makes by showing you before and after snapshots of certain directories:


$ls -la public/
total 33
drwxr-xr-x  8 saimon users  488 mar 19 13:26 .
drwxr-xr-x 15 saimon users  520 mar 19 16:19 ..
-rw-r--r--  1 saimon users  619 sep 11  2006 404.html
-rw-r--r--  1 saimon users  684 sep 11  2006 500.html
drwxr-xr-x  4 saimon users   96 mar 19 13:43 assets
-rwxr-xr-x  1 saimon users  479 dic 29  2005 dispatch.cgi
-rwxr-xr-x  1 saimon users  859 jun 14  2006 dispatch.fcgi
-rwxr-xr-x  1 saimon users  479 dic 29  2005 dispatch.rb
drwxr-xr-x  5 saimon users  120 nov  6 15:08 documents
-rw-r--r--  1 saimon users    0 dic 29  2005 favicon.ico
drwxr-xr-x  4 saimon users   96 oct 11 09:27 images
-rw-r--r--  1 saimon users 3325 nov  4 18:06 install.html
drwxr-xr-x  4 saimon users   96 oct 11 09:27 javascripts
-rw-r--r--  1 saimon users   99 dic 29  2005 robots.txt
-rw-r--r--  1 saimon users  631 nov  9 14:56 sitemap.txt
drwxr-xr-x  4 saimon users   96 oct 11 09:27 stylesheets
drwxr-xr-x  7 saimon users  296 mar 19 16:19 .svn


$rake mephisto:i18n:ui:setup


$ls -la public
total 33
drwxr-xr-x 11 saimon users  560 mar 19 16:54 .
drwxr-xr-x 15 saimon users  520 mar 19 16:19 ..
-rw-r--r--  1 saimon users  619 sep 11  2006 404.html
-rw-r--r--  1 saimon users  684 sep 11  2006 500.html
drwxr-xr-x  4 saimon users   96 mar 19 13:43 assets
drwxr-xr-x  2 saimon users  280 mar 19 16:54 ca
-rwxr-xr-x  1 saimon users  479 dic 29  2005 dispatch.cgi
-rwxr-xr-x  1 saimon users  859 jun 14  2006 dispatch.fcgi
-rwxr-xr-x  1 saimon users  479 dic 29  2005 dispatch.rb
drwxr-xr-x  5 saimon users  120 nov  6 15:08 documents
drwxr-xr-x  2 saimon users  280 mar 19 16:54 el
drwxr-xr-x  2 saimon users  280 mar 19 16:54 es
-rw-r--r--  1 saimon users    0 dic 29  2005 favicon.ico
drwxr-xr-x  4 saimon users   96 oct 11 09:27 images
-rw-r--r--  1 saimon users 3325 nov  4 18:06 install.html
drwxr-xr-x  4 saimon users   96 oct 11 09:27 javascripts
-rw-r--r--  1 saimon users   99 dic 29  2005 robots.txt
-rw-r--r--  1 saimon users  631 nov  9 14:56 sitemap.txt
drwxr-xr-x  4 saimon users   96 oct 11 09:27 stylesheets
drwxr-xr-x  7 saimon users  296 mar 19 16:19 .svn


$ls -la public/es/
total 1
drwxr-xr-x  2 saimon users 280 mar 19 16:54 .
drwxr-xr-x 11 saimon users 560 mar 19 16:54 ..
lrwxrwxrwx  1 saimon users  67 mar 19 16:54 404.html-> /home/saimon/dev/projects/saimonmoore.net/config/../public/404.html
lrwxrwxrwx  1 saimon users  67 mar 19 16:54 500.html-> /home/saimon/dev/projects/saimonmoore.net/config/../public/500.html
lrwxrwxrwx  1 saimon users  70 mar 19 16:54 favicon.ico-> /home/saimon/dev/projects/saimonmoore.net/config/../public/favicon.ico
lrwxrwxrwx  1 saimon users  65 mar 19 16:54 images-> /home/saimon/dev/projects/saimonmoore.net/config/../public/images
lrwxrwxrwx  1 saimon users  71 mar 19 16:54 install.html-> /home/saimon/dev/projects/saimonmoore.net/config/../public/install.html
lrwxrwxrwx  1 saimon users  70 mar 19 16:54 javascripts-> /home/saimon/dev/projects/saimonmoore.net/config/../public/javascripts
lrwxrwxrwx  1 saimon users  69 mar 19 16:54 robots.txt-> /home/saimon/dev/projects/saimonmoore.net/config/../public/robots.txt
lrwxrwxrwx  1 saimon users  70 mar 19 16:54 stylesheets-> /home/saimon/dev/projects/saimonmoore.net/config/../public/stylesheets


$ls -la app/views/layouts/
total 8
drwxr-xr-x  3 saimon users  192 mar 19 16:54 .
drwxr-xr-x 11 saimon users  320 mar 19 16:54 ..
-rw-r--r--  1 saimon users 3683 feb 19 14:52 application.original.rhtml
lrwxrwxrwx  1 saimon users  125 mar 19 16:54 application.rhtml-> /home/saimon/dev/projects/saimonmoore.net/config/../vendor/plugins/mephisto_i18n/tasks/../app/views/layouts/application.rhtml
-rw-r--r--  1 saimon users 1367 nov 22 16:07 simple.rhtml
drwxr-xr-x  7 saimon users  296 mar 19 16:19 .svn


$ls -la app/views
total 1
drwxr-xr-x 11 saimon users 320 mar 19 16:54 .
drwxr-xr-x 11 saimon users 272 mar 18 20:02 ..
drwxr-xr-x  3 saimon users 136 mar 18 20:02 account
drwxr-xr-x 19 saimon users 488 mar 18 20:07 admin
drwxr-xr-x  3 saimon users  72 mar 18 20:02 assets
drwxr-xr-x  3 saimon users  72 mar 18 20:02 comments
drwxr-xr-x  3 saimon users 168 mar 18 20:02 feed
lrwxrwxrwx  1 saimon users 104 mar 19 16:54 i18n-> /home/saimon/dev/projects/saimonmoore.net/config/../vendor/plugins/mephisto_i18n/tasks/../app/views/i18n
drwxr-xr-x  3 saimon users 192 mar 19 16:54 layouts
drwxr-xr-x  3 saimon users 168 mar 18 20:02 mephisto
drwxr-xr-x  7 saimon users 296 mar 19 16:19 .svn
drwxr-xr-x  3 saimon users 112 mar 18 20:02 user_mailer

As you can see it has made a few changes including:

Creating three extra subdirectories in RAILS_ROOT/public, one for each non-base locale (Remember the base locale’s doc root is just RAILS_ROOT/public) and symlinked in common files from RAILS_ROOT/public.

Overriding the admin layout template, symlinking it to one provided with the plugin. (The original is still there just in case)

Adding an extra folder ‘i18n’ to the views directory (symlinked). This is for a custom controller that takes care of switching the current locale in the admin interface.

If you decide that you didn’t really want to install this plugin in the first place and you want to rollback all these changes then just run:


rake mephisto:i18n:ui:teardown

This will return your original files and directories to their rightfull places.

“Modify the session domain”

Finally, the last step in the INCLUDE document advises us to modify the ession_domain option in ActionController::CgiRequest::DEFAULT_SESSION_OPTIONS so that when we switch between subdomains in the same session, the session doesn’t get lost.


$tail -n1 config/environments/development.rb
ActionController::CgiRequest::DEFAULT_SESSION_OPTIONS.update(:session_domain => '.saimonmoore.net')


$tail -n1 config/environments/production.rb
ActionController::CgiRequest::DEFAULT_SESSION_OPTIONS.update(:session_domain => '.saimonmoore.net')

Phew…that was quite a bit of work. Let’s see what this plugin has actually bought us.

The Final Result

We start up mongrel:


$ mongrel_rails start
 ** Starting Mongrel listening at 0.0.0.0:3000
 ** Starting Rails with development environment...
 ** Mongrel is serving static files.
 ** Rails loaded.
 ** Loading any Rails specific GemPlugins
 ** Signals ready.  TERM => stop.  USR2 => restart.  INT => stop (no restart).
 ** Rails signals registered.  HUP => reload (without restart).  It might not work well.
 ** Mongrel available at 0.0.0.0:3000
 ** Use CTRL-C to stop.

Let’s go to the administration interface of our globalized mephisto application.

Note: I’ve temporarily redirected the .saimonmoore.net domain to localhost for testing purposes.

I’ve made a wink presentation out of this next part as I think it’s the quickest way to see what exactly you can do.

Click here to see the presentation.

Next week, I’ll conclude this two-part series with the second part where I’ll be talking about the production deployment issues that arise with this plugin.

[Update] I’ve just detected a slight problem with the symlinking in the mephisto:i18n:ui:setup rake task. It creates absolute symlinks which isn’t very handy for deployment. I’ll be fixing this asap.

[Update] This is now fixed so you’ll want at least revision 26 of the plugin

[Update] Currently there is a requirement to install the ‘unicode’ gem. I’m working to remove this dependency from the plugin.

Ready to deploy? Read *Part 2

Announcing Capistrano Server Extensions

2007-03-15T19:13:00Z

Maybe you’ve heard of Capistrano a tool written by Jamis Buck in Ruby that helps you automate deployment to multiple servers. Mike Bailey wrote the deprec gem based on capistrano to automate setting up of ubuntu servers with Apache and MySQL.

I needed a slightly different setup (nginx & postgres). Read on for how to easily setup any combination of rails/mongrel/apache/nginx/mysql/postgres.

Maybe you’ve heard of Capistrano a tool written by Jamis Buck in Ruby that helps you automate deployment to multiple servers.

Capistrano & Deprec

This ‘gem’ of a gem is huge time saver. Believe me, anyone who has used it has surely reaped the benefits of


$ cap --apply-to .
$ cap setup
$ cap deploy
$ cap rollback
$ cap update_current
$ cap watch_load
$ cap uptime
$ cap disable/enable_web
$ cap some_long_complex_task_that_would_normally_take_more_than_a_couple_of_hours_if_done_manually

etc....

This beauty is such a versatile beast (pun intended) that you can easily automate tasks for a range of use cases (app deployment, system administration, backups, profiling, benchmarking etc etc)

And many people have gone ahead and extended capistrano to do their bidding with evermore complex tasks.

One such person is Mike Bailey who was obviously really pissed off at having to setup the same old software on every new VPS he was configuring for his clients. (Please note that this is pure speculation and the real reason may in fact be very different). In any case, he decided to remedy the situation and wrote the deprec gem.

What does deprec do?

It basically augments capistrano to allow you to do things like:


$ cap setup_ssh_keys   # copy out your public keys
$ cap install_rails_stack # install apache, ruby & rubygems, mongrel, rails on the hosts defined in your capistrano recipe etc.
$ deprec --apply-to . --name bailey --domain bailey.net.au
$ cap deprec_setup #setup your application to allow easy server setups
$ cap deploy_with_migrations #deploy your application
$ cap restart_mongrel_cluster #start app server
$ cap restart_apache #start web server

i.e with this gem you can very easily setup a brand new VPS with a full rails stack including the MySQL database and Apache 2 web server.

Customizing Deprec

When I first discovered deprec, I immediately realised that this was going to be saving me a lot of time when setting up our own clients VPS’, but I wasn’t really enamoured of the choices of web server or database. Furthermore I wanted to be able to select the right tools for the job. For one client I may use MySQL but for another I’d use postgres (Well actually I prefer using postgres always but maybe you’d like to do that :).

My current preference for a rails stack is the following very lightweight setup:

Nginx => Mongrel => Rails => Postgres

So as we had a couple of small new clients whose servers needed setting up I spent a couple of days and wrote my own extensions to deprec that added support for nginx (see this for details) and PostgreSQL. I also added a few other bits and pieces that allowed me to do things that I like to do with every new VPS I setup.

Exploring Capistrano Server Extensions

So first off we install the Capistrano Server Extensions gem (very lame name I know) via:


sudo gem install -y capserverext

That’ll bring down all required dependencies including capistrano and deprec if you don’t already have them.

Side Note

I’m unashamedly assuming I’m talking to a Ruby crowd and that you have at least ruby 1.8.4 installed but let me say one thing to the other crowds out there:

“Get ruby installed and try this out”

It doesn’t matter whether your setting up LAMP servers, or j2ee servers, this stuff kicks real ass and will save the day for you on many occasions, seriously. (I’m a converted java programmer myself so I know this would come in really handily for setting up something like the jdk, Tomcat/Jetty/Resin, JBoss/Geronimo)

Heck we could even spiff it up to install Oracle. Now that’s a great idea. Imagine being able to preselect a type of Oracle setup and just typing: $ cap install oracle_cluster and go away for a cuppa.

Anyway I’m diverging a lot I know…sorry.

So once capserverext has been installed your first action is to


$ cap show_tasks

Which will show you a bewildering list of possible tasks to perform.

From this list you can pick and choose, mix and match different tasks for every occasion.

But let’s run through what you’d need to do to get a rails stack setup with nginx and postgres (currently only on a Ubuntu server but I’m working on supporting debian and Gentoo).

First let’s ask capistrano to tell us what we should do to use this thing. Type:


$ cap capserverext_usage
 * executing task capserverext_usage
      * rails myproject
      * cd /path/to/myproject
      * deprec --apply-to . --name user --domain myprojectsdomain.com
      * Add following entries to deploy.rb:
          require 'capserverext/recipes'
          require 'capistrano/ext/monitor'

      * Edit deploy.rb appropriately:
        * set deprec_combination to either (:nginx_postgres, :nginx_mysql, :apache_mysql, :apache_postgres)
          for a combination other than the default: ':nginx_postgres'
        * set ssh_security_port for an ssh port other than the default 22 (Defaults to: '8888')
        * set mongrel options (best to accept the defaults)
        * set repository
        * any other custom options

      * run: "cap prepare_ssh" 
      * set ssh_options[:port] to the value of ssh_security_port in deploy.rb
      * run: "cap prepare_host"

Using Capistrano Server Extensions

Thanks, that was handy. Now let me type the following:

On my local machine:


$ cd ~/dev/freelance
$ rails amicmuseuprecolombi.org   #A domain for one of my apps
$ cd amicsmuseuprecolombi.org
$ deprec --apply-to . --name saimon --domain amicsmuseuprecolombi.org

This’ll create a deploy.rb capistrano recipe for us in ./config/deploy.rb.

Quickly edit it to add:


  require 'capserverext/recipes'
  set :deprec_combination, :nginx_postgres
  set :repository, "http://www.webtypes.com/svn/projects/#{application}/trunk" 

  set :mongrel_servers, nginx_proxy_servers
  set :mongrel_port, nginx_proxy_port
  set :mongrel_address, nginx_proxy_address

Now type:


  $ cap prepare_ssh

And set the secure_ssh_port in deploy.rb to 8888 like so:


set ssh_options[:port], 8888

Now finally type:


  $ cap prepare_host

When that’s done type:


  $ cap deploy_with_migrations
  $ cap restart_mongrel_cluster
  $ cap restart_nginx

That takes about a total of 10 minutes from start to finish!

And visit http://amicsmuseuprecolombi.org (Our latest creation based on a globalized version of Mephisto) to see the result of having typed in those few commands. Well we also wrote the code for the site but you get the gist :)

Yep that’s all it takes to get a lean rails stack setup on your server .

Variations on the same theme

“I haven’t heard of nginx before. Can’t I use Apache?” someone says.

No problem. Set:


  set :deprec_combination, :apache_postgres

  $ cap prepare_host

“I prefer MySQL.” another says.

No problem. Set:


  set :deprec_combination, :nginx_mysql

  $ cap prepare_host

“No I meant with Apache.” they say again.

No problem. Set:


  set :deprec_combination, :apache_mysql

  $ cap prepare_host

Under the cover

Some of you will be asking what do these commands do exactly and I’ll point those of you to the very readable source code of the capserverext gem and the deprec gem. (Capistrano code is also very readable but you don’t need to go that far.)

So what will capserverext do remotely:

The prepare_ssh task will:

Connect via root and set root’s password
Change ssh port for security reasons
Create a deployment user, add it to the ‘deploy’ group

The prepare_host task will:

Connect with the deployment user and copy over your local machines public ssh keys.
Reconnect without asking for passwords anymore (apart from the first time it uses sudo)
Give the deployment user sudo privileges.
enable the ubuntu ‘universe’ repository
Install requisites allowing compilation of other packages, ruby, subversion, openssl
Install the PostgreSQL database server (8.1)
Install rubygems
Install rails, mongrel, mongrel_cluster and builder
Install nginx
setup generic deployment paths
setup app specific deployment paths
Configure nginx for production
Configure postgres for production (Creates a new database according to the name given for the production environment in database.yml, a database user and gives access privileges to that user)

That’s it. And you can do this again and again, over and over, on any number of hosts.

The beauty of this is that many tasks are composed of other smaller tasks so you can execute a specific task without having to run the whole lot.

Say you want to just install and configure nginx:


$ cap install_nginx
$ cap setup_web_for_nginx

or just apache


$ cap install_apache
$ cap setup_web  (deprec task)

Conclusion

Let me conclude by saying that I hope this article has shown you the flexibility and usefullness that Capistrano can be put to and how easily you can now setup your VPS servers for most combinations of setup.

Of course there’ll be a lot of you that need to tweak things for their own purposes, just create a ~/.caprc file and customize away (That’s how I did it)

I’m going to continue working on this to add support for more linux distributions. Mac server users will have to wait until I decide to make the jump (It’ll inevitably come but I’m not sure when yet).

If you found this handy or useful please provide feedback and also let Mike Bailey know and then we can perhaps integrate this stuff into deprec (so you don’t need to be installing two separate gems).

Thanks for reading,

Saimon Moore

IE7. Finally an excuse to use IE7.js

2007-01-15T18:59:00Z

Before the launch of Internet Explorer 7(IE7), using the IE7 javascript library from genius Dean Edwards to make Internet Explorer 6(IE6) behave, just wasn’t a real option most of the time. It’s hard to motivate your client to accept that most of their visitors would have to wait a considerable amount of extra seconds before their page would look like it’s supposed to look

Since the release of IE7 (as a semi-automatic update of IE6), this has changed. Or at least it feels like it has.

Suddenly IE6 has become an old browser for which it no longer seems worthwhile to sacrifice new design possibilities. And even though there are still lots of people out there using IE6, they now do have an alternative which is almost harder not to install than to install.

So yes, somehow it feels right to let IE6 people wait a little longer and give them a less than optimal experience in 2007. Of course it helps when your client is using IE7.

Now, if only IE7.js made alpha transparent css background images possible…

Did you mean wetlips?

2006-06-02T09:11:00Z

The day this search suggestion disappears we will know we exist.

The day Googleâ„¢ will ask me ‘did you mean webtypes’ while doing my weekly search for wetlips, we will know we ruleâ€¦

Rake-completion script that handles namespaces

2006-03-31T16:03:00Z

Thanks to Nicholas Seckar for the rake-completion script.

It’s real time saver. But now that rake 0.7.0 has arrived it’s introduced namespaces which are very handy.

When I recently capped our latest app I added some custom recipes to the remote: namespace and added a couple of new namespaces as well.

Namespaces however broke rake-completion and I was getting a bit annoyed at that so I looked into it and here you have a version of rake-completion.rb which correctly handles rake namespaces.

Enjoy….

[Update] Lee Marlow has produced a new and improved version of this which is recommended over this.

Subversion post commit hook using basecamp api

2006-03-31T14:55:00Z

The Basecamp API was released last week.

We’ve created a subversion post-commit hook that posts nicely formatted messages to a specific category for all of our clients basecamp projects.

Continous communication

This way our clients are continuously informed about the project status and the added benefit is that it forces us to write decent, coherent and descriptive log messages.

Some conventions

svn/projects/client-name/project-name

We have our svn repository setup so that the first level is a reference to the client’s company and the second level is the name of the client’s project (svn/projects/client-name/project-name).

‘SCM Commits’ category exists in project

The script uses the path of the changed files to select the correct basecamp project and then posts to the ‘SCM Commits’ category if it exists for that project. It also only posts a message if the post was to the main trunk branch.

Use itâ€¦

Feel free to refactor, rewrite or otherwise modify the script. (Make sure to rename it to “post-commit” (no extension) before sticking it in your subversion repository’s ‘hooks’ directory.

Tip for textdrive users: Make sure the shebang line points to the actual path to the ruby executable and don’t use ”/usr/bin/env ruby” because when this is executed by the apache user the environment isn’t set.

2nd tip for textdrive users: Make sure all call to external system files have a full absolute path.