POLICY-SDK-APP/src/main/webapp/app/policyApp/CSS/bootstrap/test-infra/README.md

   1 ## What does `s3_cache.py` do?
   2
   3 ### In general
   4 `s3_cache.py` maintains a cache, stored in an Amazon S3 (Simple Storage Service) bucket, of a given directory whose contents are considered non-critical and are completely & solely determined by (and should be able to be regenerated from) a single given file.
   5
   6 The SHA-256 hash of the single file is used as the key for the cache. The directory is stored as a gzipped tarball.
   7
   8 All the tarballs are stored in S3's Reduced Redundancy Storage (RRS) storage class, since this is cheaper and the data is non-critical.
   9
  10 `s3_cache.py` itself never deletes cache entries; deletion should either be done manually or using automatic S3 lifecycle rules on the bucket.
  11
  12 Similar to git, `s3_cache.py` makes the assumption that [SHA-256 will effectively never have a collision](http://stackoverflow.com/questions/4014090/is-it-safe-to-ignore-the-possibility-of-sha-collisions-in-practice).
  13
  14
  15 ### For Bootstrap specifically
  16 `s3_cache.py` is used to cache the npm packages that our Grunt tasks depend on and the RubyGems that Jekyll depends on. (Jekyll is needed to compile our docs to HTML so that we can run them thru an HTML5 validator.)
  17
  18 For npm, the `node_modules` directory is cached based on our `npm-shrinkwrap.json` file.
  19
  20 For RubyGems, the `gemdir` of the current RVM-selected Ruby is cached based on the `pseudo_Gemfile.lock` file generated by our Travis build script.
  21 `pseudo_Gemfile.lock` contains the versions of Ruby and Jekyll that we're using (read our `.travis.yml` for details).
  22
  23
  24 ## Why is `s3_cache.py` necessary?
  25 `s3_cache.py` is used to speed up Bootstrap's Travis builds. Installing npm packages and RubyGems used to take up a significant fraction of our total build times. Also, at the time that `s3_cache.py` was written, npm was occasionally unreliable.
  26
  27 Travis does offer built-in caching on their paid plans, but this do-it-ourselves S3 solution is significantly cheaper since we only need caching and not Travis' other paid features.
  28
  29
  30 ## Configuration
  31 `s3_cache.py` is configured via `S3Cachefile.json`, which has the following format:
  32 ```json
  33 {
  34     "cache-name-here": {
  35         "key": "path/to/file/to/SHA-256/hash/and/use/that/as/the/cache.key",
  36         "cache": "path/to/directory/to/be/cached",
  37         "generate": "shell-command --to run --to regenerate --the-cache $from scratch"
  38     },
  39     ...
  40 }
  41 ```
  42
  43 `s3_cache.py` will SHA-256 hash the contents of the `key` file and try to fetch a tarball from S3 using the hash as the filename.
  44 If it's unable to fetch the tarball (either because it doesn't exist or there was a network error), it will run the `generate` command. If it was able to fetch the tarball, it will extract it to the `cache` directory.
  45 If it had to `generate` the cache, it will later create a tarball of the `cache` directory and try to upload the tarball to S3 using the SHA-256 hash of the `key` file as the tarball's filename.
  46
  47
  48 ## AWS Setup
  49
  50 ### Overview
  51 1. Create an Amazon Web Services (AWS) account.
  52 2. Create an Identity & Access Management (IAM) user, and note their credentials.
  53 3. Create an S3 bucket.
  54 4. Set permissions on the bucket to grant the user read+write access.
  55 5. Set the user credentials as secure Travis environment variables.
  56
  57 ### In detail
  58 1. Create an AWS account.
  59 2. Login to the [AWS Management Console](https://console.aws.amazon.com).
  60 3. Go to the IAM Management Console.
  61 4. Create a new user (named e.g. `travis-ci`) and generate an access key for them. Note both the Access Key ID and the Secret Access Key.
  62 5. Note the user's ARN (Amazon Resource Name), which can be found in the "Summary" tab of the user browser. This will be of the form: `arn:aws:iam::XXXXXXXXXXXXXX:user/the-username-goes-here`
  63 6. Note the user's access key, which can be found in the "Security Credentials" tab of the user browser.
  64 7. Go to the S3 Management Console.
  65 8. Create a new bucket. For a non-publicly-accessible bucket (like Bootstrap uses), it's recommended that the bucket name be random to increase security. On most *nix machines, you can easily generate a random UUID to use as the bucket name using Python:
  66
  67     ```bash
  68     python -c "import uuid; print(uuid.uuid4())"
  69     ```
  70
  71 9. Determine and note what your bucket's ARN is. The ARN for an S3 bucket is of the form: `arn:aws:s3:::the-bucket-name-goes-here`
  72 10. In the bucket's Properties pane, in the "Permissions" section, click the "Edit bucket policy" button.
  73 11. Input and submit an IAM Policy that grants the user at least read+write rights to the bucket. AWS has a policy generator and some examples to help with crafting the policy. Here's the policy that Bootstrap uses, with the sensitive bits censored:
  74
  75     ```json
  76     {
  77         "Version": "2012-10-17",
  78         "Id": "PolicyTravisReadWriteNoAdmin",
  79         "Statement": [
  80             {
  81                 "Sid": "StmtXXXXXXXXXXXXXX",
  82                 "Effect": "Allow",
  83                 "Principal": {
  84                     "AWS": "arn:aws:iam::XXXXXXXXXXXXXX:user/travis-ci"
  85                 },
  86                 "Action": [
  87                     "s3:AbortMultipartUpload",
  88                     "s3:GetObjectVersion",
  89                     "s3:ListBucket",
  90                     "s3:DeleteObject",
  91                     "s3:DeleteObjectVersion",
  92                     "s3:GetObject",
  93                     "s3:PutObject"
  94                 ],
  95                 "Resource": [
  96                     "arn:aws:s3:::XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
  97                     "arn:aws:s3:::XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX/*"
  98                 ]
  99             }
 100         ]
 101     }
 102     ```
 103
 104 12. If you want deletion from the cache to be done automatically based on age (like Bootstrap does): In the bucket's Properties pane, in the "Lifecycle" section, add a rule to expire/delete files based on creation date.
 105 13. Install the [`travis` RubyGem](https://github.com/travis-ci/travis): `gem install travis`
 106 14. Encrypt the environment variables:
 107
 108     ```bash
 109     travis encrypt --repo twbs/bootstrap "AWS_ACCESS_KEY_ID=XXX"
 110     travis encrypt --repo twbs/bootstrap "AWS_SECRET_ACCESS_KEY=XXX"
 111     travis encrypt --repo twbs/bootstrap "TWBS_S3_BUCKET=XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"
 112     ```
 113
 114 14. Add the resulting secure environment variables to `.travis.yml`.
 115
 116
 117 ## Usage
 118 Read `s3_cache.py`'s source code and Bootstrap's `.travis.yml` for how to invoke and make use of `s3_cache.py`.