This add-on is operated by Ashfaq Bashir

Use Amazon S3 from your Heroku application.

Last updated February 09, 2023

Adding Amazon S3 to your Heroku application is effortless and basic with S3 Hero Dev.

Customers of all sizes and industries can store and protect any amount of data for virtually any use case, such as data lakes, cloud-native applications, and mobile apps. With cost-effective storage classes and easy-to-use management features, you can optimize costs, organize data, and configure fine-tuned access controls to meet specific business, organizational, and compliance requirements.

Provisioning the Add-on

S3 Hero Dev can be attached to a Heroku application via the CLI:

$ heroku addons:create s3herodev:elite

Choosing a Bucket Name

For the basic plan, bucket names are automatically generated. If you want a custom bucket name, upgrade your plan.

You can add the parameter bucketName on provisioning for configuring a custom bucket name:

$ heroku addons:create s3herodev:elite --bucketName s3bucket

Choosing a Region

The default region is us-east-1. You can choose a region from the following supported regions if your plan is above the basic plan:

• us-east-1 (Ohio)
• eu-central-1 (Frankfurt)

You can add the parameter region on provisioning for configuring a custom region:

$ heroku addons:create s3herodev:elite --region us-east-1

Config Vars

The following config vars are available in the app config when S3 Hero Dev is provisioned:

• S3_HERO_DEV_ACCESS_KEY_ID

• S3_HERO_DEV_SECRET_KEY_ID

• S3_HERO_DEV_BUCKET_NAME

• S3_HERO_DEV_REGION_NAME

These config vars can be confirmed using the heroku config command:

$ heroku config | grep s3herodev

After installing S3 Hero Dev, your application can interact with S3 using the IAM credentials provided to your application. This allows you to use any Amazon client, including the Amazon CLI, to interact with your bucket.

Local Setup

You can locally duplicate the config vars in your development environment after you’ve provisioned the S3 Hero Dev.

To view all of your config vars, type heroku config. Use the following command for each value that you want to add to your .env file:

$ heroku config:get S3_HERO_DEV_ACCESS_KEY_ID -s >> .env
$ heroku config:get S3_HERO_DEV_SECRET_KEY_ID -s >> .env

Or copy the entire file in one go:

$ heroku config -s | grep s3herodev > .env

For more information, see the Running Apps Locally article.

Using Amazon CLI

The AWS Command Line Interface (CLI) is a unified tool to manage your AWS services. With just one tool to download and configure, you can control multiple AWS services from the command line and automate them through scripts.

After you’ve installed it, you can configure it with the S3 Hero Dev settings in your app config:

$ aws configure
AWS Access Key ID [None]: <S3_HERO_DEV_ACCESS_KEY_ID>
AWS Secret Access Key [None]: <S3_HERO_DEV_SECRET_KEY_ID>
Default region name [None]: us-east-1
Default output format [None]

The following table lists the most popular commands used when using the AWS CLI for S3 Bucket:

Using with Node

Node applications must add the following entry into their package.json, specifying the dependency on the aws-sdk library:

$ npm install aws-sdk --save

You can configure the aws object globally:

process.env.AWS_ACCESS_KEY_ID     = process.env.S3_HERO_DEV_ACCESS_KEY_ID;
process.env.AWS_SECRET_ACCESS_KEY = process.env.S3_HERO_DEV_SECRET_KEY_ID;
process.env.AWS_REGION            = 'us-east-1';
var AWS = require('aws-sdk');
var s3  = new AWS.S3();

Or you can configure the aws object locally:

var AWS = require('aws-sdk');
var s3  = new AWS.S3({
  accessKeyId: process.env.BUCKETEER_AWS_ACCESS_KEY_ID,
  secretAccessKey: process.env.BUCKETEER_AWS_SECRET_ACCESS_KEY,
  region: 'us-east-1',
});

After creating an object, you can start making request to the S3 API:

var params = {
  Key:    'hello',
  Bucket: process.env.BUCKETEER_BUCKET_NAME,
  Body:   new Buffer('Hello, node.js'),
};

s3.putObject(params, function put(err, data) {
  if (err) {
    console.log(err, err.stack);
    return;
  } else {
    console.log(data);
  }

  delete params.Body;
  s3.getObject(params, function put(err, data) {
    if (err) console.log(err, err.stack);
    else     console.log(data);

    console.log(data.Body.toString());
  });
});

Using with Ruby

Ruby applications must add the following entry into their Gemfile specifying the aws-sdk client library:

$ bundle install

Update the application dependencies with Bundler:

$ gem 'aws-sdk'

To configure the S3 Client, in the config/initalizers/aws.rb, you can configure the aws object globally:

Aws.config[:credentials] = Aws::Credentials.new(
  ENV['S3_HERO_DEV_ACCESS_KEY_ID'],
  ENV['S3_HERO_DEV_SECRET_KEY_ID']
)
Aws.config[:region]      = 'us-east-1'
S3 = Aws::S3::Client.new

You can use this snippet to upload the file:

Aws::S3::Client.new.put_object(
  bucket: ENV['S3_HERO_DEV_BUCKET_NAME'],
  key: 'hello',
  body: 'world',
)

Using with Other Languages

To use S3 Hero Dev with other languages, use language-specific AWS SDKs (for example, Python, Java).

Dashboard

Use the S3 Hero Dev dashboard to:

• Create new IAM Credentials
• Get storage and bandwidth metrics to monitor your add-on usage
• Enable Static Website Hosting

You can access the dashboard via the CLI:

$ heroku addons:open s3-hero-dev

Or by visiting the Heroku Dashboard and selecting the application in question. Select S3 Hero Dev from the Add-ons menu.

Security

• The data you store on S3 Hero Dev is encrypted in transit and at rest on the server side.
• Our physical infrastructure is hosted on Amazon Web Services (AWS) data centers.

Migrating Between Plans

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

$ heroku addons:upgrade s3herodev:elite

Removing the Add-on

Use the heroku addons:destroy command to remove the add-on:

$ heroku addons:destroy s3herodev:elite

Before removing S3 Hero Dev, perform a data export by using your S3 client to download your data.

Support

Submit all S3 Hero Dev support and runtime issues via one of the Heroku Support channels. Any non-support related issues or product feedback is welcome.