Storing images and files in Amazon S3

← Previous: Configuring CKEditor in Apostrophe

You can store your images and files in Amazon S3 if you wish. You don't have to use the local file system.

This is essential to host an Apostrophe site on Heroku, or an Amazon EC2 instance without persistent storage.

Just take advantage of the uploadfs module, which is built into Apostrophe.

First sign up for Amazon Web Services and create an S3 bucket in which to store your files. Do not use the us-east region for reasons explained below.

During the signup process you will obtain an AWS secret and key which are needed as part of the configuration.

Here's a working Amazon S3 configuration. Just add an uploadfs property to your configuration in app.js:

modules: {
  'apostrophe-attachments': {
    uploadfs: {
      backend: 's3',
      secret: 'YOUR AMAZON SECRET',
      key: 'YOUR AMAZON KEY',
      bucket: 'your-bucket-name',
      region: 'us-west-2'
    }
  }
}

With this configuration all file uploads are written to S3 instead of the local file system.

You may pass any options supported by the knox module.

Special requirements for the US-East region

The US-East region is misnamed; it is really "US Standard," and it serves files from both Oregon and Virginia.

As a consequence, it does not offer "read after write" consistency. This means that a file that uploadfs just stored will not necessarily be available to view right away. This is not a good user experience for users who are uploading images to Apostrophe and expecting to see them right away.

See this article for a detailed description of how long "eventual" consistency can really take.

So, just use a bucket in any other region, such as us-west-2.

If the East Coast is the best fit for you, use this instead as your "region" setting:

external-1

In June 2015, Amazon announced that the US-East region supports read-after-write consistency, but only if you use the s3-external-1 endpoint. Setting region to external-1 will cause uploadfs to use the proper URLs for this. (Note: do not include the s3- in the string.)

Next: Migrating from Apostrophe 0.5 →