This site provides the following access keys:

Brandan Lennox's

Extremely Large File Uploads with nginx, Passenger, Rails, and jQuery

We have to handle some really frackin’ huge uploads (approaching 2 TB) in our Rails-Passenger-nginx application at work. This results in some interesting requirements:

  1. Murphy’s Law guarantees that uploads this big will get interrupted, so we need to support resumable uploads.
  2. Even if the upload doesn’t get interrupted, we have to report progress to the user since it’s such a long feedback cycle.
  3. Luckily, we can restrict the browsers we support, so we can use some of the advanced W3C APIs (like File) and avoid Flash.
  4. Only one partition in our appliance is large enough to contain a file that size, and it’s not /tmp.

For the first three requirements, it seemed like the jQuery File Upload plugin was a perfect fit. For the last, we just needed to tweak Passenger to change the temporary location of uploaded files…

Many Googles later, I realized that option is only supported in Apache and my best bet was the third-party nginx upload module. But its documentation is fairly sparse, and getting it to work with the jQuery plugin was a lot more work than I anticipated.

Below is my solution.

nginx and the Upload Module

The first step was recompiling nginx with the upload module. In our case, this meant modifying an RPM spec and rebuilding it, but in general, you just need to extract the upload module’s tarball to your filesystem and reference it in the ./configure command when building nginx:

./configure --add-module=/path/to/nginx_upload_module ...

Once that was built and installed, I added the following section to our nginx.conf:

# See
location = /upload-restore-archive {

  # if resumable uploads are on, then the $upload_field_name variable
  # won't be set because the Content-Type isn't (and isn't allowed to be)
  # multipart/form-data, which is where the field name would normally be
  # defined, so this *must* correspond to the field name in the Rails view
  set $upload_field_name "archive";

  # location to forward to once the upload completes
  upload_pass /backups/archives/restore.json;

  # filesystem location where we store uploads
  # The second argument is the level of "hashing" that nginx will perform
  # on the filenames before storing them to the filesystem. I can't find
  # any documentation online, so as an example, say we were using this
  # configuration:
  #   upload_store /tmp/uploads 2 1;
  # A file named '43829042' would be written to this path:
  #   /tmp/uploads/42/0/43829042
  # I hope that's clear enough. The argument is required and must be
  # greater than 0. You can see the implementation here:
  upload_store /backup/upload 1;

  # whether uploads are resumable
  upload_resumable on;

  # access mode for storing uploads
  upload_store_access user:r;

  # maximum upload size (0 for unlimited)
  upload_max_file_size 0;

  # form fields to be passed to Rails
  upload_set_form_field $upload_field_name[filename] "$upload_file_name";
  upload_set_form_field $upload_field_name[path] "$upload_tmp_path";
  upload_set_form_field $upload_field_name[content_type] "$upload_content_type";
  upload_aggregate_form_field $upload_field_name[size] "$upload_file_size";

  # hashes are not supported for resumable uploads
  #upload_aggregate_form_field $upload_field_name[signature] "$upload_file_sha1";

That’s a literal copy-and-paste from the config. I’m including the comments here because the documentation wasn’t as explicit as I apparently needed it to be.

Some important points:

  • Valery Kholodkov, the author of the upload module, has written a protocol defining how resumable uploads work. You should definitely read it and understand the Content-Range and Session-Id headers.
  • I can’t find any documentation on “nginx directory hashes”. That comment is the best I could do to explain it.
  • Once the upload is completely finished, the module sends a request to a given URL with a given set of parameters. That’s what upload_set_form_field and upload_aggregate_form_field are for, so you can make the request look like a multipart form submission to your application.
  • The module supports automatic calculation of a SHA1 (or MD5) hash of uploaded files, presumably implemented as a filter during the upload to save time. I would’ve liked to have that hash passed to Rails for verification of the file, but it’s unsupported for resumable uploads. I’m leaving that setting commented out for future developers’ sakes.

At this point, I was able to use curl to upload files and observe what was happening on the filesystem. The next step was configuring the jQuery plugin.

The jQuery File Upload Plugin

This plugin is extremely full-featured and comprehensively documented, which was exactly the problem I had with it. I needed something in between the basic example and the kitchen sink example, and the docs were spread over a series of wiki pages that I personally had trouble following. A curse of plenty.

Here’s the essence of what I came up with (in CoffeeScript):

# We need a simple hashing function to turn the filename into a
# numeric value for the nginx session ID. See:
hash = (s, tableSize) ->
  b = 27183
  h = 0
  a = 31415

  for i in [0...s.length]
    h = (a * h + s[i].charCodeAt()) % tableSize
    a = ((a % tableSize) * (b % tableSize)) % (tableSize)

sessionId = (filename) ->
  hash(filename, 16384)


  # nginx's upload module responds to these requests with a simple
  # byte range value (like "0-2097152/3892384590"), so we shouldn't
  # try to parse that response as the default JSON dataType
  dataType: 'text',

  # upload 8 MB at a time
  maxChunkSize: 8 * 1024 * 1024,

  # very importantly, the nginx upload module *does not allow*
  # resumable uploads for a Content-Type of "multipart/form-data"
  multipart: false,

  # add the Session-Id header to the request when the user adds the
  # file and we know its filename
  add: (e, data) ->
    data.headers or= {}
    data.headers['Session-Id'] = sessionId(data.files[0].name)

  # update the progress bar on the page during upload
  progress: (e, data) ->

Unlike the nginx config above, this example leaves out a lot of application-specific settings that aren’t relevant to getting the plugin to work with nginx.

Some important points:

  • I decided to use a simple JavaScript hashing function to hash the filename for the Session-Id. It might not need to be numeric, but all the nginx examples I read used numeric filenames, and the Session-Id is used directly by nginx as the filename on disk.
  • As noted in the comment, the response to an individual upload request is a plain-text byte range, which is also present in the Content-Range header. The plugin uses this value to determine the next chunk of the file to upload.
  • This means that in order to resume an upload, the first chunk of the file must be re-uploaded. Then nginx responds with the last successful byte range, and the plugin will start from there on the next request. This can be momentarily disconcerting, since it looks like the upload has started over. Set your chunk size accordingly.
  • You must set multipart: false for resumable uploads to work. I missed that note in the protocol, and I wasted a lot of time trying to figure out why my uploads weren’t resuming.

At this point, I could interrupt an upload, resume it by simply uploading the same file again, and I had a lovely progress bar to boot. The last step was making sure Rails worked.


All the hard work has been done by the time Rails even realizes somebody’s uploading something. The controller action looks exactly like you’d expect it to:

class ArchivesController < ApplicationController
  def restore
    archive =[:archive])

    if archive.valid? && archive.perform!
      render json: { errors: archive.errors.full_messages }, status: :error

The view suffers a bit, since the jQuery plugin wants to own the form and nginx has its configuration hard-coded:

<!-- The fileupload plugin takes care of all the normal form options -->
  <input id="restore-archive" type="file" data-url="/upload-restore-archive">
  <%= button_tag 'Upload and Restore', id: 'restore-upload-button', type: 'button' %>

That’s about it.


It was pretty sweet once it worked, but the journey was arduous. Hope this helps some people.