Upload Progress

The Webiva upload progress capability is based on the apache-upload-progress- module.

---

---

Prerequisites

If you installed Webiva directly from our Installation Documentation then you’re using Apache and Passenger. This tutorial is written with the assumption that you are and the hope that if you’re slick enough to set up Webiva in your own non-apache/passenger way then you’re slick enough to take what you need from this and fit it to suit you.

apxs2 is not installed on Ubuntu with the apache2-server. Its located in the development packages. You can find it by:

apt-cache search apxs2  

Currently the containing packages are named

apache2-prefork-dev - Apache development headers - non-threaded MPM
apache2-threaded-dev - Apache development headers - threaded MPM  

This should give you a list of all packages which contain the file. They will be apache packages, but are not pertinent to the running of Webiva so the choice in what to install is yours.

Download apache module

The module is available from github.com Choose your download method:

git clone git://github.com/drogus/apache-upload-progress-module.git  

or download the tarball

http://github.com/drogus/apache-upload-progress-module/tarball/master  

If you’re using the tarball, unpack it in a place of your choosing.

Compiling and installing the module

After you’ve got the file unpacked, cd into the directory:

$ cd apache-upload-progress-module

Now compile and install the module:

$  sudo apxs2 -cia mod_upload_progress.c 

The -i option will install the module into the default directory (/usr/lib/apache2/modules on debian). You may need to move it depending on you distribution. The -a option should activate the module.

If you need to activate it manually, you can add a LoadModule directive, on debian we can create a module file:

$ sudo vi /etc/apache2/mods-available/upload_progress.load

With the following single line:

LoadModule upload_progress_module /usr/lib/apache2/modules/mod_upload_progress.so

Now activate the module:

$ sudo a2enmod upload_progress

Next open up the Webiva virtual host and add the following lines:

<Location />
    # enable tracking uploads in /
    TrackUploads On
</Location>

<Location /website/file/progress>
    # enable upload progress reports in /website/file/progress
    ReportUploads On
</Location>

The first directive turns on upload progress for the root of your site tree.
The second directive will be the URL that will be requested from the progress indicator. ** Note ** If you are writing your own indicator, this can be changed to anything you prefer, but for Webiva’s file uploader, it must be as above

Now Restart apache:

 $ sudo apache2ctl restart

Use the Webiva progress indicator

Once you have the module installed and apache restarted, the progress indicator in the files section should appear while uploading. If not, please submit a bug and a stack trace/log entry.

Usage for writing your own

When a request is made to http://mysite.com/website/file/progress
the result is a JSON object. This object contains the events needed to show progress in your indicator.

The returned document is a JSON text with the possible 4 results:

* the upload request hasn’t been registered yet or is unknown:

new Object({ ‘state’ : ‘starting’ })

* the upload request has ended:

new Object({ ‘state’ : ‘done’ })

* the upload request generated an HTTP error:

new Object({ ‘state’ : ‘error’, ‘status’ : })

One error code that is interesting to track for clients is HTTP error 413 (Request entity too large)

* the upload request is in progress:

new Object({ ‘state’ : ‘uploading’, ‘received’ : , ‘size’ : })

The HTTP request to this location must have either an X-Progress-ID parameter or X-Progress-ID HTTP header containing the unique identifier as specified in your upload/POST request to the relevant tracked zone. If you are using the X- Progress-ID as a query-string parameter, ensure it is the LAST argument in the URL.

References

• Done in prototype: http://drogomir.com/files/blog/prototype-upload-progress
• github link: http://github.com/drogus/apache-upload-progress-module/
• Screencast howto: http://www.railsillustrated.com/screencast-file-uploads- progress-in-rails-passenger.html