Orchard Core Amazon S3 Media Storage - Prompt Templates

Module Overview

The OrchardCore.Media.AmazonS3 module enables storing media assets in Amazon S3 Buckets instead of the default App_Data file-based store. It provides two features:

OrchardCore.Media.AmazonS3 — Replaces the default media store with Amazon S3 storage.
OrchardCore.Media.AmazonS3.ImageSharpImageCache — Stores ImageSharp resized image cache in Amazon S3 instead of the local file system.

Media is still served by the Orchard Core web site. The Media Cache module fetches assets on the fly from S3, enabling image resizing through ImageSharp.Web integration.

Amazon S3 Media Storage Configuration

Guidelines

Enable the OrchardCore.Media.AmazonS3 feature.
Only one storage provider can be active at a time (File Storage, Azure Blob Storage, or Amazon S3 Storage).
When hosting inside AWS (EC2, EKS, etc.), you only need BucketName; credentials are resolved via IAM roles.
When hosting outside AWS, provide credentials via the Credentials section, AWS CLI profiles, or environment variables.
Prefer AWS profiles or environment variables over embedding credentials in appsettings.json to avoid accidental source control exposure.
Set CreateBucket to true to auto-create the bucket. New buckets are created without ACLs for security.

Configuration Properties

Property	Description	Default
BucketName	AWS S3 bucket name (required).	`""`
Region	AWS region endpoint (e.g., `eu-central-1`).	`""`
Profile	AWS CLI profile name (e.g., `default`).	`""`
ProfilesLocation	Custom location for AWS profiles file.	`""`
Credentials.SecretKey	AWS secret key (for hosting outside AWS).	`""`
Credentials.AccessKey	AWS access key (for hosting outside AWS).	`""`
BasePath	Subdirectory path inside the bucket.	`"/media"`
CreateBucket	Auto-create the bucket on startup.	`false`

Basic Configuration (Hosted in AWS)

{
  "OrchardCore": {
    "OrchardCore_Media_AmazonS3": {
      "BucketName": "my-orchard-media",
      "BasePath": "/media"
    }
  }
}

Configuration with Explicit Credentials (Hosted Outside AWS)

{
  "OrchardCore": {
    "OrchardCore_Media_AmazonS3": {
      "BucketName": "my-orchard-media",
      "Region": "eu-central-1",
      "Credentials": {
        "SecretKey": "your-secret-key",
        "AccessKey": "your-access-key"
      },
      "BasePath": "/media",
      "CreateBucket": true
    }
  }
}

Configuration with AWS Profile

{
  "OrchardCore": {
    "OrchardCore_Media_AmazonS3": {
      "BucketName": "my-orchard-media",
      "Region": "eu-central-1",
      "Profile": "default",
      "ProfilesLocation": "",
      "BasePath": "/media"
    }
  }
}

AWS Credentials Loading Order

The OrchardCore_Media_AmazonS3 configuration follows the standard AWSOptions loading order:

Credentials property of AWSOptions.
Shared Credentials File (custom location) — when both profile and profile location are specified.
SDK Store (Windows only) — when only the profile is set.
Shared Credentials File (default location) — when only the profile is set.
AWS Web Identity Federation Credentials — when an OIDC token file exists in environment variables.
CredentialsProfileStoreChain — SDK Store (Windows) then Shared Credentials File (default).
Environment variables — when AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY are set.
ECS Task Credentials or EC2 Instance Credentials — when using IAM roles.

Best practice: Use profiles or environment variables instead of embedding credentials directly in configuration files.

S3 Bucket Security Policies

Guidelines

Buckets created with CreateBucket: true are created without ACLs for security.
If creating a bucket manually, enable ACLs and configure public access settings.
To make media files publicly accessible, add an S3 bucket policy.
For manually created buckets, block all public access and use a bucket policy for read access.

Public Read Bucket Policy

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "AddPerm",
      "Effect": "Allow",
      "Principal": "*",
      "Action": "s3:GetObject",
      "Resource": "arn:aws:s3:::YOUR-BUCKET-NAME/YOUR-BASE-PATH/*"
    }
  ]
}

Manual Bucket ACL Setup

Open your bucket in the AWS Console.
Go to the Permissions tab.
Edit Block public access and tick "Block all public access".
Add the bucket policy above to grant read access to media files.

Multi-Tenant Bucket Templating

Guidelines

Use Liquid templating in BucketName and BasePath for multi-tenant setups.
The ShellSettings object is available in the Liquid template context.
{{ ShellSettings.Name }} is automatically lowercased; ensure the full BucketName conforms to S3 naming rules.
Only default Liquid filters and tags are available.

Bucket per Tenant

{
  "OrchardCore": {
    "OrchardCore_Media_AmazonS3": {
      "BucketName": "{{ ShellSettings.Name }}-media",
      "Region": "eu-central-1",
      "Credentials": {
        "SecretKey": "",
        "AccessKey": ""
      },
      "BasePath": "/media",
      "Profile": "",
      "ProfilesLocation": ""
    }
  }
}

Single Bucket with Base Folder per Tenant

{
  "OrchardCore": {
    "OrchardCore_Media_AmazonS3": {
      "BucketName": "shared-media",
      "Region": "eu-central-1",
      "Credentials": {
        "SecretKey": "",
        "AccessKey": ""
      },
      "BasePath": "{{ ShellSettings.Name }}/Media",
      "Profile": "",
      "ProfilesLocation": ""
    }
  }
}

Local S3 Emulator Setup (Docker)

Guidelines

Use a local emulator for development to avoid shared online storage conflicts.
Set ServiceURL instead of Region when using an emulator.
Enable ForcePathStyle: true for all emulators (uses http://localhost/mybucket instead of http://mybucket.localhost).
Credentials are required but not validated by emulators; use dummy values.

Emulator Configuration

{
  "OrchardCore": {
    "OrchardCore_Media_AmazonS3": {
      "ServiceURL": "http://localhost:9444/",
      "Profile": "default",
      "ProfilesLocation": "",
      "Credentials": {
        "SecretKey": "dummy",
        "AccessKey": "dummy"
      },
      "BasePath": "/media",
      "CreateBucket": true,
      "RemoveBucket": true,
      "BucketName": "media",
      "ForcePathStyle": true
    }
  }
}

Docker Commands for S3 Emulators

S3Mock (Adobe):

docker run -p 9444:9090 -t adobe/s3mock:latest

LocalS3 (Robothy):

docker run -d -e MODE=IN_MEMORY -p 9444:80 luofuxiang/local-s3:latest

Amazon S3 ImageSharp Image Cache

Guidelines

Enable the OrchardCore.Media.AmazonS3.ImageSharpImageCache feature.
Replaces the default PhysicalFileSystemCache with AWSS3StorageCache for resized images.
Useful for ephemeral file systems (containers, clean deployments).
Reduces pressure on local disk IO.
Cache files are only removed per tenant when using a separate bucket per tenant.
Templating and emulator settings work the same as for the main S3 media storage.

ImageSharp Cache Configuration

{
  "OrchardCore": {
    "OrchardCore_Media_AmazonS3_ImageSharp_Cache": {
      "Region": "eu-central-1",
      "Profile": "default",
      "ProfilesLocation": "",
      "Credentials": {
        "SecretKey": "",
        "AccessKey": ""
      },
      "BasePath": "/cache",
      "CreateBucket": true,
      "RemoveBucket": false,
      "BucketName": "imagesharp-cache"
    }
  }
}

CDN Caching Strategy

When fronting media with a CDN, allow sufficient time for CDN PoPs to cache assets before purging the local Media Cache.
Each CDN PoP maintains its own cache independently.
The Media Cache will re-fetch assets from S3 on demand when a CDN PoP requests an uncached item.
CDN providers clear caches on their own schedules; the S3 source must always remain accessible.
The Media Cache feature is automatically enabled with Amazon S3 storage and supports purging via the admin dashboard.