request-tracker/README.S3

Setup
=====

In order to use the S3 storage type, you must grant RT access to your S3 account.

1. Log into Amazon S3, https://aws.amazon.com/s3/, as the account you wish 
   to store files under.

2. Navigate to "Security Credentials" under your account name in the menu bar.

3. Open the "Access Keys" pane.

4. Click "Create New Access Key".

5. Copy the provided values for Access Key ID and Secret Access Key into 
   your RT_SiteConfig.pm file:

        Set(%ExternalStorage,
            Type            => 'AmazonS3',
            AccessKeyId     => '...', # Put Access Key ID between quotes
            SecretAccessKey => '...', # Put Secret Access Key between quotes
            Bucket          => '...',
        );

6. Set up a Bucket for RT to use. You can either create and configure it 
   in the S3 web interface, or let RT create one itself. Either way, 
   tell RT what bucket name to use in your RT_SiteConfig.pm file:

        Set(%ExternalStorage,
            Type            => 'AmazonS3',
            AccessKeyId     => '...',
            SecretAccessKey => '...',
            Bucket          => '...', # Put bucket name between quotes
        );

7. You may specify a Host option in Set(%ExternalStorage, ...); to connect 
   to an endpoint other than Amazon::S3's default of s3.amazonaws.com.


Direct Linking
==============

This storage engine supports direct linking. This means that RT can link
directly to S3 when listing attachments, showing image previews, etc. This
relieves some bandwidth pressure from RT because ordinarily it would have to
download each attachment from S3 to be able to serve it.

To enable direct linking you must first make all content in your bucket
publicly viewable.

Beware that this could have serious implications for billing and privacy. RT
cannot enforce its access controls for content on S3. This is tempered somewhat
by the fact that users must be able to guess the SHA-256 digest of the file to
be able to access it. But there is nothing stopping someone from tweeting a URL
to a file hosted on your S3. These concerns do not arise when using an
RT-mediated link to S3, since RT uses an access key to upload to and download
from S3.

To make all content in an S3 bucket publicly viewable, navigate to the bucket
in the S3 web UI. Select the "Properties" tab and inside "Permissions" there is
a button to "Add bucket policy". Paste the following content in the provided
textbox:

    {
        "Version": "2008-10-17",
        "Statement": [
            {
                "Sid": "AllowPublicRead",
                "Effect": "Allow",
                "Principal": {
                    "AWS": "*"
                },
                "Action": "s3:GetObject",
                "Resource": "arn:aws:s3:::BUCKET/*"
            }
        ]
    }

Replace BUCKET with the bucket name that is used by your RT instance.

Finally, set $ExternalStorageDirectLink to 1 in your RT_SiteConfig.pm file:

    Set($ExternalStorageDirectLink, 1);

TROUBLESHOOTING
===============

Issues Connecting to the Amazon Bucket

Here are some things to check if you receive errors connecting to Amazon S3.

* Double check all of the configuration parameters, including the bucket name.
  Remember to restart the server after changing values for RT to load new
  settings.

* If you manually created a bucket, make sure it is in your default region. 
  Trying to access a bucket in a different region may result in 400 errors.

* Check the permissions on the bucket and make sure they are sufficient for 
  the user RT is connecting as to upload and access files. If you are using 
  the direct link option, you will need to open permissions further for users 
  to access the attachment via the direct link.