ghost-gstorage-plugin

v2.1.1

Published

5 months ago

A comprehensive Ghost Blog storage adapter plugin for Google Cloud Storage, supporting all media types including images, videos, audio files, and documents.

0High
0Medium
0Low

ayushbnaik

ghost google cloud storage plugin blog media files images videos documents

📝 Table of Contents

🧐 About

The ghost-gstorage-plugin is a comprehensive storage adapter for Ghost CMS that allows you to store ALL your media files on Google Cloud Storage. This plugin provides a seamless way to manage and serve all types of media files directly from Google Cloud, ensuring high availability and scalability.

Version 2.0.0 now supports:

🖼️ Images (jpg, png, gif, webp, etc.)
🎥 Video files (mp4, avi, mov, webm, etc.)
🎵 Audio files (mp3, wav, flac, aac, etc.)
📄 Documents (pdf, doc, txt, zip, etc.)

✨ New Features v2.0.0

🚀 Complete Media Support

All file types: No more limitations to just images
Smart file detection: Automatically categorizes files by type
Organized storage: Files are organized into folders by type and date

📁 Improved Organization

Files are automatically organized in your Google Cloud Storage bucket:

your-bucket/
├── images/
│   ├── 2024/01/image-123456789.jpg
│   └── 2024/02/photo-987654321.png
├── media/
│   ├── 2024/01/video-123456789.mp4
│   └── 2024/02/audio-987654321.mp3
└── files/
    ├── 2024/01/document-123456789.pdf
    └── 2024/02/archive-987654321.zip

🔧 Better Configuration

Single adapter configuration for all file types
Individual adapter configuration for fine-grained control
Backward compatibility with v1.x configurations

🏁 Getting Started

These instructions will help you set up the ghost-gstorage-plugin on your Ghost blog.

Prerequisites

Before you begin, ensure you have met the following requirements:

You have a Google Cloud account.
You have created a Google Cloud Storage bucket.
You have a service account key JSON file for authentication.
Ghost CMS v4.0+ (required for file upload support)

Installing

Navigate to your Ghost installation directory:
```
cd /var/www/ghost
```

Install the plugin:

npm install --save ghost-gstorage-plugin@latest

Create the storage module:

export GHOST_ENVIRONMENT=production
export CONTENT_PATH=$(jq -r '.paths.contentPath // "."' config.${GHOST_ENVIRONMENT}.json)
mkdir -p ${CONTENT_PATH}/adapters/storage/gcloud
cat > ${CONTENT_PATH}/adapters/storage/gcloud/index.js << EOL
'use strict';
module.exports = require('ghost-gstorage-plugin');
EOL

⚙️ Configuration

Single Adapter Configuration (Recommended)

For most users, this is the simplest approach. All file types use the same Google Cloud Storage configuration:

{
  "storage": {
    "active": "gcloud",
    "gcloud": {
      "projectId": "your-project-id",
      "bucket": "your-bucket-name",
      "key": "path/to/your/service-account-key.json",
      "assetDomain": "https://your-custom-domain.com",
      "uploadFolderPath": "ghost-uploads",
      "insecure": false,
      "maxAge": 2678400
    }
  }
}

Multiple Adapter Configuration

For advanced users who want different configurations for different file types:

{
  "storage": {
    "images": {
      "adapter": "gcloud",
      "gcloud": {
        "projectId": "your-project-id",
        "bucket": "your-images-bucket",
        "key": "path/to/service-account-key.json",
        "uploadFolderPath": "images"
      }
    },
    "media": {
      "adapter": "gcloud", 
      "gcloud": {
        "projectId": "your-project-id",
        "bucket": "your-media-bucket",
        "key": "path/to/service-account-key.json",
        "uploadFolderPath": "media"
      }
    },
    "files": {
      "adapter": "gcloud",
      "gcloud": {
        "projectId": "your-project-id",
        "bucket": "your-files-bucket",
        "key": "path/to/service-account-key.json",
        "uploadFolderPath": "files"
      }
    }
  }
}

Configuration Options

projectId: Your Google Cloud project ID.
key: Path to your service account key JSON file.
bucket: Your Google Cloud Storage bucket name.
assetDomain: Optional custom domain for your bucket.
uploadFolderPath: The path within your bucket where files will be uploaded.
insecure: Set to true if using a custom domain without HTTPS.
maxAge: Cache control max-age in seconds (defaults to 31 days).

📁 File Organization

The plugin automatically organizes files based on their type:

File Type Detection

Images: .jpg, .jpeg, .png, .gif, .bmp, .webp, .svg, .ico
Media: .mp4, .avi, .mov, .wmv, .flv, .webm, .mkv, .mp3, .wav, .flac, .aac, .ogg, .m4a
Files: All other file types (.pdf, .doc, .zip, etc.)

Storage Structure

bucket-name/
├── [uploadFolderPath]/
│   ├── images/
│   │   └── YYYY/MM/filename-timestamp.ext
│   ├── media/
│   │   └── YYYY/MM/filename-timestamp.ext
│   └── files/
│       └── YYYY/MM/filename-timestamp.ext

🔧 Migration from v1.x

Version 2.0.0 is backward compatible with v1.x configurations. Your existing image uploads will continue to work without any changes.

To take advantage of the new features:

Update your Ghost installation to v4.0+ (if not already)
Install the latest version of the plugin
Update your configuration (optional - existing config will work)
Restart Ghost

🔍 Verification

After installation, verify your configuration:

ghost stop
ghost run

You should see logs indicating successful initialization. Test by uploading different file types in Ghost Admin.

⛏️ Built Using

@google-cloud/storage - Google Cloud Storage Node.js Client
Ghost - The open-source headless Node.js CMS
mime-types - MIME type detection

✍️ Authors

Ayush Naik - Initial work & enhancements.

🎉 Acknowledgements

Thanks to the Ghost community for their support and contributions.
Special thanks to users who requested full media support.

🐛 Issues & Support

If you encounter any issues or have questions:

Check the Ghost documentation for storage adapters
Create an issue on GitHub
Make sure your Ghost version supports the file types you're trying to upload