Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 126 lines (69 sloc) 4.895 kB
362e9d8 @railsjedi Adding README and gemspec
railsjedi authored
1 # Jammit S3
2
3 ## Introduction
4
5 Jammit S3 is a jammit wrapper that provides appropriate hooks so you can easily deploy your assets to s3/cloudfront
6
7 It's especially great for Heroku user who use generated assets such as coffee-script and sass. jammit-s3 includes a script you can use as a hook to recompile and upload all your assets.
8
9
10 ## Installation
11
12 To install jammit-s3, just use:
13
14 gem install jammit-s3
15
16 If you are using Rails3, add it to your project's `Gemfile`:
17
18 gem 'jammit-s3'
19
20
3ab555b @railsjedi msg about jammit dependency
railsjedi authored
21 Jammit S3 already has a gem dependency for jammit, so I'd recommend removing any existing `gem 'jammit'` references from your Gemfile.
22
23
362e9d8 @railsjedi Adding README and gemspec
railsjedi authored
24 ## Configuration
25
26 Within your `config/assets.yml`, just add a toplevel key called `s3_bucket` that contains the bucketname you want to use. If jammit-s3 doesn't find the bucket, it will try to create it. Bucketnames need to be globally unique. Learn more about bucketnames [here](http://support.rightscale.com/06-FAQs/FAQ_0094_-_What_are_valid_S3_bucket_names%3F)
27
28 s3_bucket: my-awesome-jammit-bucket
29
30 ## Deployment
31
32 To deploy your files to s3, just the jammit-s3 command at your project's root.
33
34 jammit-s3
35
36 If using it in the context of your Rails3 app, I'd recommend using `bundle exec`
37
38 bundle exec jammit-s3
39
40 ## Saving Authentication Info
41
130972f @railsjedi updating readme
railsjedi authored
42 Set your authenticaton information within `config/assets.yml`
362e9d8 @railsjedi Adding README and gemspec
railsjedi authored
43
44 s3_access_key_id: 03HDMNF59CWZ2J24T702
45 s3_secret_access_key: 1TzRlDmuH8DoOlJ2tlwW8qx+i+Pfe0jzIouWI2BL
46
47 Replace these with your own access keys, found [here](https://aws-portal.amazon.com/gp/aws/developer/account/index.html?ie=UTF8&action=access-key).
48
49 As you probably don't want to check this data into source control, I'd recommend you just set it to an environment variable on your local box, and use ERB
50
830d414 @railsjedi Adding S3 Uploader and binary
railsjedi authored
51 s3_access_key_id: <%= ENV['ACCESS_KEY_ID'] %>
52 s3_secret_access_key: <%= ENV['SECRET_ACCESS_KEY'] %>
362e9d8 @railsjedi Adding README and gemspec
railsjedi authored
53
54 You can then set these env variables in your .bash_profile
55
56
830d414 @railsjedi Adding S3 Uploader and binary
railsjedi authored
57 ## Folders to upload
58
59 By default, jammit-s3 will upload your configured asset directly, along with public/images. However you can customize this using the `s3_upload_files` setting, which should be a list of file globs.
60
56dbae1 @railsjedi fix readme
railsjedi authored
61 # adds image uploads
62 s3_upload_files:
63 - public/css/images/**
830d414 @railsjedi Adding S3 Uploader and binary
railsjedi authored
64
98dbfc4 @railsjedi Adding permission setting for uploaded objects
railsjedi authored
65 ## Setting permissions on uploaded s3 objects
66
67 By default, jammit-s3 uses the permission setting found on the s3 bucket. However, you can override this with the config:
68
69 s3_permission: public_read
70
71 Valid permission options are:
72
73 `private`: Owner gets FULL_CONTROL. No one else has any access rights. This is the default.
74
75 `public_read`: Owner gets FULL_CONTROL and the anonymous principal is granted READ access. If this policy is used on an object, it can be read from a browser with no authentication.
76
77 `public_read_write`: Owner gets FULL_CONTROL, the anonymous principal is granted READ and WRITE access. This is a useful policy to apply to a bucket, if you intend for any anonymous user to PUT objects into the bucket.
78
79 `authenticated_read`: - Owner gets FULL_CONTROL, and any principal authenticated as a registered Amazon S3 user is granted READ access.
830d414 @railsjedi Adding S3 Uploader and binary
railsjedi authored
80
41e26a5 @fbjork removed CloudFront and SSL configuration, using config.action_control…
fbjork authored
81 ## Using CloudFront
362e9d8 @railsjedi Adding README and gemspec
railsjedi authored
82
c9c5ab4 Updated README on the fact that asset_host will be set automatically
Kliment Mamykin authored
83 For this to work you need to make sure you have the CloudFront enabled via you Amazon acccount page. Go here: http://aws.amazon.com/cloudfront/ and click "Sign Up"
84
edb3cd7 Updated README with CloudFront setup options
Kliment Mamykin authored
85 To use CloudFront, simply add the following settings to config/assets.yml:
362e9d8 @railsjedi Adding README and gemspec
railsjedi authored
86
edb3cd7 Updated README with CloudFront setup options
Kliment Mamykin authored
87 use_cloudfront: on
4bcf0d1 Renamed config property cloud_dist_id to cloudfront_dist_id for
Kliment Mamykin authored
88 cloudfront_dist_id: XXXXXXXXXXXXXX
c9c5ab4 Updated README on the fact that asset_host will be set automatically
Kliment Mamykin authored
89 cloudfront_domain: xyzxyxyz.cloudfront.net
2364cd1 Updated README
Kliment Mamykin authored
90
4bcf0d1 Renamed config property cloud_dist_id to cloudfront_dist_id for
Kliment Mamykin authored
91 Please note that cloudfront_dist_id is not the same as the CloudFront domain
2364cd1 Updated README
Kliment Mamykin authored
92 name. Inside CloudFront management console select the
93 distribution, and you will see Distribution ID and Domain Name values.
362e9d8 @railsjedi Adding README and gemspec
railsjedi authored
94
41e26a5 @fbjork removed CloudFront and SSL configuration, using config.action_control…
fbjork authored
95 This will use the CloudFront domain name for your assets instead of serving them from the (slow) S3 bucket.
15868d7 @ariejan Update README
ariejan authored
96
e8aaa40 Updated README with CloudFront known issues
Kliment Mamykin authored
97 ### Known issues with CloudFront invalidation
98
99 1. It may reportedly take up to 15 minutes to invalidate all the CloudFront
100 caches around the globe (and Amazon charges for more than a certain number
101 of invalidations per month).
102
103 2. It's non-atomic from the perspective of the end-user: They may get an
104 older version of the site with a newer version of the JavaScript and CSS, or
105 vice versa.
106
107 3. It doesn't play nicely with aggressive HTTP caching. For example, once I
108 serve a script or a stylesheet, I would like it to be cached indefinitely
109 with no more round trips to see whether it is valid.
110
111 Given these constraints, there's still an important need for some kind of
112 content-based hashing. Done right, this assures that all files can be cached
113 indefinitely, and the user will always get matched HTML/JS/CSS files. (This currently
114 is in the works).
115
d083a0e @railsjedi Adding gemfile and bin
railsjedi authored
116 ## Bugs / Feature Requests
362e9d8 @railsjedi Adding README and gemspec
railsjedi authored
117
118 To suggest a feature or report a bug:
d083a0e @railsjedi Adding gemfile and bin
railsjedi authored
119 http://github.com/railsjedi/jammit-s3/issues/
120
121
122 ## Jammit Home Page
123
124 Jammit S3 is a simple wrapper around Jammit. To view the original Jammit docs, use http://documentcloud.github.com/jammit/
362e9d8 @railsjedi Adding README and gemspec
railsjedi authored
125
Something went wrong with that request. Please try again.