This add-on is operated by Pirate Radio

Quick and easy access to S3


Last Updated: 07 May 2015

This article is a work in progress, or documents a feature that is not yet released to all users. This article is unlisted. Only those with the link can access it.

The Bucket add-on is currently in beta.

Table of Contents

This add-on has been deprecated.

Bucket is an add-on for providing Amazon S3 buckets.

Each bucket provided to an application will come with a unique set of credentials that has exclusive access to the assigned bucket.

Provisioning the add-on

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

A list of all plans available can be found here.

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

Once Bucket has been added, the config vars BUCKET_ACCESS_KEY, BUCKET_SECRET_KEY, and BUCKET_NAME will be available in the app configuration and will contain the credentials needed to access the specified bucket.

This can be confirmed with the heroku config command:

$ heroku config | grep BUCKET
BUCKET_NAME: bucket-identiier

After installing Bucket the application should be configured to fully integrate with the add-on.

Local setup

Environment setup

After provisioning the add-on it’s necessary to locally replicate the config vars so your development environment can operate against the service.

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 ADDON_CONFIG_NAME values retrieved from heroku config to .env.

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

Credentials and other sensitive configuration values should not be committed to source-control. In Git exclude the .env file with: echo .env >> .gitignore.

Using Bucket in Node.js

You can use the awssum library for Node.js to connect to S3.

var S3 = require("awssum").load("amazon/s3").S3;

var storage = new S3({
  accessKeyId:     process.env.BUCKET_ACCESS_KEY,
  secretAccessKey: process.env.BUCKET_SECRET_KEY

  BucketName:    process.env.BUCKET_NAME,
  ObjectName:    'helloworld.txt',
  ContentLength: 14,
  Body:          'Hello World!\n'
}, function(err, data) {
  console.log('err', err);
  console.log('data', data);

Using Bucket from Python

You can use the boto library for Python to connect to S3.

from boto.s3.connection import S3Connection
from boto.s3.key import Key

aws = S3Connection(os.environ.get('BUCKET_ACCESS_KEY'), os.environ.get('BUCKET_SECRET_KEY'))

file = Key(aws.get_bucket(os.environ.get('BUCKET_NAME'))
file.key = 'helloworld.txt'
file.set_contents_from_string('Hello World!\n')

Using Bucket from Ruby

You can use the fog library for Ruby to connect to S3.

require "fog"

s3 = Fog::Storage.new({
  :provider              => "AWS",
  :aws_access_key_id     => ENV["BUCKET_ACCESS_KEY"],
  :aws_secret_access_key => ENV["BUCKET_SECRET_KEY"]

bucket = s3.directories.get(ENV["BUCKET_NAME"])

file = bucket.files.create(
  :key  => "helloworld.txt",
  :body => "Hello World!\n"


The Bucket dashboard allows you to view information about your S3 bucket.

The dashboard can be accessed via the CLI:

$ heroku addons:open bucket
Opening bucket for sharp-mountain-4005...

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

Migrating between plans

Use the heroku addons:upgrade command to migrate to a new plan.

$ heroku addons:upgrade bucket:500mb
-----> Upgrading bucket:5gb sharp-mountain-4005... done, v18 ($5/mo)

Removing the add-on

Bucket can be removed via the CLI.

This will destroy all associated data and cannot be undone!

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

Before removing Bucket be sure to download any files you wish to keep from your bucket.


All Bucket 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 support@piraterad.io.