Predoc

Predoc is a Ruby on Rails web service for in-browser document previews. It converts supported documents — Microsoft Word, Excel, and PowerPoint — into PDFs for web browsers to display.

Installation

Dependencies

Predoc uses LibreOffice (via Docsplit) to convert documents. Install LibreOffice on the web server using aptitude, apt-get, or yum:

$ aptitude install libreoffice

Configuration

You need to specify the paths for Predoc to create temporary and cache files. Create predoc.rb from the template file config/initializers/predoc.rb.default at the same location, and modify these variables:

• WORKING_DIRECTORY is where temporary files are downloaded and stored.
• CACHE_ROOT_DIRECTORY is where converted files are cached.

Make sure these directories are writable by the web server.

In addition, you can configure the maximum number of seconds allowed for a single conversion by changing CONVERSION_TIMEOUT.

Conversion Statistics

If you use StatsD to keep track of statistics, you can enable it by setting STATSD_HOST. Also configure STATSD_PORT and STATSD_NAMESPACE as needed. The application will increment one or more of the following stats related to requests for preview:

• General
  • request — when a preview is requested
  • convert — when a conversion process begins
  • converted — when a conversion process ends (sent as duration in milliseconds)
• Preview request successful
  • sent.cached — when a cached preview is available and sent
  • sent.passthru — when a PDF source file is sent directly without conversion
  • sent.converted — when a document is converted and sent
• Error handled internally
  • rescue.inconvertible — when an error occurred during a conversion process
  • rescue.timeout — when a conversion took too long and is aborted
• Preview request failed
  • error.unreadable — when a source file is not found or cannot be read
  • error.unsupported — when a source file type is not supported
  • error.incomplete — when a conversion yielded nothing due to some errors

Deployment

You can use Capistrano to deploy Predoc. Create deploy.rb from the template file config/deploy.rb.example at the same location. Customize settings as needed. You have the option to deploy to multiple stages (e.g. staging, production, etc.) In that case, you'll need to create config/deploy/{stage_name}.rb as well.

In production, the application expects the environment variable SECRET_KEY_BASE to be set. Generate one using rake secret, then export the output within a shell configuration script like .bashrc or .profile for the user running the application.

Usage

To create a preview, point your web browser to the web service:

http://example.com/viewer?url=http://path/to/document

Note: Replace example.com with the server hostname, and http://path/to/document with an actual web-hosted document

Health Check

The application status page is located at http://example.com/status. Use /status.json to get the output in JSON.

Testing

To run unit tests, first create test.rb from the template file config/test.rb.default at the same location. Change the URL values in FIXTURE_URLS to real web-hosted test documents (not provided). Run this command to start the test:

ruby -Itest test/functional/documents_controller_test.rb