BoxLang 🚀 A New JVM Dynamic Language Learn More...

Preside Extension: S3 Storage Provider

v2.1.0+0000067 Preside Extensions

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.


box install preside-ext-s3-storage-provider


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."

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



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() {

		map( "myCustomStorageProvider" ).asSingleton().to( "" ).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
		).virtualInheritance( "presideSuperClass" );



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:



  • #13 Add a getTemporaryPrivateObjectUrl() method for getting presigned URLs for private objects


  • #12 Rewrite java interactions to use an isolated OSGi bundle, disassociating the extension with specific Lucee libraries and allowing usage with multiple versions of Lucee.


  • Use non-legacy URLs and endpoints for assets. i.e. and NOT


  • #10 fix for bad $raiseError() function call that was not wanted in the first place


  • Fix for issues when using commandline to process pushes and pulls with files containing spaces and other special chars


  • Log full error when falling back to 'File not found error'


  • Fix for issue where content-disposition for file downloads uploaded with CLI contained single quotes that broke the filename that browsers used for file download


  • Support for Preside 10.14 'file system' storage provider methods that allow operations just on local file paths, rather than binary objects loaded into memory.
  • Support using the AWS CLI to perform GETs and PUTs of objects rather than the Java API - minimize java memory usage


  • #4 ensure mimetype and content disposition is correctly set when moving an object


  • Ensure the new Preside 10.12 "ScheduledExportStorageProvider" is automatically converted to S3


  • Use more compatible mapping in wirebox.cfc (we have a problem with load order sometimes we think)


  • Ensure the new Preside 10.12 "ScheduledReportStorageProvider" is automatically converted to S3


  • Do not use Lucee temp directory for file based cache.


  • Fix objectExists() throwing an error rather than returning false when object does not exist in storage


  • Remove accidentally added code (out of place)


  • Ensure formbuilder storage provider is mapped to s3!


  • 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


  • Fix fieldnames for form validation


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


  • First draft working storage provider

$ box install preside-ext-s3-storage-provider

No collaborators yet.
  • {{ getFullDate("2019-02-07T11:22:27Z") }}
  • {{ getFullDate("2023-08-01T16:34:55Z") }}
  • 3,767
  • 93,253