README

This plugin registers a file storage backend for osTicket so new ticket attachments (and other files stored through the same mechanism) are saved as objects in a Google Cloud Storage bucket instead of the database.

Plugin ID: osticket:storage-gcs
Backend code: G (shown in the system “Store Attachments” dropdown as Google Cloud Storage (bucket/prefix)).

Requirements

• osTicket 1.17+ (see ost_version in plugin.php).
• PHP 8.0+ with extensions required by google/cloud-storage (e.g. JSON, OpenSSL).
• A GCS bucket and a Google Cloud service account key (JSON) with appropriate permissions (see below).
• Composer dependencies installed in this directory (vendor/autoload.php must exist or the plugin will not register the storage backend on bootstrap), unless you use the pre-built PHAR release (dependencies are bundled inside the archive).
• PHP Phar support (ext-phar) enabled if you install from a .phar file.

Installation

From PHAR (GitHub release)

Use this when you deploy from a release asset instead of a git checkout.

1. Download osticket-storage-gcs.phar from the GitHub Releases page for the version you want (the file is attached to each release after CI builds it).
2. Copy the file to your osTicket include/plugins/ directory, keeping the name osticket-storage-gcs.phar (same basename as the source folder so install paths stay predictable).
3. Do not run Composer in include/plugins/ for this layout—the PHAR already contains vendor and plugin.php at the archive root.
4. In Admin Panel → Manage → Plugins, add the plugin if it is not registered yet, then enable it and open configuration.

If you previously used the unpacked directory under include/plugins/osticket-storage-gcs/, disable or remove that installation before switching to the PHAR (only one layout should exist for this plugin id), then add the PHAR-based plugin again from the plugins list if needed.

From source (directory + Composer)

1. Copy the plugin folder to include/plugins/osticket-storage-gcs/ (or install from your deployment process).

2. From the plugin directory, install PHP dependencies:

   composer install --no-dev

   In Docker-based setups (example):

   docker compose exec php-fpm sh -c 'cd /var/www/html/include/plugins/osticket-storage-gcs && composer install --no-dev'

3. In Admin Panel → Manage → Plugins, add/install the plugin if it is not already listed, then enable it and open its configuration.

Plugin configuration

Open the plugin instance settings and fill in:

Saving the form runs a connectivity check (bucket->info()). If it fails, fix the bucket name, IAM, or credentials before continuing.

Google Cloud IAM (summary)

Grant the service account at least:

• Object read/write/delete on the bucket (e.g. Storage Object Admin on the bucket, or a custom role with storage.objects.* as needed).

For V4 signed URLs (redirect downloads), the account typically also needs permission to sign blobs (e.g. Service Account Token Creator on itself, or use a signing method supported by your environment as described in Google Cloud signed URLs).

Selecting the default storage backend

Enabling the plugin alone does not move attachments to GCS. You must set the system default storage to this backend.

1. Go to Admin Panel → Settings → System (or your equivalent System settings page).
2. Under Attachments Storage and Settings, set Store Attachments to the entry labelled Google Cloud Storage (...) (bucket/prefix as configured).

1. Save settings.

After this, new uploads use backend G. Existing attachments stay on their previous backend until you migrate them (if you use osTicket’s file migration tools).

Verify that objects land in GCS

• Upload a new attachment and confirm in the database (ost_file or your prefixed table) that the row’s bk column is G.
• List objects in the bucket (Console or gsutil ls gs://YOUR-BUCKET/your-prefix/).

If bk stays D (database) despite the plugin being enabled, the G backend is usually not registered (missing vendor/autoload.php) or the default storage dropdown was not switched to Google Cloud Storage.

Troubleshooting

• vendor/autoload.php missing: run composer install in the plugin directory (source install only). If you use the PHAR, ensure the file is readable under include/plugins/osticket-storage-gcs.phar and that the Phar extension is loaded.
• Silent fallback to database: osTicket may catch upload errors and try the next backend. Check PHP / osTicket logs and confirm IAM, bucket name, and credentials.
• Path to JSON in Docker: use a path inside the mounted application tree (e.g. under /var/www/html/...) so the PHP process can read the file.
• Plain “File not found” after saving a reply with an attachment (PHAR install): osTicket reads file bytes over HTTPS for mail and other paths; the plugin forces a host CA bundle for Guzzle when code runs from a PHAR. If it still fails, set openssl.cafile (or curl.cainfo) in php.ini to your system bundle (e.g. /etc/ssl/certs/ca-certificates.crt on Debian/Ubuntu).

License

See the LICENSE file in this repository.