Amazon S3 Connector module

Amazon S3 Connector module provides an app that allows users to manage assets in Amazon S3 while using them in Magnolia.

Amazon S3 (Simple Storage Service) is an online file storage web service offered by Amazon Web Services that provides storage through web services interfaces.

Using Amazon S3 takes the load of storing and serving large assets off your Magnolia servers. 

Installing

<dependency>
  <groupId>info.magnolia.amazon</groupId>
  <artifactId>amazon-s3-connector-module</artifactId>
</dependency>

You also need

<dependency>
  <groupId>info.magnolia.dam</groupId>
  <artifactId>magnolia-dam-external-app</artifactId>
</dependency>

Connecting to Amazon S3

To connect to Amazon S3 and use the features of the module add your Amazon access key and secret access key in the module's configuration in /modules/amazon-s3-connector-module/config.

Amazon S3 Browser

In the Amazon S3 browser app you can work with assets within Magnolia as if you were in the Amazon S3 interface. To open the app, click the Amazon S3 browser tile:

Basic actions include

• Creating and deleting Amazon S3 buckets. Buckets can be region-specific.
• Creating, deleting and copying Amazon S3 folders.
• Uploading assets to Amazon S3, and deleting and copying assets.

Setting access control permissions

You can set access control permissions for each bucket, folder and asset to private or public. See Access Control List Overview (and particularly private and public-read access) for more.

Items whose status is red (unpublished) in the browser are not publicly visible, but are visible in the page editor on author instances for a short period of time (3 minutes).

Clearing cache

AmazonS3AssetProvider (Git) uses caching to keep the number of calls to Amazon S3 to a minimum. You can clear the cache in the browser app by executing the Refresh browser action. The cache expires automatically 15 minutes after last read.

Publishing assets

Like all Magnolia content, assets stored in Amazon S3 are not visible on public instances until they are published from an author instance.

To make S3 images publicly visible use the Publish action in the browser app. The publishing process simply changes the permissions in Amazon S3 to make them visible to the general public.

Unpublished assets (set to private) are visible on author instances for only 3 minutes during which temporary links are generated for them.

Using the DAM API

Amazon S3 Connector module implements the Magnolia DAM API. This means that you can work with assets stored in Amazon S3 the same way as assets stored in the JCR and managed in the Assets app. Item keys are used to retrieve assets or folders from Amazon S3 in the  <providerId>:/<bucketName>/<objectKey> format.

Using assets in templates

Since the Amazon S3 Connector module implements the Magnolia DAM API, you can use assets stored in Amazon S3 in the same was as other assets in your template scripts.

This example retrieves an S3 asset using damfn templating functions. 

<img src="${damfn.getAssetLink('s3:/myBucket/myFolder/my-asset.png')}" />

Post-processing of assets

Amazon S3 does not offer post-processing of assets and it is therefore currently not possible to use Magnolia's Imaging module with S3 assets. If your assets require post processing we recommend using Magnolia's DAM.