HumHub AWS S3 Module - User Manual

Overview

The HumHub AWS S3 Module integrates Amazon Web Services (AWS) Simple Storage Service (S3) with your HumHub installation. This module allows you to store files uploaded to your HumHub platform in an AWS S3 bucket instead of your local file system, providing benefits such as:

• Improved scalability for file storage
• Better reliability and redundancy
• Reduced load on your web server

Requirements

• HumHub 1.17 or later
• AWS account with S3 access
• AWS Access Key and Secret Key with appropriate permissions
• S3 Bucket created in your AWS account

Installation

1. Download the AWS S3 Module from the HumHub Marketplace.
2. Log in to your HumHub installation as an administrator.
3. Navigate to Administration -> Modules.
4. Find the "AWS S3" module in the list and click "Enable".

Configuration

Creating AWS S3 Resources

Before configuring the module, you need to set up the required AWS resources:

1. Create an AWS Account if you don't already have one at aws.amazon.com.
2. Create an S3 Bucket:
   • Log in to the AWS Management Console
   • Navigate to S3 service
   • Click "Create bucket"
   • Choose a unique bucket name
   • Select the appropriate region for your needs
   • Configure bucket settings (public access, versioning, etc.)
   • Click "Create bucket"

3. Create an IAM User with S3 access:

   • Navigate to IAM service
   • Click "Users" then "Create user"
   • Enter a name for the user
   • Select "Programmatic access"
   • Create or assign a policy with the following permissions:

      {
        "Version": "2012-10-17",
        "Statement": [
            {
                "Effect": "Allow",
                "Principal": "*",
                "Action": "s3:ListBucket",
                "Resource": "arn:aws:s3:::YOUR-BUCKET-NAME"
            },
            {
                "Effect": "Allow",
                "Principal": "*",
                "Action": [
                    "s3:PutObject",
                    "s3:GetObject",
                    "s3:DeleteObject"
                ],
                "Resource": "arn:aws:s3:::YOUR-BUCKET-NAME/*"
            }
        ]
      }
     

   • Complete the user creation process
   • Important: Store the Access Key ID and Secret Access Key securely, as they will be shown only once

   ### Module Configuration

   1. After enabling the module, navigate to Administration -> Modules -> Config -> AWS S3.
   2. Enter the following information:
      • AWS Access Key: Your IAM user's Access Key ID
      • AWS Secret Key: Your IAM user's Secret Access Key
      • AWS Region: The region where your S3 bucket is located (e.g., us-east-1, eu-west-2)
      • S3 Bucket: The name of your S3 bucket
   3. Click "Save" to store your settings.

   ### CORS Configuration (Optional) If you encounter issues with cross-origin requests, you may need to configure CORS settings for your S3 bucket:

   1. In the AWS Management Console, navigate to your S3 bucket
   2. Click on the "Permissions" tab
   3. Scroll down to "Cross-origin resource sharing (CORS)"
   4. Click "Edit" and add a configuration similar to:

       [
       {
           "AllowedHeaders": [
               "*"
           ],
           "AllowedMethods": [
               "GET",
               "PUT",
               "POST",
               "DELETE",
               "HEAD"
           ],
           "AllowedOrigins": [
               "https://example.com"
           ],
           "ExposeHeaders": [
               "ETag"
           ],
           "MaxAgeSeconds": 3000
       }
       ]
      

4. Replace https://example.com with your actual HumHub URL
5. Click "Save changes"

Usage

Once configured, the module works transparently in the background. All file uploads in your HumHub installation will be automatically stored in your AWS S3 bucket instead of the local file system.

Testing Your Configuration

To verify that the module is working correctly:

1. Upload a file to your HumHub installation (e.g., a profile picture or a file in the Files module)
2. Check your S3 bucket in the AWS Management Console to confirm that the file appears there
3. Ensure that you can view/download the file in your HumHub installation
4. For added testing, you can also test the connection from the module settings.

Troubleshooting

Common Issues

1. Files cannot be uploaded:

   • Verify your AWS credentials are correct
   • Check that the IAM user has the necessary permissions
   • Ensure the S3 bucket exists and is accessible

2. Files upload but cannot be viewed:

   • Check your S3 bucket permissions
   • Verify CORS settings if applicable
   • Ensure your bucket policy allows the necessary actions

3. Module configuration page shows errors:

   • Check that all required fields are filled out correctly
   • Verify that your AWS region is specified correctly

Logs

Check the HumHub logs for more detailed error information:

• /protected/runtime/logs/

Uninstallation

If you wish to uninstall the module:

1. Before uninstalling, consider backing up any files stored in S3 if you want to keep them
2. Navigate to Administration -> Modules
3. Find the "AWS S3" module and click "Disable"
4. Once disabled, you can click "Uninstall"
5. Files will now be stored in the local file system again

Security Considerations

• Always use IAM users with the minimum necessary permissions
• Never share your AWS Access Key and Secret Key
• Consider enabling S3 bucket versioning to prevent accidental data loss
• Regularly review your S3 access logs for unusual activity
• Consider configuring server-side encryption for your S3 bucket

Support

For issues related to this module, please:

1. Check the module's documentation
2. Visit the HumHub community site
3. Email Green Meteor directly (i.e. hello@greenmeteor.net)