# jekyll-s3

[![Build Status](https://secure.travis-ci.org/laurilehmijoki/jekyll-s3.png)] (http://travis-ci.org/laurilehmijoki/jekyll-s3)
[![Gem Version](https://fury-badge.herokuapp.com/rb/jekyll-s3.png)](http://badge.fury.io/rb/jekyll-s3)

Deploy your jekyll site to S3.

## What jekyll-s3 can do for you

* Upload your site to AWS S3
* Help you use AWS Cloudfront to distribute your Jekyll blog
* Create an S3 website for you
* Improve page speed with HTTP cache control and gzipping
* Set HTTP redirects for your website
* (for other features, see the documentation below)

## Install

    gem install jekyll-s3

## Usage

* Go to your jekyll site directory
* Run `jekyll-s3`. It generates a configuration file called `_jekyll_s3.yml` that looks like this:
<pre>
s3_id: YOUR_AWS_S3_ACCESS_KEY_ID
s3_secret: YOUR_AWS_S3_SECRET_ACCESS_KEY
s3_bucket: your.blog.bucket.com
</pre>
* Edit it with your details (you can use [ERB](http://ruby-doc.org/stdlib-1.9.3/libdoc/erb/rdoc/ERB.html) in the file)
* Run `configure-s3-website --config-file _jekyll_s3.yml` This will configure
  your bucket to function as an S3 website. If the bucket does not exist,
  `configure-s3-website` will create it for you.

* Run `jekyll-s3` to push your Jekyll blog to S3. Congratulations! You are live.

(If you are using `jekyll-s3` on an [EC2 instance with IAM
roles](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/UsingIAM.html#UsingIAMrolesWithAmazonEC2Instances),
you can omit the `s3_id` and `s3_secret` keys in the config file.)

### Using environment variables

You can use ERB in your `_jekyll_s3.yml` file which incorporates environment variables:

```yaml
s3_id: <%= ENV['S3_ID'] %>
s3_secret: <%= ENV['S3_SECRET'] %>
s3_bucket: blog.example.com
```

## Additional features

### Cache Control

You can use the `max_age` configuration option to enable more effective browser
caching of your static assets. There are two possible ways to use the option:
you can specify a single age (in seconds) like so:

```yaml
max_age: 300
```

Or you can specify a hash of globs, and all files matching those globs will have
the specified age:

```yaml
max_age:
  "assets/*": 6000
  "*": 300
```

Place the configuration into the file `_jekyll_s3.yml`.

### Gzip Compression

If you choose, you can use compress certain file types before uploading them to
S3. This is a recommended practice for maximizing page speed and minimizing
bandwidth usage.

To enable Gzip compression, simply add a `gzip` option to your `_jekyll_s3.yml`
configuration file:

```yaml
gzip: true
```

Note that you can additionally specify the file extensions you want to Gzip
(`.html`, `.css`, `.js`, and `.txt` will be compressed when `gzip: true`):

```yaml
gzip:
  - .html
  - .css
  - .md
```

Remember that the extensions here are referring to the *compiled* extensions,
not the pre-processed extensions.

### Using non-standard AWS regions

By default, `jekyll-s3` uses the US Standard Region. You can upload your Jekyll
site to other regions by adding the setting `s3_endpoint` into the
`_jekyll_s3.yml` file.

For example, the following line in `_jekyll_s3.yml` will instruct `jekyll_s3` to
push your site into the Tokyo region:

```yaml
s3_endpoint: ap-northeast-1
```

The valid `s3_endpoint` values consist of the [S3 location constraint
values](http://docs.amazonwebservices.com/general/latest/gr/rande.html#s3_region).

### Ignoring files you want to keep on AWS

Sometimes there are files or directories you want to keep on S3, but not on
your local machine. You may define a regular expression to ignore files like so:

```yaml
ignore_on_server: that_folder_of_stuff_i_dont_keep_locally
```

### Reduced Redundancy

You can reduce the cost of hosting your blog on S3 by using Reduced Redundancy Storage:

  * In `_jekyll_s3.yml`, set `s3_reduced_redundancy: true`
  * All objects uploaded after this change will use the Reduced Redundancy Storage.
  * If you want to change all of the files in the bucket, you can change them through the AWS console, or update the timestamp on the files before running `jekyll-s3` again

### How to use Cloudfront to deliver your blog

It is easy to deliver your S3-based web site via Cloudfront, the CDN of Amazon.

#### Creating a new CloudFront distribution

When you run the command `configure-s3-website`, it will ask you whether you
want to deliver your website via CloudFront. If you answer yes,
`configure-s3-website` will create a CloudFront distribution for you.

This feature was added into the version 1.3.0 of the `configure-s3-website` gem.
For more information, see the [gem's
documentation](https://github.com/laurilehmijoki/configure-s3-website).

#### Using your existing CloudFront distribution

If you already have a CloudFront distribution that serves data from your Jekyll
S3 bucket, just add the following line into the file `_jekyll_s3.yml`:

    cloudfront_distribution_id: your-dist-id

Next time you run `jekyll-s3`, it will invalidate the items on CloudFront and
thus force the CDN system to reload the changes from your Jekyll S3 bucket.

#### Specifying custom settings for your CloudFront distribution

The gem `configure-s3-website`, which is a dependency of `jekyll-s3`, lets you
define custom settings for your CloudFront distribution.

For example, like this you can define a your own TTL and CNAME:

```yaml
cloudfront_distribution_config:
  default_cache_behavior:
    min_TTL: <%= 60 * 60 * 24 %>
  aliases:
    quantity: 1
    items:
      CNAME: your.website.com
```

See the [gem's
documentation](https://github.com/laurilehmijoki/configure-s3-website) for more
info.

### The headless mode

Jekyll-s3 has a headless mode, where human interactions are disabled.

In the headless mode, `jekyll-s3` will automatically delete the files on the S3
bucket that are not on your local computer.

Enable the headless mode by adding the `--headless` or `-h` argument after
`jekyll-s3`.

### Configuring redirects on your Jekyll S3 website

You can set HTTP redirects on your Jekyll S3 website in two ways. If you only
need simple "301 Moved Premanently" redirects for certain keys, use the
Simple Redirects method. Otherwise, use the Routing Rules method.

#### Simple Redirects

For simple redirects Jekyll S3 uses Amazon S3's
[`x-amz-website-redirect-location`](http://docs.aws.amazon.com/AmazonS3/latest/dev/how-to-page-redirect.html)
metadata. It will create zero-byte objects for each path you want
redirected with the appropriate `x-amz-website-redirect-location` value.

For setting up simple redirect rules, simply list each path and target
as key-value pairs under the `redirects` configuration option:

```yaml
redirects:
  index.php: /
  about.php: about.html
  music-files/promo.mp4: http://www.youtube.com/watch?v=dQw4w9WgXcQ
```

#### Routing Rules

You can configure more complex redirect rules by adding the following
configuration into the `_jekyll_s3.yml` file:

```yaml
routing_rules:
  - condition:
      key_prefix_equals: blog/some_path
    redirect:
      host_name: blog.example.com
      replace_key_prefix_with: some_new_path/
      http_redirect_code: 301
```

After adding the configuration, run the command `configure-s3-website --config
_jekyll_s3.yml` on your command-line interface. This will apply the routing
rules on your S3 bucket.

For more information on configuring redirects, see the documentation of the
[configure-s3-website](https://github.com/laurilehmijoki/configure-s3-website#configuring-redirects)
gem, which comes as a transitive dependency of the `jekyll-s3` gem.

### Using `jekyll-s3` as a library

By nature, `jekyll-s3` is a command-line interface tool. You can, however, use
it programmatically by calling the same API as the executable `jekyll-s3` does:

````ruby
require 'jekyll-s3'
is_headless = true
Jekyll::S3::CLI.new.run('/path/to/your/jekyll-site/_site/', is_headless)
````

You can also use a basic `Hash` instead of a `_jekyll_s3.yml` file:

```ruby
config = {
  "s3_id"     => YOUR_AWS_S3_ACCESS_KEY_ID,
  "s3_secret" => YOUR_AWS_S3_SECRET_ACCESS_KEY,
  "s3_bucket" => "your.blog.bucket.com"
}
in_headless = true
Jekyll::S3::Uploader.run('/path/to/your/jekyll-site/_site/', config, in_headless)
```

The code above will assume that you have the `_jekyll_s3.yml` in the directory
`/path/to/your/jekyll-site`.

## Example configurations

See
<https://github.com/laurilehmijoki/jekyll-s3/blob/master/example-configurations.md>.

## Known issues

None. Please send a pull request if you spot any.

## Development

### Versioning

Jekyll-s3 uses [Semantic Versioning](http://semver.org).

### Tests

  * Install bundler and run `bundle install`
  * Run all tests by invoking `rake test`
  * Run the integration tests by running `bundle exec cucumber`
  * Run the unit tests by running `bundle exec rspec spec/lib/*.rb`

### Contributing

We (users and developers of Jekyll-s3) welcome patches, pull requests and
ideas for improvement.

When sending pull requests, please accompany them with tests. Favor BDD style
in test descriptions. Use VCR-backed integration tests where possible. For
reference, you can look at the existing Jekyll-s3 tests.

If you are not sure how to test your pull request, you can ask the [gem owners
](http://rubygems.org/gems/jekyll-s3) to supplement the request with tests.
However, by including proper tests, you increase the chances of your pull
request being incorporated into future releases.

## License

MIT

## Copyright

Copyright (c) 2011 VersaPay, Philippe Creux.

Contributors (in alphabetical order)
* Alan deLevie
* Cory Kaufman-Schofield
* Chris Kelly
* Chris Moos
* David Michael Barr
* László Bácsi
* Lauri Lehmijoki
* Mason Turner
* Michael Bleigh
* Shigeaki Matsumura
* stanislas
* Zee Spencer