Permalink
Browse files

small fixes and new configuration article.

  • Loading branch information...
1 parent 53540f6 commit f8c581f6d6938e154c40bc8c045b2b47236f58f9 @paddycarver paddycarver committed May 15, 2012
Showing with 242 additions and 5 deletions.
  1. +152 −0 _posts/2012-05-11-configuration.md
  2. +15 −0 articles/index.html
  3. +74 −4 cache/code/memcached/index.md
  4. +1 −1 cache/start/first-cache/index.md
@@ -0,0 +1,152 @@
+---
+permalink: /articles/configuration
+title: Configuring the Official Client Libraries
+categories:
+ - articles
+breadcrumbs:
+ - ['Articles', '/articles']
+ - ['Library Configuration', '/configuration']
+layout: post
+section: overview
+---
+
+# {{ page.title }}
+
+In the interest of letting users stop writing increasingly lengthy configuration
+files and start writing code, the maintainers of Iron.io's official client
+libraries have developed a global configuration scheme for all of Iron.io's
+services. This lets you set your project ID and token once to make them
+available to across all of Iron.io's services, and even across workspaces.
+The authors took care to provide a scheme that would allow users the
+flexibility to set a default, then override it at the service, workspace,
+or client level.
+
+## About the Scheme
+
+The configuration scheme consists of three hierarchies: the file hierarchy,
+the JSON hierarchy, and the overall hierarchy. By understanding these three
+hierarchies and how clients determine the final configuration values, you
+can build a powerful system that saves you redundant configuration while
+allowing edge cases.
+
+### The Overall Hierarchy
+
+The overall hierarchy is simple to understand: local takes precedence
+over global. The configuration is constructed as follows:
+
+* The global configuration file sets the defaults according to the file
+ hierarchy.
+* The global environment variables overwrite the global configuration file's
+ values.
+* The product-specific environment variables overwrite everything before
+ them.
+* The local configuration file overwrites everything before it according
+ to the file hierarchy.
+* The configuration file specified when instantiating the client library
+ overwrites everything before it according to the file hierarchy.
+* The arguments passed when instantiating the client library overwrite
+ everything before them.
+
+### The Environment Variables
+
+The environment variables the scheme looks for are all of the same formula:
+the camel-cased product name is switched to an underscore ("IronWorker"
+becomes "iron_worker") and converted to be all capital letters. For the
+global environment variables, "IRON" is used by itself. The value being
+loaded is then joined by an underscore to the name, and again capitalised.
+For example, to retrieve the OAuth token, the client looks for "IRON_TOKEN".
+In the case of product-specific variables (which override global variables),
+it would be "IRON_WORKER_TOKEN" (for IronWorker).
+
+### The File Hierarchy
+
+The hierarchy of files is simple enough: if a file named ".iron.json"
+exists in your home folder, that will provide the defaults. In addition,
+if an "iron.json" file exists in the same directory as the script being
+run, that will be used to *overwrite* the values from the ".iron.json"
+file in your home folder. Any values in "iron.json" that are not found
+in ".iron.json" will be added; any values in ".iron.json" that are not
+found in "iron.json" will be left alone; any values in ".iron.json" that
+are found in "iron.json" will be replaced with the values in "iron.json".
+
+This allows a lot of flexibility: you can specify a token that will be
+used globally (in ".iron.json"), then specify the project ID for each
+project in its own "iron.json" file. You can set a default project ID,
+but overwrite it for that one project that uses a different project ID.
+
+### The JSON Hierarchy
+
+Each file consists of a single JSON object, potentially with many sub-objects.
+The JSON hierarchy works in a similar manner to the file hierarchy: the
+top level provides the defaults. If the top level contains a JSON object
+whose key is an Iron.io service ("iron_worker", "iron_mq", or "iron_cache"),
+that will be used to overwrite those defaults when one of their clients
+loads the config file.
+
+This allows you to define a project ID once and have two of the services
+use it, but have the third use a different project ID.
+
+## Example
+
+In the event that you wanted to set a token that would be used globally,
+you would set "~/.iron.json" to look like this:
+
+{% highlight js %}
+{
+ "token": "YOUR TOKEN HERE"
+}
+{% endhighlight %}
+
+To follow this up by setting your project ID for each project, you would
+create an "iron.json" file in each project's directory:
+
+{% highlight js %}
+{
+ "project_id": "PROJECT ID HERE"
+}
+{% endhighlight %}
+
+If, for one project, you want to use a different token, simply include it
+in that project's "iron.json" file:
+
+{% highlight js %}
+{
+ "project_id": "PROJECT ID HERE",
+ "token": "YOUR TOKEN HERE"
+}
+{% endhighlight %}
+
+Now for that project *and that project only*, the new token will be used.
+
+If you want all your IronCache projects to use a different project ID, you
+can put that in the "~/.iron.json" file:
+
+{% highlight js %}
+{
+ "project_id": "GLOBAL PROJECT ID",
+ "iron_cache": {
+ "project_id": "IRONCACHE ONLY PROJECT ID"
+ }
+}
+{% endhighlight %}
+
+If you don't want to write things to disk or on Heroku or a similar platform
+that has integrated with Iron.io to provide your project ID and token
+automatically, the library will pick them up for you automatically.
+
+## Accepted Values
+
+The configuration scheme looks for the following values:
+
+* **host**: The domain name the API can be located at. Defaults to a
+ product-specific value, but always using Amazon's cloud.
+* **protocol**: The protocol that will be used to communicate with the API.
+ Defaults to "https", which should be sufficient for 99% of users.
+* **port**: The port to connect to the API through. Defaults to 443, which
+ should be sufficient for 99% of users.
+* **api_version**: The version of the API to connect through. Defaults to
+ the version supported by the client. End-users should probably never
+ change this.
+* **project_id**: The ID of the project to use for requests.
+* **token**: The OAuth token that should be used to authenticate requests.
+ Can be found [in the HUD](https://hud.iron.io/tokens).
View
@@ -0,0 +1,15 @@
+---
+title: All Articles | Iron.io Dev Center
+layout: default
+section: overview
+breadcrumbs:
+- ['Articles', '/articles']
+---
+
+<h1>All Articles</h1>
+
+<ul>
+ {% for post in site.categories.articles %}
+ <li><a href="{{ site.baseurl }}{{ post.permalink }}" title="{{ post.title }}">{{ post.title }}</a></li>
+ {% endfor %}
+</ul>
@@ -7,8 +7,75 @@ breadcrumbs:
- ['Memcached', '/memcached']
---
+<style type="text/css">
+.alert {
+ padding: 8px 35px 8px 14px;
+ margin: 10px;
+ color: #c09853;
+ text-shadow: 0 1px 0 rgba(255, 255, 255, 0.5);
+ background-color: #fcf8e3;
+ border: 1px solid #fbeed5;
+ -webkit-border-radius: 4px;
+ -moz-border-radius: 4px;
+ border-radius: 4px;
+}
+
+.alert-heading {
+ color: inherit;
+}
+
+.alert .close {
+ position: relative;
+ top: -2px;
+ right: -21px;
+ line-height: 18px;
+}
+
+.alert-success {
+ color: #468847;
+ background-color: #dff0d8;
+ border-color: #d6e9c6;
+}
+
+.alert-danger,
+.alert-error {
+ color: #b94a48;
+ background-color: #f2dede;
+ border-color: #eed3d7;
+}
+
+.alert-info {
+ color: #3a87ad;
+ background-color: #d9edf7;
+ border-color: #bce8f1;
+}
+
+.alert-block {
+ padding-top: 14px;
+ padding-bottom: 14px;
+ margin-top: 10px;
+}
+
+.alert-block > p,
+.alert-block > ul {
+ margin-bottom: 0;
+}
+
+.alert-block p + p {
+ margin-top: 5px;
+}
+</style>
+
# Memcached Support
+<div class="alert alert-danger">
+<p>
+<strong>Warning!</strong> Using the Memcached transport <em>does not</em> encrypt
+your credentials during transport. It should be used temporarily or for
+testing only, as it is less secure than the <a href="/cache/reference/api">REST API</a>.
+</p>
+</div>
+
You can use any of the [Memcached clients](http://code.google.com/p/memcached/wiki/Clients)
with IronCache. The list of supported languages is extensive, so there is
sure to be a library for your language of choice.
@@ -56,10 +123,13 @@ choose from for many languages):
</tbody>
</table>
-### Supported Protocols
-
-It's important to note that *only* the **text protocol** is supported in
-IronCache. The newer *binary* protocol is **not supported** at this time.
+<div class="alert">
+<p>
+It's important to note that <em>only</em> the <strong>text protocol</strong>
+is supported in IronCache. The newer <em>binary</em> protocol is <strong>not
+supported</strong> at this time.
+</p>
+</div>
## Host Information
To connect to IronCache using Memcached, use the host below:
@@ -169,7 +169,7 @@ the data:
That's everything you need to know to get started with IronCache. Yes, really.
From here, check out our [client libraries](/cache/code/libraries) to get a
-list of API wrappers you can use, our [API reference](/cache/reference/API) to
+list of API wrappers you can use, our [API reference](/cache/reference/api) to
get all the details about the API and the cache environment, and look into our
[memcached support](/cache/code/memcached) to connect with IronCache from your
favourite [memcached](http://memcached.org) client.

0 comments on commit f8c581f

Please sign in to comment.