NGINX upload module with Paperclip (on Rails)


Over the Christmas holidays I started looking at integrating the nginx upload module into Bugle.

The nginx upload module has been around for a while, but I couldn’t find anything to explain exactly what went on with the params and the best way to integrate it with the Paperclip gem in Rails (which Bugle uses for all upload handling). As I worked with it I found a few caveats along the way.

Why bother?

Without the module, your Rails app will receive the raw uploaded data, parsing its entire contents before it can be used. For large uploads this can be quite slow, since Ruby is the work horse throughout.

With this module, parsing the file happens in C through nginx and before your Ruby application gets it. The module puts the parsed file into a tmp directory and strips all the multipart params out of the POST body, replacing it with params you can use (in Rails) to get the name and location of the file on disk. So by the time the request hits your application, all the expensive parsing has been done and the file is ready to be used by your app. Basically hard work is moved from Ruby to C.

Compiling Nginx to include the module

To install the module you need to build nginx from source and pass it the upload module source directory as an argument. Since I run Bugle on a live production machine I wanted to work with things locally first. I began by setting up my local (OSX) box to match the production stack. I currently use nginx with Passenger and Ruby Enterprise Edition.

First download and untar both the nginx and upload module sources. Then build using the following commands (these worked on both OSX and my Ubuntu production server)

sudo /opt/ruby-enterprise-1.8.7-20090928/bin/passenger-install-nginx-module --nginx-source-dir=<path to nginx sources> --extra-configure-flags=--add-module='<path to upload module sources>'

Or if you’re just building nginx from source (without using the handy passenger installer) go with this;

cd <path to nginx sources>
./configure --add-module=<path to upload module sources>
make install

Don’t worry about any existing nginx.conf files you have or nginx vhosts etc. They will be unaffected after recompiling.

Configuring Nginx

The next step is to configure nginx to use the module. In Bugle uploads are normally sent via a POST request to the uploads controller using a restful URL that can be one of;

POST /admin/blogs/:blog_id/uploads
POST /admin/themes/:theme_id/uploads

These hit the ‘uploads’ controller, ‘create’ action. I wanted to keep the same restful URLs so I tried the following regex in the nginx config.

location ~* admin\/(themes|blogs)\/([0-9]+)\/uploads { }

While this did work in recognising the URL, the upload module wouldn’t work with it. In the end I opted to use a new defined url for faster uploads, here is the route for it in Rails. You may have a simpler upload URL controller action making this unnecessary.

map.connect 'admin/uploads/fast_upload', :controller => 'admin/uploads', 
                                        :action     => 'create', 
                                        :conditions => { :method => :post }

So the modified nginx server config becomes;

server {
 listen   80;
 server_name *;
 # ...
 # somewhere inside your server block
 # ...
 # Match this location for the upload module
 location /admin/uploads/fast_upload {
   # pass request body to here
   upload_pass @fast_upload_endpoint;

   # Store files to this directory
   # The directory is hashed, subdirectories 0 1 2 3 4 5 6 7 8 9 should exist    
   # i.e. make sure to create /u/apps/bugle/shared/uploads_tmp/0 /u/apps/bugle/shared/uploads_tmp/1 etc.
   upload_store /u/apps/bugle/shared/uploads_tmp 1;

   # set permissions on the uploaded files
   upload_store_access user:rw group:rw all:r;

   # Set specified fields in request body
   # this puts the original filename, new path+filename and content type in the requests params
   upload_set_form_field upload[fast_asset][original_name] "$upload_file_name";
   upload_set_form_field upload[fast_asset][content_type] "$upload_content_type";
   upload_set_form_field upload[fast_asset][filepath] "$upload_tmp_path";

   upload_pass_form_field "^theme_id$|^blog_id$|^authenticity_token$|^format$";
   upload_cleanup 400 404 499 500-505;
 location @fast_upload_endpoint {
   passenger_enabled on;  # or this could be your mongrel/thin backend
  • After processing, the upload module puts the file in one of 10 tmp directories, these should be already created and accessible by your Rails app, since I am using Capistrano, I’ve chosen the shared/ folder to house the tmp files (you’d risk loosing a file mid-deploy if you chose somewhere in the RAILS_APP current/ directory)
  • The upload_pass_form_field directive preserves any params that match the regex (we don’t want the module to strip the following params: format, blog_id, theme_id or authenticity_token)
  • The upload_pass directive sets what should handle the request after the upload module has finished with the file (we want to handle it using Rails, through passenger, so a @fast_upload_endpoint location is defined)
  • The upload_set_form_field directives are used to specify the params that Rails will now receive, this will give;
    • params[‘upload’][‘fast_asset’][‘original_name’]
    • params[‘upload’][‘fast_asset’][‘content_type’]
    • params[‘upload’][‘fast_asset’][‘filepath’]

At this point its worth testing the app. Perform an upload and check that nginx is sending these params to your controller action. For more info here is a complete guide to all the module directives.

Working with Paperclip and Rails

Finally I needed to modify Rails to make use of these new params. In Bugle the upload module has_attached_file :asset using Paperclip. One problem is that new file in the tmp/ directory exists with a hashed meaningless filename, so simply passing this file to self.asset will not work for Paperclip processing. It needs to have the original filename and content_type. Fortunately we have those in the new params too. So the new fast_asset= method shifts and renames the file into a sub tmp directory (which gets cleaned on the after_create filter). All this seems a little convoluted, but I couldn’t see any other way to do this, without perhaps modifying the Paperclip internals. If anyone has any suggestions around this let me know in the comments.

class Upload < ActiveRecord::Base
  has_attached_file :asset, :styles => {:thumb => ["64x64#", :jpg]},
                            :url    => ":base_url/:resource/:styles_folder:basename:style_filename.:extension",
                            :path   => "public/u/:resource/:styles_folder:basename:style_filename.:extension" 
  attr_accessor :tmp_upload_dir
  after_create  :clean_tmp_upload_dir
  # handle new param
  def fast_asset=(file)
    if file && file.respond_to?('[]')
      self.tmp_upload_dir = "#{file['filepath']}_1"
      tmp_file_path = "#{self.tmp_upload_dir}/#{file['original_name']}"
      FileUtils.mkdir_p(self.tmp_upload_dir)['filepath'], tmp_file_path)
      self.asset =
  # clean tmp directory used in handling new param
  def clean_tmp_upload_dir
    FileUtils.rm_r(tmp_upload_dir) if self.tmp_upload_dir &&

For completeness here is the regular controller action;

def create
  # ...
  @upload =[:upload])
  # ...

Go Go Uploads!

Thats it, you should now have much faster uploads through nginx! To see the improvement try uploading a 50Mb+ file with/without the module. In a future series of posts I will be conducting a complete walkthrough of the uploader I have built for Bugle. End to end from the browser, to Rails and the actual server configuration.

Related Links

19 comments so far

  • photo of Ladislav Martincik Ladislav Martincik Jan 07, 2010

    Very nice! I like it.

  • photo of Patrick Patrick Feb 11, 2010

    Cool tip. Will try this out… but why exactly is the upload not working though when you try location ~* ??? why would the url matter?

  • photo of matt matt Feb 11, 2010

    Patrick, no idea why it wouldn’t work. The location regex did match OK (I tested that on its own) but when uploading the file through it, the module simply didn’t run. Or didn’t appear to do anything. Meaning I had the same old regular params for parsing the file, rather than the params to the fast file handle from the module.

    I got no error messages or notices in the logs either.

  • photo of Anthony Anthony Feb 23, 2010

    I got an undefined method ‘data’ when trying this out. I think where you have

    self.tmp_upload_dir = “#{data[‘filepath’]}_1”

    it should be

    self.tmp_upload_dir = “#{file[‘filepath’]}_1”

    The other references to “data” should also be switched to “file”

  • photo of Matt Matt Feb 23, 2010

    Yep, your right, sorry was a typo on my behalf – I’ve updated the code above now.

  • photo of Valery Valery Apr 02, 2010

    Great article. Thanks. Upload module rules!

  • photo of pavel k pavel k Apr 13, 2010

    hm, why all the file manipulation:

    def fast_asset=(file)

    if file && file.respond_to?(‘[]’)

    self.tmp_upload_dir = “#{file[‘filepath’]}_1”

    tmp_file_path = “#{self.tmp_upload_dir}/#{file[‘original_name’]}”

    FileUtils.mkdir_p(self.tmp_upload_dir)[‘filepath’], tmp_file_path)

    self.asset =


    end </pre>

    instead of

    def fast_asset=(file)

    if file && file.respond_to?(‘[]’)

    self.asset =[‘filepath’])

    self.asset_content_type = file[‘content_type’]

    self.asset_file_name = file[‘original_name’]



    p.s. huge thanks for the article

  • photo of Guilherme Guilherme Apr 29, 2010

    Hi Matt,

    The project on github is not online, there is other repository that i could check your implementation?

    Thank you!

    Great article :)

  • photo of Matt Matt Apr 29, 2010

    Guilherme, Sorry – I’ve still not had time to do a series of posts on this or create an example project on gitHub. I will do soon, within the next month or so.

  • photo of Grant Grant May 18, 2010

    I think I’m missing something. Where is the fast_asset method actually called?

Leave a comment