FORGEBOX Enterprise 🚀 - Take your ColdFusion (CFML) Development to Modern Times! Learn More...

Preside Extension: S3 Storage Provider

v0.9.3.00012 Public

Preside S3 Storage Provider

The S3 Storage Provider for Preside provides the best way to integrate S3 with your Preside applications. While you can use native Lucee S3 mappings, this method has the following advantages:

  • More intuitive to configure
  • Public/Private asset uploads are taken care of with precise ACL setting
  • Local file cache configurable with Cachebox

The provider is pretty much feature complete, but should be considered BETA at the time of this writing.

Installation

box install preside-ext-s3-storage-provider

Configuration

Using as your default storage provider for the asset manager

To configure the provider for use throughout the asset manager, you will need to set your S3 credentials and bucket name (at a minimum). These can either be set directly in your Config.cfc (not recommended), or injected using environment variables. The settings are:

settings.s3StorageProvider = {
	  accessKey = "" // required, i.e. your S3 access key
	, secretKey = "" // required, i.e. your S3 secret access key
	, bucket    = "" // required, e.g. 'my-unique-s3-bucket'
	, region    = "" // optional, e.g. eu-west-2 (default is us-east-1)
	, subpath   = "" // optional, e.g. /sub/path/in/bucket 
	, rootUrl   = "" // optional, e.g. https://custom.domain.com/public"
};

These can be injected using the following environment variables (e.g. if deploying with docker):

PRESIDE_S3_ASSETS_ACCESS_KEY
PRESIDE_S3_ASSETS_SECRET_KEY
PRESIDE_S3_ASSETS_REGION
PRESIDE_S3_ASSETS_BUCKET
PRESIDE_S3_ASSETS_SUBPATH
PRESIDE_S3_ASSETS_URL

Caching

The extension setups up a cachebox cache named, s3StorageProviderCache, to cache binary file downloads from S3. The default is a DiskCache in the temp directory with a 2 hour timeout and max 500 objects. If you wish to override this, simply configure your own s3StorageProviderCache in your application's Cachebox.cfc. For reference, here are the settings we have used:

{
	  objectStore                    = "DiskStore"
	, objectDefaultTimeout           = 120
	, objectDefaultLastAccessTimeout = 0
	, useLastAccessTimeouts          = false
	, reapFrequency                  = 60
	, freeMemoryPercentageThreshold  = 0
	, evictionPolicy                 = "LFU"
	, evictCount                     = 200
	, maxObjects                     = 500
	, directoryPath                  = GetTempDirectory() & "/.s3Cache"
	, autoExpandPath                 = false
}

Using for non-asset-manager storage

If you have configured storage providers that are for use outside of the asset manager (see documentation), you can change them to use the S3 Storage Provider in your application's /config/Wirebox.cfc. For example:

component extends="preside.system.config.WireBox" {

	public void function configure() {
		super.configure();

		map( "myCustomStorageProvider" ).asSingleton().to( "s3StorageProvider.services.S3StorageProvider" ).noAutoWire().initWith(
			  s3bucket    = "" // your settings here
			, s3accessKey = "" // your settings here
			, s3secretKey = "" // your settings here
			, s3region    = "" // your settings here
			, s3rootUrl   = "" // your settings here
			, s3subpath   = "" // your settings here
		);
	}

}

Contributing

Contribution in all forms is very welcome. Use Github to create pull requests for tests, logic, features and documentation. Or, get in touch over at Preside's slack team and we'll be happy to help and chat: https://presidecms-slack.herokuapp.com/.

Changelog

0.9.3

  • Change how public URLs are set. Now must either pass nothing for automatic public URL generation, or pass an explicity URL including the subpath to the public folder.
  • Do not lowercase all filenames
  • Fix bad argument names that break with the admin GUI setup of asset manager storage providers

0.9.2

  • Fix fieldnames for form validation

0.9.1

  • Remove dependency on S3SDK (not feature complete enough). Use jets3t that comes with Lucee instead.

0.9.0

  • First draft working storage provider

Here are all the versions for this package. Please note that you can leverage CommandBox package versioning to install any package you like. Please refer to our managing package version guide for more information.

Version Created Last Update Published By Stable Actions
Current
0.9.3.00012 Jul 30 2019 03:29 PM Jul 30 2019 03:29 PM
Version History
0.9.2.00008 Feb 08 2019 06:33 AM Feb 08 2019 06:33 AM
0.9.1.00006 Feb 07 2019 11:32 AM Feb 07 2019 11:32 AM
0.9.0.00003 Feb 07 2019 11:22 AM Feb 07 2019 11:22 AM

 

No collaborators yet.
  • Feb 07 2019 11:22 AM
  • Jul 30 2019 03:29 PM
  • 280
  • 378
  • 1222