jekyll-ezdeploy README

Version 0.1-ALPHA

Requirements

This tool is confirmed to work with

• s3cmd v2.0.1
• jekyll v3.6.2

Your mileage may vary with other versions of these tools.

Setup

1. Configure Jekyll

1. Install jekyll: gem install jekyll bundler
2. If you need to, create a new Jekyll site: jekyll new /path/to/site
3. In your Jekyll site directory, add your stage settings to _config-stage.yml and your production settings to _config-production.yml.

2. Configure AWS

1. Register a domain. (Optional) If you need a domain, register it.

2. Make a stage bucket.

   • Open the S3 console.
   • Click Create bucket.
   • Name it something like example.com-stage
   • Use all default settings.
   • Open bucket properties.
   • Under static website hosting, enable "Use this bucket to host a website". Customize your index or error path if needed. Note the endpoint URL.
   • Under Permissions, go to bucket policy, and enter this policy, with the name of your bucket entered:

   {
       "Version": "2012-10-17",
       "Statement": [
           {
               "Sid": "PublicReadGetObject",
               "Effect": "Allow",
               "Principal": "*",
               "Action": "s3:GetObject",
               "Resource": "arn:aws:s3:::NAMEOFYOURBUCKET/*"
           }
       ]
   }

   • Visit the endpoint URL -- you should see an AWS 404. (If you see a 403, you have a problem with your bucket policy.)

3. Get a stage certificate. (Optional)

   • If you want to have a stage URL other than an S3 or a Cloudfront URL, get a cert for it.

4. Make a stage Cloudfront distribution. (Optional)

   • Select your stage S3 bucket as the origin domain name.
   • ...
   • Use the cert you set up.
   • This takes a while to set up.

5. Make a production bucket.

   • Follow the same directions as above.

6. Get a production certificate through ACM.

7. Make a production distribution.

   • Same directions as above.

8. Set up a deployment user in IAM: https://console.aws.amazon.com/iam/home?region=us-east-1#/home

   • Name them something like example.com-deploy
   • Give them programmatic access only
   • Make a policy for them like this: NOTE: THIS DOESN'T ACTUALLY WORK RIGHT NOW

   {
       "Version": "2012-10-17",
       "Statement": [
           {
               "Sid": "VisualEditor0",
               "Effect": "Allow",
               "Action": [
                   "s3:ListAllMyBuckets",
                   "s3:HeadBucket",
                   "s3:ListObjects"
               ],
               "Resource": "*"
           },
           {
               "Sid": "VisualEditor1",
               "Effect": "Allow",
               "Action": "s3:*",
               "Resource": [
                   "arn:aws:s3:::YOURBUCKET-stage",
                   "arn:aws:s3:::YOURBUCKET-production"
               ]
           }
       ]
   }

   • ...

3. Configure Your Deployment

1. Install s3cmd: brew install s3cmd
2. Enter your deployment settings in CONFIG:
   • PROJECT_NAME is a human readable name for your project for easy reference
   • ABSOLUTE_PATH_TO_SITE is the path to your jekyll site
   • AWS_S3_HOST is the S3 endpoint for your bucket. The default host (which is for Northern Virginia, aka us-east-1) is s3.amazonaws.com. For the region you chose, see https://docs.aws.amazon.com/general/latest/gr/rande.html#s3_region for the endpoint URL to use.
   • BUCKET_NAME is the S3 bucket you want to deploy to

Operation

In the same directory as this README, ./deploy.sh to run. You'll be prompted for which environment (Stage or Production) you'd like to deploy to.