Permalink
Browse files

Move the FAQ back into the repo to make it easier to find.

  • Loading branch information...
1 parent 2ad0621 commit 543ffdc9f47a724d4c5ebc39ed03e844f65a45fb @rgrove committed Jan 3, 2017
Showing with 155 additions and 1 deletion.
  1. +152 −0 FAQ.md
  2. +2 −0 README.md
  3. +1 −1 index.js
View
@@ -0,0 +1,152 @@
+# RawGit Frequently Asked Questions
+
+## Who runs RawGit?
+
+Hi, I'm [Ryan Grove](http://wonko.com/).
+
+## Why is this necessary? Can't I just load files from GitHub directly?
+
+When you request certain types of files (like JavaScript, CSS, or HTML) from
+`raw.githubusercontent.com` or `gist.githubusercontent.com`, GitHub serves them
+with a `Content-Type` header set to `text/plain`. As a result, most modern
+browsers won't actually interpret these files as JavaScript, CSS, or HTML and
+will instead just display them as text.
+
+GitHub does this because serving raw files from a git repo is inefficient and
+they want to discourage people from using their GitHub repos for static file
+hosting.
+
+RawGit acts as a caching proxy. It forwards requests to GitHub, caches the
+responses, and relays them to your browser with an appropriate `Content-Type`
+header based on the extension of the file that was requested. The caching layer
+ensures that minimal load is placed on GitHub, and you get quick and easy static
+file hosting right from a GitHub repo. Everyone's happy!
+
+## Is RawGit associated with GitHub?
+
+No, RawGit is not associated with GitHub in any way. Please don't contact GitHub
+asking for help with RawGit.
+
+## What's the difference between rawgit.com and cdn.rawgit.com URLs?
+
+When you make a request to a `rawgit.com` URL, the RawGit server loads the
+requested file from GitHub, serves it to your browser, and caches it for a short
+time. If you push new changes to GitHub, you can reload and see them within a
+few minutes. This makes `rawgit.com` useful for testing or sharing demos during
+development, but it also puts more server load on RawGit and GitHub.
+
+Requests to `cdn.rawgit.com` are routed through
+[MaxCDN](http://www.maxcdn.com/)'s super fast content delivery network, and are
+cached **permanently** at the CDN layer based on the URL. This results in the
+best performance and reduces load on RawGit and on GitHub, but it means that
+reloading won't fetch new changes from GitHub.
+
+During development, when traffic is low and freshness is more important than
+performance, use `rawgit.com`. For anything you share with the public or push to
+production, use `cdn.rawgit.com`.
+
+## Can I use a rawgit.com development URL on a production website or in public example code?
+
+No. Only use `rawgit.com` URLs for low-traffic testing or for sharing temporary
+demos with a few people during development. Please use `cdn.rawgit.com` for
+anything that might result in heavy traffic or that people might copy and paste
+into their own code.
+
+Please don't use `rawgit.com` URLs in example code or in public demos, because
+people often copy and paste that code and use it in production apps without
+realizing that they need to change the RawGit URLs. Then they send too much
+traffic to RawGit, get throttled, and their apps break.
+
+When people misuse `rawgit.com` development URLs, it costs me money. Please be
+considerate.
+
+## What will happen if I send large amounts of traffic to a rawgit.com development URL?
+
+First, requests will be throttled and your site will start to load very slowly.
+If the traffic continues even after automatic throttling is triggered, RawGit
+will start serving an error page instead of the requested file. If traffic
+reaches truly excessive levels, then a big ugly error message may be displayed
+directly on your website asking your users to notify you of the problem.
+
+This is designed to get your attention as quickly as possible before the
+excessive traffic becomes a major problem for RawGit and starts costing me
+large amounts of money or impacting other users of this service.
+
+Remember, only use `cdn.rawgit.com` in production.
+
+## How long does the CDN cache files? How can I make it refresh my file?
+
+The CDN caches files permanently based on their path. It ignores query strings.
+This is done to improve performance and to make it possible for the CDN to
+handle massive amounts of traffic without causing excessive load on RawGit or
+GitHub's servers.
+
+To ensure that the CDN always serves the version of the file you want, use a git
+tag or commit hash in the file's path instead of a branch name, and update the
+URL if you push a new version of the file.
+
+So, instead of a URL like `https://cdn.rawgit.com/user/repo/branch/file`, use a
+URL like `https://cdn.rawgit.com/user/repo/tag/file` or
+`https://cdn.rawgit.com/user/repo/commit/file`.
+
+## How can I get a GitHub URL with a commit hash to use with the CDN?
+
+![](https://camo.githubusercontent.com/046ef00f68f6936ac132a009135faba5236688aa/68747470733a2f2f63646e2e7261776769742e636f6d2f726a73746f6e652f726a73746f6e652e6769746875622e696f2f623633663866653930333231353165326532326235383933636562373137373734346665386531612f696d672f5261774769744c696e6b696e672e676966)
+
+## I need guaranteed 100% uptime. Should I use cdn.rawgit.com?
+
+No. RawGit is a free, best-effort service and cannot provide any uptime or
+support guarantees, even for the CDN.
+
+While I do my best to keep things running, things sometimes go wrong. Sometimes
+there are network or provider issues outside my control. Sometimes abusive
+traffic temporarily affects response times. Sometimes things break while I'm
+asleep and I don't know there are problems until I wake up. And sometimes I
+break things by doing something dumb (although I try really hard not to).
+
+Since I run RawGit in my spare time, with my own money and with CDN hosting
+generously donated by [MaxCDN](http://www.maxcdn.com/), it has a budget that's
+probably less than you pay for coffee in a given month. My goal is to help other
+open source developers get their projects up and running, but if you need to
+serve files that are crucial to your business, you should pay for a host with
+well-funded infrastructure and uptime guarantees.
+
+## Why do anonymous gist URLs return 403 errors?
+
+RawGit doesn't serve anonymous gists because they're frequently used for illegal
+or abusive content. Sorry.
+
+## I moved a file in my repo and now old RawGit URLs are broken. Is there any way to redirect to the new file?
+
+[There sure
+is](https://github.com/rgrove/rawgit/wiki/How-to-redirect-a-RawGit-URL-to-another-URL-or-GitHub-file)
+(for non-CDN URLs, anyway). But in the future, you might want to consider using
+URLs based on a tag or commit ref rather than a branch, since tags and commits
+always represent a single point in time and won't break if you move a file
+later.
+
+## Can I donate money/Bitcoin/pie to help you out?
+
+It's super nice of you to offer, but I don't need any donations at this time.
+RawGit's server costs are minimal, and the lovely people at
+[MaxCDN](http://www.maxcdn.com/) provide RawGit's CDN service free of charge.
+Thank you though!
+
+## I have feedback or want to report a problem! Who can I contact?
+
+- To report a critical issue like RawGit being broken or to share general
+ feedback, send a tweet to [@rawgit](https://twitter.com/rawgit) or
+ [@yaypie](https://twitter.com/yaypie). I try to respond quickly when I'm
+ awake and near a computer, but sometimes I do have to sleep. If you don't
+ get a response, just wait longer.
+
+- To report a non-critical issue, please
+ [file an issue](https://github.com/rgrove/rawgit/issues) on RawGit's GitHub
+ project.
+
+- To report a security concern, please email `security@rawgit.com` privately.
+ Feel free to encrypt your email using [my public key](https://rawgit.com/public-key.txt)
+ if you're paranoid. Expect a response within 48 hours.
+
+- To file a DMCA takedown notification or counter-notification, see
+ [RawGit's DMCA Notice & Takedown Procedure](RawGit-DMCA-Notice-&-Takedown-Procedure)
View
@@ -2,6 +2,8 @@
This is the source code behind <https://rawgit.com/>.
+Have questions about RawGit? See the [FAQ](FAQ.md).
+
## Installing
1. Install Node.js.
View
@@ -55,7 +55,7 @@ app.get('/', (req, res) => {
});
app.get('/faq', (req, res) => {
- res.redirect('https://github.com/rgrove/rawgit/wiki/Frequently-Asked-Questions');
+ res.redirect('https://github.com/rgrove/rawgit/blob/master/FAQ.md');
});
// Don't allow requests for Google Webmaster Central verification files.

0 comments on commit 543ffdc

Please sign in to comment.