Skip to content

Using Amazon S3 for Storage

ADAM BLVCK edited this page Jul 26, 2022 · 9 revisions

To enable S3 persistence in your pwa / app, follow these steps:

  1. Make yourself an AWS account
  2. Create an S3 bucket with default settings. In this example, we'll call the bucket MY_BUCKET_HERE.
  3. Create a new AWS IAM user with programmatic access.
  4. Create a new AWS IAM Policy with the following content. Attach it to the previously created AWS IAM user.
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "s3:*"
            ],
            "Resource": [
                "arn:aws:s3:::MY_BUCKET_HERE",
                "arn:aws:s3:::MY_BUCKET_HERE/*"
            ]
        }
    ]
}
  1. Download your AWS IAM User credentials (usually a CSV) with Access Key and Secret Access Key, and either add them to an .env file, since you don't want these to be pushed to GIT, or configure your app-host (like Heroku) to inject these credentials in the environment variables. For Heroku, this can be done by going to the Settings tab in their app dashboard, and going to the Config Vars section.
VARIABLE VALUE
AWS_ACCESS_KEY_ID paste your key here
AWS_S3_BUCKET paste bucket key here
AWS_SECRET_ACCESS_KEY paste secret here
'AWS_REGION' paste your s3 region
NPM_CONFIG_PRODUCTION false
  1. Configure your gun instance in the following way:
var gun = Gun({
   web: config.server.listen(config.port),
   peers: config.peers,
   s3: {
      key: env.AWS_ACCESS_KEY_ID, // AWS Access Key
      secret: env.AWS_SECRET_ACCESS_KEY, // AWS Secret Token
      bucket: env.AWS_S3_BUCKET // The bucket you want to save into
   }
});

To make S3 persistence work with the 1-click deploy to Heroku, it's recommended to fork/clone the gun repo, and perform the following changes to your forked copy:

  • Add "aws-sdk": "^2.528.0" to dependencies in package.json.
  • The Procfile tells heroku what file to start, when the instance starts. In this case it launches examples/http.js.
  • Proceed by changing the examples/http.js file, such that the gun instance starts with your S3 configuration:
var gun = Gun({
   web: config.server.listen(config.port),
   peers: config.peers,
   s3: {
      key: process.env.AWS_ACCESS_KEY_ID, // AWS Access Key
      secret: process.env.AWS_SECRET_ACCESS_KEY, // AWS Secret Token
      bucket: process.env.AWS_S3_BUCKET // The bucket you want to save into
   }
});
  • Deploy your forked repo to Heroku by executing (using Heroku CLI) the following in the repo:
heroku create # if not created before - creates a new app in your Heroku Dashboard
git push -f heroku HEAD:master # deploys HEAD:mater to your Heroku app

To monitor instance output, use:

heroku logs --tail

To restart the instance, to test S3 persistence, use:

heroku restart

Use a tool like Cyberduck to check if you can access the S3 bucket whilst providing your AWS IAM credentials.


If you are running your own server, you probably have an upstart script or something similar that monitors your app and starts or restarts it if it crashes. You can set ENVIRONMENT VARIABLES there, exactly how depends upon your setup so please google around for that.

Or if you are using command line directly, try something like:

$VARIABLE1=value1 VARIABLE2=value2 node yourapp.js

They will show up in NodeJS as process.env.AWS_ACCESS_KEY_ID and so on. They could also be set in NodeJS with process.env.AWS_ACCESS_KEY_ID = 'value'; but that is not recommended because it could leak your access keys to GitHub or other places.

This wiki is where all the GUN website documentation comes from.

You can read it here or on the website, but the website has some special features like rendering some markdown extensions to create interactive coding tutorials.

Please feel free to improve the docs itself, we need contributions!

Clone this wiki locally