README.md in s3_website-0.1.0 vs README.md in s3_website-0.2.0
- old
+ new
@@ -1,42 +1,42 @@
-# s3_website – Deploy your website to S3.
+# Deploy your website to S3
-[] (http://travis-ci.org/laurilehmijoki/s3_website)
+[](https://travis-ci.org/laurilehmijoki/s3_website)
[](http://badge.fury.io/rb/s3_website)
-## What s3_website can do for you
+## What `s3_website` can do for you
-* Upload your site to AWS S3
+* Create and configure an S3 website for you
+* Upload your static website to AWS S3
* Help you use AWS Cloudfront to distribute your website
-* 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
+<span style="color: yellow">This project is still on beta level. Expect backward
+incompatible changes.</span>
+
gem install s3_website
## Usage
+Here's how you can get started:
+
* Go to your website directory
-* Run `s3_website cfg create`. It generates a configuration file called `s3_website.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>
+* Run `s3_website cfg create`. It generates a configuration file called `s3_website.yml`
* 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 s3_website.yml` This will configure
+* Run `s3_website cfg apply` 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.
-
+ `s3_website cfg apply` will create it for you.
* Run `s3_website push` to push your website to S3. Congratulations! You are live.
-(If you are using `s3_website` 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.)
+`s3_website` attempts to be a command-line interface tool that is easy to
+understand and use. For example, `s3_website --help` should print you all the
+things it can perform. Please create an issue if you think the tool is
+incomprehensible or inconsistent.
### Using environment variables
You can use ERB in your `s3_website.yml` file which incorporates environment variables:
@@ -44,13 +44,19 @@
s3_id: <%= ENV['S3_ID'] %>
s3_secret: <%= ENV['S3_SECRET'] %>
s3_bucket: blog.example.com
```
+(If you are using `s3_website` 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.)
+
## Project goals
* Provide a command-line interface tool for deploying and managing S3 websites
+ * Create commands such as `s3_website push`, `s3_website cfg create` and
+ `s3_website cfg apply`
* Let the user have all the S3 website configurations in a file
* Minimise or remove the need to use the AWS Console
* Allow the user to deliver the website via CloudFront
* Automatically detect the most common static website tools, such as Jekyll or
Nanoc
@@ -146,18 +152,14 @@
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.
+When you run the command `s3_website cfg apply`, it will ask you whether you
+want to deliver your website via CloudFront. If you answer yes, command 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 website
S3 bucket, just add the following line into the file `s3_website.yml`:
@@ -166,12 +168,11 @@
Next time you run `s3_website`, it will invalidate the items on CloudFront and
thus force the CDN system to reload the changes from your website S3 bucket.
#### Specifying custom settings for your CloudFront distribution
-The gem `configure-s3-website`, which is a dependency of `s3_website`, lets you
-define custom settings for your CloudFront distribution.
+`s3_website` 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:
@@ -181,23 +182,21 @@
quantity: 1
items:
CNAME: your.website.com
```
-See the [gem's
-documentation](https://github.com/laurilehmijoki/configure-s3-website) for more
-info.
+Once you've saved the configuration into `s3_website.yml`, you can apply them by
+running `s3_website cfg apply`.
### The headless mode
s3_website has a headless mode, where human interactions are disabled.
In the headless mode, `s3_website` 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
-`s3_website`.
+Enable the headless mode by adding the `--headless` argument after `s3_website`.
### Configuring redirects on your S3 website
You can set HTTP redirects on your S3 website in two ways. If you only need
simple "301 Moved Premanently" redirects for certain keys, use the Simple
@@ -233,16 +232,16 @@
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
-s3_website.yml` on your command-line interface. This will apply the routing
-rules on your S3 bucket.
+After adding the configuration, run the command `s3_website cfg apply` 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 `s3_website` gem.
+gem, which comes as a transitive dependency of the `s3_website` gem. (The
+command `s3_website cfg apply` internally calls the `configure-s3-website` gem.)
### Using `s3_website` as a library
By nature, `s3_website` is a command-line interface tool. You can, however, use
it programmatically by calling the same API as the executable `s3_website` does: