Registry / storage / ghost-storage-adapter-s3

ghost-storage-adapter-s3

library2.8.0jsnpmunverified

An AWS S3 storage adapter for Ghost blogging platform (v1.x). Current version 2.8.0 provides a drop-in storage backend for Ghost 1.x, allowing media uploads to be stored in an S3-compatible bucket instead of the local filesystem. It supports configuration via JSON or environment variables, optional CDN integration with assetHost, SSE, path prefix, endpoint for third-party S3 providers, and ACL management. Compared to built-in local storage or other adapters, it offers direct S3 integration with IAM role support and is designed specifically for Ghost's storage API. Maintained on GitHub with periodic releases for minor updates and bug fixes.

storage

npm install ghost-storage-adapter-s3

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · GHOST-STORAGE-ADAP

ghost-storage-adapter-s3

storagejavascriptv2.8.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

default export

✓ const adapter = require('ghost-storage-adapter-s3');

✗ import adapter from 'ghost-storage-adapter-s3';

CommonJS module; no ESM default import. Use require() as shown.

adapter class

✓ const S3Adapter = require('ghost-storage-adapter-s3');

✗ import { S3Adapter } from 'ghost-storage-adapter-s3';

The module exports a class directly via module.exports = class S3Adapter { ... };

Install, configure with AWS credentials and bucket, copy to Ghost's adapter folder, restart.

// 1. Install // npm install ghost-storage-adapter-s3 aws-sdk // 2. Create adapter config in Ghost's config file (config.production.json) { "storage": { "active": "s3", "s3": { "accessKeyId": "YOUR_ACCESS_KEY_ID", "secretAccessKey": "YOUR_SECRET_ACCESS_KEY", "region": "us-east-1", "bucket": "my-ghost-blog", "assetHost": "https://cdn.mydomain.com", "signatureVersion": "v4" } } } // 3. Copy adapter into Ghost's content directory // mkdir -p ./content/adapters/storage && cp -r ./node_modules/ghost-storage-adapter-s3 ./content/adapters/storage/s3 // 4. Restart Ghost // ghost restart

Debug

Known issues

breakingAdapter only supports Ghost 1.x (not 0.10/0.11). For older versions use v1.3.0.

fix

Use ghost-storage-adapter-s3@1.3.0 for Ghost 0.10.x/0.11.x

affects: >=2.0.0

gotchaassetHost must include protocol (e.g., 'https://...') otherwise Ghost's domain may be prepended.

fix

Ensure assetHost string starts with '//' or full protocol like 'https://'

affects: >=1.0.0

gotchaIf using CloudFront, object ACL does not need to be 'public-read'.

fix

Set acl to appropriate private or omit if using CloudFront OAI

affects: >=1.0.0

gotchaThird-party S3 providers (e.g., MinIO) often require forcePathStyle: true and a custom endpoint.

fix

Configure endpoint and forcePathStyle in adapter settings

affects: >=1.0.0

deprecatedThe aws-sdk v2 package is in maintenance mode. Future may require migration to @aws-sdk/client-s3 v3.

fix

Plan to switch to @aws-sdk/client-s3 when adapter is updated

affects: >=2.8.0

Errors

Common errors & fixes

Error: connect ETIMEDOUT <s3-endpoint>

Network connectivity issue or incorrect endpoint configured for S3.

fix

Verify endpoint, region, and network access (firewall/proxy). For AWS S3, endpoint is implicit.

AccessDenied: Access Denied

IAM policy does not allow the required S3 actions or bucket policy blocks access.

fix

Ensure IAM user has s3:PutObject, s3:GetObject, s3:DeleteObject, s3:ListBucket on target bucket resources.

The authorization mechanism you have provided is not supported

Missing signatureVersion 'v4' for regions that require AWS Signature V4.

fix

Add 'signatureVersion': 'v4' to S3 adapter config.

TypeError: Cannot read property 'storage' of undefined

Adapter file not copied correctly or Ghost version mismatch.

fix

Ensure adapter is in ./content/adapters/storage/s3/ and Ghost version is 1.x.

Upgrade

Version history

2.8.0latest on npm

Audit

Dependencies

aws-sdkrequiredRequired to interact with AWS S3 API for upload, delete, and serve operations.

Agent activity

21 hits · last 30 days

node

Resources

githubhttps://github.com/colinmeinke/ghost-storage-adapter-s3 ↗

packageghost-storage-adapter-s3 ↗

homepagehttps://github.com/colinmeinke/ghost-storage-adapter-s3#readme ↗