Filepicker.io Heroku addon instructions

docs

[Filepicker.io](http://addons.heroku.com/filepicker) provides file uploading and content management for developers as an [add-on](http://addons.heroku.com) for Heroku.

Filepicker.io 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, Filepicker.io provides:
 * Integration with 17 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

Filepicker.io is accessible via our filepicker.js API as well as SDKs for iOS and Android. Additionally, there are supported framework libraries for [[Rails,Django,Phonegap,Meteor]]* and client libraries for [[Ruby,Python,Node.js,PHP]]*

## Provisioning the add-on

Filepicker.io can be attached to a Heroku application via the CLI:

<div class="callout" markdown="1">
A list of all plans available can be found [here](http://addons.heroku.com/filepicker.io).
</div>

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

Once Filepicker.io has been added, two additional config variables will be set up:
 * `FILEPICKER_APP_KEY`: Your Filepicker.io api key, used to perform uploads and other actions against the Filepicker.io API.
 * `FILEPICKER_APP_SECRET`: Your Filepicker.io secret key, used for signing policies as part of the Filepicker.io security scheme.

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

    :::term
    $ heroku config:get FILEPICKER_API_KEY
    KJsdf8KSDFjksdf
    $ heroku config:get FILEPICKER_API_SECRET
    ZXJM897LJ9752de

After installing Filepicker.io your application should be good-to-go to start utilizing the capabilities of Filepicker.io

## 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 Filepicker.io

<div class="callout" markdown="1">
Though less portable it’s also possible to set local environment variables using `export ADDON_CONFIG_NAME=value`.
</div>

Use [Foreman](config-vars#local_setup) to reliably configure and run the process formation specified in your app’s [Procfile](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 ADDON_CONFIG_NAME >> .env
$ more .env

<p class="warning" markdown="1">
Credentials and other sensitive configuration values (like your Filepicker.io credentials!) should not be committed to source-control. In Git exclude the .env file with: `echo .env >> .gitignore`.
</p>

## Using with Rails 3.x

Ruby on Rails applications will need to add the following entry into their `Gemfile` specifying the ADDON_NAME client library.

    :::ruby
    gem 'filepicker-rails'

Update application dependencies with bundler.

    :::term
    $ bundle install

In config/application.rb, set

    :::ruby
    config-filepicker_rails.api_key = ENV['FILEPICKER_API_KEY']

### Deploy changes

Deploy the Filepicker.io configuration to Heroku:

    :::term
    $ git add config/filepicker-rails.rb
    $ git commit -a -m "Adding filepicker-rails config"
    $ git push heroku master
    …
    -----> Heroku receiving push
    -----> Launching... done, v3
           http://warm-frost-1289.herokuapp.com deployed to Heroku

    To git@heroku.com:warm-frost-1289.git
     * [new branch]      master -> master

### Integrate the Javascript library into your layout

For all the pages where you want to integrate filepicker.io functoinality, add the following code to your layout:

    :::ruby
    <%= filepicker_js_include_tag %>

### Adding an upload field to your form

One of the most common uses of Filepicker.io is 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

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

      <%= 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.io image process capabilities like so:

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

## Dashboard

<div class="callout" markdown="1">
For more information on the features available within the Filepicker.io dashboard please see the docs at [filepicker.io/web/docs](developers.filepicker.io/web/docs/).
</div>

The Filepicker.io 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:

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

or by visiting the [Heroku apps web interface](http://heroku.com/myapps) and selecting the application in question. Select Filepicker.io from the Add-ons menu.

## Removing the add-on

Filepicker.io can be removed via the  CLI.

<div class="warning" markdown="1">This will destroy all associated data and cannot be undone!</div>

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

Before removing Filepicker.io a data export can be performed by visiting your developer console and exporting any uploaded files. Contact [contact@filepicker.io](mailto:contact@filepicker.io) for assistance.

## Support

All Filepicker.io support and runtime issues should be submitted via on of the [Heroku Support channels](support-channels). Any non-support related issues or product feedback is welcome at [Stack Overflow](http://stackoverflow.com/questions/tagged/filepicker.io) via the filepicker tag or via email at [contact@filepicker.io](mailto:contact@filepicker.io)

## Additional resources

Additional resources are available at:

* [Filepicker.io Documentation](https://developers.filepicker.io/docs/)
* [Sample code and Demos](https://www.filepicker.io/demos/)