S3

edit Introduced: 4.5

S3

Lucee supports S3-compatible object storage through the S3 extension, which provides both a Virtual File System (VFS) using s3:// paths and a set of native s3*() functions. It works with AWS S3 and any S3-compatible provider such as MinIO, Backblaze B2, or Wasabi.

Installation

The S3 extension must be installed before use. Install it via the Lucee Administrator under Extension > Applications, or declare it in .CFConfig.json:

{
  "extensions": [
    {
      "id": "17AB52DE-B300-A94B-E058BD978511E39E",
      "name": "S3 Extension"
    }
  ]
}

Configuration

Credentials and connection settings can be configured in three ways, in order of precedence:

Application.cfc

component {
    this.name = "myapp";
    // configure S3 credentials and endpoint for all s3:// paths in this application
    this.vfs.s3.accessKeyId     = server.system.environment.LUCEE_S3_ACCESSKEYID;
    this.vfs.s3.awsSecretKey    = server.system.environment.LUCEE_S3_SECRETACCESSKEY;
    this.vfs.s3.host            = server.system.environment.LUCEE_S3_HOST;
    this.vfs.s3.defaultLocation = server.system.environment.LUCEE_S3_REGION;
    // required for self-hosted providers like MinIO that use path-style URLs
    this.vfs.s3.pathStyleAccess = true;
    // set to false for providers running over plain HTTP (e.g. local MinIO)
    this.vfs.s3.ssl             = false;
}

Environment Variables / System Properties

Environment Variable System Property Description
LUCEE_S3_ACCESSKEYID lucee.s3.accesskeyid Access key ID
LUCEE_S3_SECRETACCESSKEY lucee.s3.secretaccesskey Secret access key
LUCEE_S3_HOST lucee.s3.host Custom endpoint host (non-AWS)
LUCEE_S3_REGION lucee.s3.region Region or location
LUCEE_S3_PATHSTYLEACCESS lucee.s3.pathstyleaccess Force path-style URLs (true/false)
LUCEE_S3_SSL lucee.s3.ssl Use SSL/HTTPS (true/false)

Inline URL Credentials

Credentials can be embedded directly in the s3:// URL. Useful for one-off operations or multiple accounts in the same application:

s3://{accessKeyId}:{secretKey}@{host}/{bucket}/path/to/file.txt

Virtual File System (VFS)

With credentials configured in Application.cfc or via environment variables, all standard Lucee file functions work transparently against S3 using s3:/// paths (three slashes — the third slash starts the bucket path):

// read a file
content = fileRead("s3:///my-bucket/hello.txt");
// write a file
fileWrite("s3:///my-bucket/hello.txt", "Hello World");
// check existence
exists = fileExists("s3:///my-bucket/hello.txt");
// list a bucket
files = directoryList("s3:///my-bucket/", false, "query");
// copy between buckets
fileCopy("s3:///my-bucket/hello.txt", "s3:///other-bucket/hello.txt");
// delete
fileDelete("s3:///my-bucket/hello.txt");

Native S3 Functions

The extension also provides native s3*() functions that expose S3-specific features not available through the generic VFS interface:

Buckets

// list all buckets
buckets = s3listBuckets();
// list objects in a bucket
objects = s3listBucket("my-bucket");

Read and Write

// read a text object
content = s3read("my-bucket", "hello.txt");
// read binary object
binary = s3readBinary("my-bucket", "image.png");
// write an object
s3write("my-bucket", "hello.txt", "Hello World");

Copy, Move, Delete

// copy object (within or between buckets)
s3copy("my-bucket", "hello.txt", "other-bucket", "hello-copy.txt");
// move object
s3move("my-bucket", "hello.txt", "other-bucket", "hello-moved.txt");
// check existence
exists = s3exists("my-bucket", "hello.txt");
// delete object
s3delete("my-bucket", "hello.txt");

Metadata and ACL

// get object metadata
meta = s3getMetaData("my-bucket", "hello.txt");
// set custom metadata
s3setMetaData("my-bucket", "hello.txt", { "x-custom-tag": "value" });
// get ACL
acl = s3getACL("my-bucket", "hello.txt");

URLs

// generate a presigned URL (expires in 1 hour)
url = s3generatePresignedUrl("my-bucket", "hello.txt", 3600);
// generate a permanent URI
uri = s3generateUri("my-bucket", "hello.txt");

Self-Hosted Providers (MinIO, LocalStack)

Self-hosted S3-compatible providers require two additional settings:

  • pathStyleAccess = true — Lucee automatically enables path-style for unrecognised hostnames, but set this explicitly to guarantee it regardless of hostname. Prevents the AWS SDK from constructing virtual-hosted style URLs (bucket.host) which fail DNS resolution on non-AWS hostnames
  • ssl = false — disables HTTPS when the provider runs over plain HTTP
// Application.cfc for MinIO
this.vfs.s3.accessKeyId     = "minioadmin";
this.vfs.s3.awsSecretKey    = "minioadmin";
this.vfs.s3.host            = "minio:9000";
this.vfs.s3.defaultLocation = "us-east-1";
this.vfs.s3.pathStyleAccess = true;
this.vfs.s3.ssl             = false;

Available this.vfs.s3 Settings

Setting Type Default Description
accessKeyId string — Access key ID
awsSecretKey string — Secret access key
host string AWS S3 Custom endpoint host, e.g. minio:9000
defaultLocation string — Region, e.g. us-east-1
pathStyleAccess boolean null true = force path-style, false = force virtual-hosted, null = auto-detect
ssl boolean true false = connect over plain HTTP
acl string — Default ACL for new objects, e.g. public-read
cacheRegion boolean false Cache bucket region lookups to reduce extra requests
cache timespan — Cache duration for object listings

See Also

See also