# README

# Table of Contents

* [README](#readme)
* [Prerequisites](#prerequisites)
  * [Install this Distribution from CPAN](#install-this-distribution-from-cpan)
  * [`.orepan2-s3.json`](#orepan2-s3json)
* [Adding a New Distribution to Your DarkPAN](#adding-a-new-distribution-to-your-darkpan)
  * [The Default Index](#the-default-index)
  * [Distribution Documentation](#distribution-documentation)
* [Using a Website Enabled S3 Bucket](#using-a-website-enabled-s3-bucket)
  * [WARNING!](#warning!)

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

# Prerequisites

* An AWS account
* An S3 bucket
* A CloudFront distribution
* ...and several Perl modules (see [requires](requires))

You should set up your S3 bucket and CloudFront distribution before
proceeding. You can use this
[project](https://github.com/rlauer6/s3-static-site) to set up your
infrastructure. 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 `bash` 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:

```
{
 "default": {
    "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 "".

[Back to Table of Contents](#table-of-contents)

# 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:

* Upload the file to your S3 bucket
* Update the package index
* Create a default F</index.html> page the shows all of your
  distributions
* Invalidate the CloudFront cache if you are using CloudFront

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:

* `/index.html`
* `/orepan2/02package.details.text.gz`
* `/orepan2/orepan2-cache.json`
* the distribution you just uploaded

## 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 or set the `template` key in your
configuration. See C<perldoc OrePAN2::S3> for more details.

## Distribution Documentation

Similar to the way the MetaCPAN sites show your POD as an HTML page,
the default index generated for you will show you a Module Index
listing all of your distributions.

* If your distribution has a `README.md` file then an document icon is
  placed next to the distribution name. Clicking the icon will bring
  up the HTML version of the `README.md`.
* If the primary Perl module in your distribution contains POD another
  document icon will be displayed. Clicking that icon will display the
  HTML version of the POD from your module.

[Back to Table of Contents](#table-of-contents)

# Using a Website Enabled S3 Bucket

As explained
[here](https://blog.tbcdevelopmentgroup.com/2025-02-18-post.html),
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](bin/create-insecure-bucket) that will
allow you to create your insecure website enabled bucket.

## WARNING!

Take a look at this [blog
post](https://blog.tbcdevelopmentgroup.com/2025-02-21-post.html)
before you blithely lock down your S3 bucket using an IP address.

[Back to Table of Contents](#table-of-contents)