README

This is the README file for the OrePAN2::S3 distribution. The intent of this project is to create a so-called DarkPAN mirror that is served up from an S3 bucket behind a CloudFront distribution. However, this project can also support a website enabled S3 bucket without using CloudFront.

Prerequisites

You should set up your S3 bucket and CloudFront distribution before proceeding. You can use this project to set up your infrastructure before proceeding. That project will explain how to create and secure your own private static website hosted on S3. A script is included in that project to help you create all of the AWS artifacts required.

Install this Distribution from CPAN

cpanm -v OrePAN2::S3

This will install two scripts:

Script Name Description
orepan2-s3 Used to add new distributions to your DarkPAN
orepan2-s3-index Called by orepan2-s3 to create an index.html

.orepan2-s3.json

Set up a configuration file that will be used by the scripts. If you run orepan2-s3 the first time and there is no configuration, a default configuration will be installed in your home directory that looks something like this:

{
    "AWS": {
        "profile" : "prod",
        "region" : "us-east-1",
        "bucket" : "my-bucket",
        "prefix" : "orepan2"
    },
    "CloudFront" : {
        "DistributionId" : "**************"
    }
}

Note this is the minimum configuration. See perldoc OrePAN::S3 for more configuration file options.

If you are not using a CloudFront distribution (see below), remove or set the DistributionId to "".

Adding a New Distribution to Your DarkPAN

orepan2-s3 add {tarball}

Example:

orepan2-s3 add OrePAN2-S3-0.01.tar.gz

When you add a file to the DarkPAN repository the script will:

By default, the script invalidates the CloudFront cache if it finds a DistributionId in your configuration. You'll need to invalidate the cache in order to see your updates to the index.html and the DarkPAN index. If you don't need to do that because your TTL on your CloudFront distribution is fairly low, use the -x option to prevent the script from invalidating the cache.

Keep in mind that AWS gives you 1000 invalidations/month for free after which you pay $.005 per invalidation request. More than one file can be included in each request. The script will invalidate at least 4 paths on each invalidation request:

The Default Index

A default index page is created for you from a template embedded in the script. To view the default template:

orepan2-index dump-template

If you want to create your own template you can provide that using the C<--template> option. See C for more details.

Using a Website Enabled S3 Bucket

As explained here, there are many ways to create static websites. One such way is to use a feature of S3 that allows you to serve content directly from the bucket. In order to use HTTPS however, you would need to front the bucket using CloudFront and optionally install your own certificate and domain name.

If you don't want or need that kind of security and simply want to plow ahead with an insecure public bucket, you can do so. In that case you might want to at least create a bucket policy to restrict the IPs addresses that can access your bucket. Caveat Emptor.

To use an insecure bucket, simply remove the DistributionId from the configuration file.

You'll find a script here that will allow you to create your insecure website enabled bucket.

WARNING!

Take a look at this blog post before you blithely lock down your S3 bucket using an IP address.