ghost-aws-s3-storage

An AWS S3 storage adapter for Ghost, built with AWS SDK for JavaScript v3 and the latest ghost-storage-base.

• No ACLs are set on uploads. Use bucket policies and/or CloudFront for access control.
• Compatible with S3 and S3-compatible providers (via custom endpoint + path-style).

Install

Install into your Ghost instance directory (the directory where Ghost runs):

npm install ghost-aws-s3-storage

Then copy the adapter into your Ghost content folder:

mkdir -p ./content/adapters/storage/aws-s3
cp -R ./node_modules/ghost-aws-s3-storage/* ./content/adapters/storage/aws-s3/

Notes:

• Copying the entire module preserves the structure expected by Ghost.
• Runtime dependencies are resolved from your Ghost root node_modules via Node's resolution algorithm.

Then update your Ghost config (e.g., config.production.json):

{
  "storage": {
    "active": "aws-s3",
    "aws-s3": {
      "region": "YOUR_AWS_REGION",
      "bucket": "YOUR_BUCKET",
      "assetHost": "https://cdn.example.com",      
      "pathPrefix": "content/images",              
      "endpoint": "https://s3-compatible.example", 
      "serverSideEncryption": "aws:kms",           
      "ssekmsKeyId": "arn:aws:kms:...:key/...",   
      "forcePathStyle": true                        
    }
  }
}

Notes:

• assetHost optional. If omitted, the adapter uses https://<bucket>.s3.<region>.amazonaws.com (or https://<bucket>.s3.amazonaws.com for us-east-1).
• pathPrefix optional subdirectory inside the bucket; defaults to none.
• endpoint and forcePathStyle are for S3-compatible providers.
• No ACLs are set; ensure your bucket policy or CloudFront settings provide the desired access.

Required vs Optional

• Required

  • region: from AWS_DEFAULT_REGION → AWS_REGION → config.region. If missing: throws "S3 region is required".
  • bucket: from GHOST_STORAGE_S3_BUCKET → GHOST_STORAGE_ADAPTER_S3_PATH_BUCKET → config.bucket. If missing: throws "S3 bucket is required".

• Optional

  • assetHost: from env → config.assetHost. Trailing slash removed. Default URL if unset:
    • Virtual-hosted-style when forcePathStyle=false: https://<bucket>.s3.<region>.amazonaws.com (or https://<bucket>.s3.amazonaws.com for us-east-1).
    • Path-style when forcePathStyle=true: https://s3.<region>.amazonaws.com/<bucket> (or https://s3.amazonaws.com/<bucket> for us-east-1).
    • For S3-compatible providers (custom endpoint), set assetHost to the public base URL you want returned.
  • pathPrefix: from env → config.pathPrefix. Default: empty. Prepended to stored keys (e.g., pathPrefix/YYYY/MM/file).
  • endpoint: from env → config.endpoint. Default: AWS regional endpoint. Affects SDK calls only; returned URLs use assetHost or the default host above.
  • forcePathStyle: from env (true|1|yes) → config.forcePathStyle. Default: false. Affects request style and default URL shape.
  • serverSideEncryption: from env → config.serverSideEncryption. Default: none. If set (e.g., aws:kms, AES256), applied to uploads.
  • ssekmsKeyId: from env → config.ssekmsKeyId. Used only when SSE uses KMS.
  • credentials: from config.accessKeyId/config.secretAccessKey; otherwise AWS default provider chain (env, role, web identity, shared config). If not set, SDK resolves automatically.

• Not used

  • ACLs: none are set. Use bucket policies/CloudFront.
  • signatureVersion: not configurable; AWS SDK v3 uses SigV4 by default.

Environment variables (optional)

These can be used instead of or alongside config values:

• AWS_ACCESS_KEY_ID
• AWS_SECRET_ACCESS_KEY
• AWS_DEFAULT_REGION
• GHOST_STORAGE_S3_BUCKET (or legacy GHOST_STORAGE_ADAPTER_S3_PATH_BUCKET)
• GHOST_STORAGE_S3_ASSET_HOST (or legacy GHOST_STORAGE_ADAPTER_S3_ASSET_HOST)
• GHOST_STORAGE_S3_PATH_PREFIX (or legacy GHOST_STORAGE_ADAPTER_S3_PATH_PREFIX)
• GHOST_STORAGE_S3_ENDPOINT (or legacy GHOST_STORAGE_ADAPTER_S3_ENDPOINT)
• GHOST_STORAGE_S3_SSE (or legacy GHOST_STORAGE_ADAPTER_S3_SSE)
• GHOST_STORAGE_S3_SSE_KMS_KEY_ID
• GHOST_STORAGE_S3_FORCE_PATH_STYLE (boolean: true|1|yes)

Methods

Implements the standard Ghost adapter methods: save, exists, delete, serve, read.

• Save returns the absolute URL (based on assetHost or default S3 host) to the stored object.
• Serve streams objects directly from S3 and sets common response headers.

License

MIT