cloudflare/Stout
Publicmirrored fromhttps://github.com/cloudflare/Stout
docs/getting-started.md
48lines · modecode
unknown
| 1 | ### Setting Up Your Site |
| 2 | |
| 3 | If you don't already have an S3-hosted site, start here. |
| 4 | |
| 5 | We're going to create a basic site config which uses CloudFront's CDN to deliver high performance at a minimal cost. Once you run the setup, you'll end up with a configuration which looks like this: |
| 6 | |
| 7 | ``` |
| 8 | The Deploy Tool -> S3 <- CloudFront's Global CDN <- DNS <- Your Users |
| 9 | ``` |
| 10 | |
| 11 | The simplest way to get started is to run the `create_site.sh` script in the utils folder. After installing the [aws command line tools](http://aws.amazon.com/cli/), run: |
| 12 | |
| 13 | ```bash |
| 14 | ./utils/create_site.sh subdomain.my-site.com |
| 15 | ``` |
| 16 | |
| 17 | Feel free to leave out the subdomain if you'd like to host it at the root of your domain. |
| 18 | |
| 19 | This will: |
| 20 | |
| 21 | - Create an S3 bucket for this site with the correct security policy and website hosting |
| 22 | - Create a CloudFront distribution pointed at that bucket |
| 23 | - Create a user with the appropriate permissions to upload to that bucket |
| 24 | - Create an access key for that user |
| 25 | |
| 26 | Once that's done, copy the access key, secret key (from the JSON blob the access key request spits out) and bucket (the bucket's name is just the url you provided) it printed to your `deploy.yaml`, or save them to use with the `stout deploy` as arguments. |
| 27 | |
| 28 | The final step is to point your DNS records to the new CloudFront distribution. If you use Route 53 you want to create an alias to the distribution (it will be named the same as the new domain). If you use another DNS service, you'll want to create a CNAME to the CloudFront distribution's hostname. |
| 29 | |
| 30 | Please note that it will take up to twenty minutes for the CloudFront distribution to initialize. Additionally it may take some time for your DNS records to update. |
| 31 | |
| 32 | If you'd like development or staging environments, just run the command again with the URL you'd like them to have, and add the new credentials as before. See the "YAML Config" section of the README for an example of how to configure multiple environments. |
| 33 | |
| 34 | Be very careful to never commit a file to a public repo that contains your AWS credentials. If you are deploying a public repo, either keep the credentials on your local machine you deploy from, or in the build service (like CircleCI) you're using. |
| 35 | |
| 36 | #### Step-by-step Instructions |
| 37 | |
| 38 | 1. Install Amazon's AWS Command-Line Tools (and create an AWS account if you don't have one) |
| 39 | 1. Run the `create_site.sh` tool with the URL of the site you'd like to deploy |
| 40 | 1. Take note of the AWS key and secret in the final JSON blob outputted by the script |
| 41 | 1. Download the executable from this project |
| 42 | 1. Run `stout deploy --bucket subdomain.your-site.com --key YOUR_NEW_AWS_KEY --secret YOUR_NEW_AWS_SECRET` to deploy |
| 43 | 1. Add the `--root` argument if your built files are in a subdirectory. |
| 44 | 1. Visit the cloudfront url of your new distribution to see how your site currently looks, include any new files you may have missed and deploy again |
| 45 | 1. Optionally, Move any configuration options you don't mind being committed to your repository to a deploy.yaml file |
| 46 | 1. Optionally, Run `create_site.sh` again to create staging or development sites, and add their configuration to your deploy.yaml as well |
| 47 | 1. Optionally, Deploy more projects to this same site by running deploy with the `--dest` argument |
| 48 | 1. Optionally, Add the deploy step to your build tool |