README

Store HumHub file uploads in Amazon S3 or an S3-compatible service (MinIO, Wasabi, etc.) instead of the local filesystem.

Features

• Drop-in replacement for HumHub's default file storage
• Works with AWS S3 and S3-compatible endpoints
• Write-through local cache for compatibility with HumHub's file handling
• Admin UI with connection testing before enabling
• Optional credentials from environment variables

Requirements

• HumHub 1.14 or later
• PHP 8.0 or later (with curl extension)
• An S3 bucket and IAM credentials with appropriate permissions

Installation

Use a separate Composer project in protected/modules/. The module installs to protected/modules/humhub-s3/ and its dependencies go to protected/modules/vendor/, leaving HumHub's protected/vendor/ tree untouched.

Do not run composer init or composer require at the HumHub web root.

One-time setup — copy the Composer scaffold (once per HumHub instance):

cd /path/to/humhub/protected/modules
curl -fsSL https://raw.githubusercontent.com/Adrian-MID/humhub-s3/main/modules.composer.json -o composer.json

Install or update:

cd /path/to/humhub/protected/modules
composer require adrian-mid/humhub-s3:^1.0
php ../yii cache/flush-all

Enable HumHub S3 under Administration → Modules.

HumHub 1.16+ processes module disable and removal via background queue jobs. Ensure cron is running (php protected/yii cron/run) or run the queue worker manually (php protected/yii queue/run).

Configuration

Use Test Connection to verify upload, download, and delete operations before enabling storage.

HTTP endpoints are only allowed for localhost. Metadata IP addresses (e.g. 169.254.x.x) are blocked.

Environment variables

If you prefer to keep your AWS API key out of the database, you can configure optional environment variable names for credentials (e.g. AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY). When set and present on the server, they take precedence over database-stored values and database stored values can be empty.

Replace YOUR-BUCKET and adjust the prefix if you changed the default.

How it works

HumHub stores uploaded files through a pluggable StorageManager. When this module is enabled and configured, it replaces the default local storage manager with an S3-backed implementation.

Files are written to a local runtime cache first, then synced to S3. Downloads prefer the cache and fetch from S3 on demand. HumHub continues to handle access control — objects are not exposed via public S3 URLs.

Objects are stored under:

{prefix}/{guid[0]}/{guid[1]}/{guid}/{variant}

Example key: humhub/a/3/a3f2…/file

Limitations

• Existing files are not migrated. Files uploaded before enabling S3 remain on the local filesystem.
• Large files are streamed during upload and download, but very large files still depend on PHP and web server limits.
• No multipart upload. Very large files use a single PUT request.

Development

This module is maintained with strict static analysis and coding standards:

• PHPStan level 10 — composer phpstan
• PHP CS Fixer (PER-CS + PHP 8.2 migration rules) — composer cs:check / composer cs:fix

Run all checks:

composer install
composer lint

CI runs the same checks on push and pull requests via GitHub Actions.

Uninstall

Disabling or removing the module reverts to local filesystem storage and deletes all module settings (including stored credentials). On HumHub 1.16+, ensure the queue/cron is running so the background job completes.

License

GPL-3.0-or-later — see LICENSE.

Changelog

See CHANGELOG.md.