Orchardcore Amazon S3 Media

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

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:

1. Credentials property of AWSOptions.
2. Shared Credentials File (custom location) — when both profile and profile location are specified.
3. SDK Store (Windows only) — when only the profile is set.
4. Shared Credentials File (default location) — when only the profile is set.
5. AWS Web Identity Federation Credentials — when an OIDC token file exists in environment variables.
6. CredentialsProfileStoreChain — SDK Store (Windows) then Shared Credentials File (default).
7. Environment variables — when AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY are set.
8. 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 Access

Guidelines

• Buckets created with CreateBucket: true are created without ACLs for security.
• Private bucket (recommended): Media is served through Orchard Core, so the application identity needs bucket access but the bucket does not need public reads.
• Public bucket: Use only when clients or a CDN must retrieve media directly from S3. Configure an explicit read policy and review the effect of public-access-block settings.
• Do not combine a public read policy with a public-access block that prevents public policies from taking effect.

Public Read Bucket Policy (Direct S3 Delivery Only)

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

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.
• The options type is AwsImageSharpImageCacheOptions.
• Custom startup registration uses the ImageSharpCache configure order.
• 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": "media-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.
• Local remote-media files use the wwwroot/{tenant}/ms-cache folder.