This add-on is operated by Filepicker

Connect, Store and Process any file from anywhere on the Internet.


Last Updated: 07 May 2015

Table of Contents

The Ink file picker provides file uploading and content management for developers as an add-on for Heroku.

The Ink file picker excels any time you want to add uploading or cloud file integration into your application. Worried about running into the Heroku 30-second-timeout with big files? No worries, we can handle files upward of 100GB. Need to store them on S3? Done, no questions asked.

Even better, Ink provides:

  • Integration with 19 content providers, so your users can pull in content directly from the cloud, increasing their engagement in your application. No wrestling with APIs required - one line of code and your app is set up with Dropbox, Facebook Photos, Google Drive, Instagram, and many more.
  • Powerful image processing functionality, so you can take uploads from the user and crop them to a 128x128 profile pictured centered around their face, for example
  • Stellar performance, streaming large files in parallel at speeds 4-10 times faster than basic flash uploaders

The Ink file picker is accessible via our filepicker.js API as well as SDKs for iOS.

Provisioning the add-on

Ink can be attached to a Heroku application via the CLI:

A list of all plans available can be found here.

$ heroku addons:create filepicker
-----> Adding filepicker to sharp-mountain-4005... done, v18 (free)

Once the Ink file picker has been added, two additional config variables will be set up:

  • FILEPICKER_APP_KEY: Your Ink api key, used to perform uploads and other actions against the API.
  • FILEPICKER_APP_SECRET: Your Ink secret key, used for signing policies as part of the Ink file picker security scheme.

This can be confirmed using the heroku config:get command.

$ heroku config:get FILEPICKER_API_KEY
$ heroku config:get FILEPICKER_API_SECRET

After installing Ink your application should be good-to-go to start utilizing the capabilities of the Ink file picker

Local setup

Environment setup

After provisioning the add-on, you’ll want to copy the config vars to your local development environment so you can make the same calls using Ink

Though less portable it’s also possible to set local environment variables using export FILEPICKER_API_KEY=value.

Use Foreman to configure, run and manage process types specified in your app’s Procfile. Foreman reads configuration variables from an .env file. Use the following command to add the FILEPICKER_API_KEY and FILEPICKER_API_SECRET values retrieved from heroku config to .env.

$ heroku config -s | grep FILEPICKER >> .env
$ more .env

Credentials and other sensitive configuration values (like your Ink credentials!) should not be committed to source-control. In Git exclude the .env file with: echo .env >> .gitignore.

Using with Rails

Ruby on Rails applications will need to add the following entry into their Gemfile specifying the filepicker-rails client library.

gem 'filepicker-rails'

Update application dependencies with bundler.

$ bundle install

In config/application.rb, set

config.filepicker_rails.api_key = ENV['FILEPICKER_API_KEY']

Deploy changes

Deploy the filepicker configuration to Heroku:

$ git add .
$ git commit -a -m "Adding filepicker-rails config"
$ git push heroku master
-----> Heroku receiving push
-----> Launching... done, v3 deployed to Heroku

 * [new branch]      master -> master

Integrate the Javascript library into your layout

For all the pages where you want to integrate the Ink file picker functionality, add the following code to your layout:

<%= filepicker_js_include_tag %>

Adding an upload field to your form

One of the most common uses of the Ink file picker is to upload files to your application. The filepicker-rails gem simplifies this process, storing the file on S3 and attaching a url to your model for later retrieval

<%= form_for @user do |f| %>
    <%= f.label :avatar_url, "Upload Your Avatar:" %>
    <%= f.filepicker_field :avatar_url %> <!-- User#avatar_url is a regular string column -->

  <%= f.submit %>
<% end %>

Displaying the image

In the example above the user uploaded an image. If you then want to display that image in the page, cropped to 160x160 pixels, you can take advantage of the filepicker image process capabilities like so:

<%= filepicker_image_tag @user.avatar_url, w: 160, h: 160, fit: 'clip' %>


For more information on the features available within the Ink dashboard please see the docs at

The Ink dashboard allows you to add your S3 credentials and configure security, as well as monitor your usage and see how users are working with your application

The dashboard can be accessed via the CLI:

$ heroku addons:open filepicker
Opening filepicker for sharp-mountain-4005…

or by visiting the Heroku apps web interface and selecting the application in question. Select Ink file picker from the Add-ons menu.

Removing the add-on

The Ink file picker can be removed via the CLI.

This will destroy all associated data and cannot be undone!

$ heroku addons:destroy filepicker
-----> Removing filepicker from sharp-mountain-4005... done, v20 (free)

Before removing Ink a data export can be performed by visiting your developer console and exporting any uploaded files. Contact for assistance.


All Ink file picker support and runtime issues should be submitted via on of the Heroku Support channels. Any non-support related issues or product feedback is welcome at Stack Overflow via the ink-file-picker tag or via email at

Additional resources

Additional resources are available at: