IronWorker Client Library Configuration

Many of the client libraries make use of a global configuration scheme for all of Iron.io services. This approach lets you set and manage your tokens and project IDs in a centralized manner and make them available across all of Iron.io's services, even across workspaces.

This scheme allows you to spend less time on configuration issues and more on writing code. It also supports the design pattern that calls for strict separation of configuration information from application code.

The two most common variables used in configuration are the project ID and the token. The project ID is a unique identifier for your project and can be found in the HUD. The token is one of your tokens, which can be found on their own page in the HUD.

Quick Start

Create a file called .iron.json in your home directory (i.e., ~/.iron.json) and enter your Iron.io credentials:

{
    "token": "MY_TOKEN",
    "project_id": "MY_PROJECT_ID"
 }

The project_id you use will be the default project to use. You can always override this in your code.

Alternatively, you can set the following environment variables:

IRON_TOKEN=MY_TOKEN
IRON_PROJECT_ID=MY_PROJECT_ID

That's it, now you can get started.

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 Client's Environment Variables set in iron.json

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).

Accepted Values

The configuration scheme looks for the following values:

• 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.
• 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.

Note that only the project_id and token values need to be set. They do not need to be set at every level of the configuration, but they must be set at least once by the levels that are used in any given configuration. It is recommended that you specify a default project_id and token in your iron.json file.

The File Hierarchy

The hierarchy of files is simple enough:

1. if a file named .iron.json exists in your home folder, that will provide the defaults.
2. if a file named iron.json 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:

{
  "token": "YOUR TOKEN HERE"
}

To follow this up by setting your project ID for each project, you would create an iron.json file in each project's directory:

{
  "project_id": "PROJECT ID HERE"
}

If, for one project, you want to use a different token, simply include it in that project's iron.json file:

{
  "project_id": "PROJECT ID HERE",
  "token": "YOUR TOKEN HERE"
}

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:

{
  "project_id": "GLOBAL PROJECT ID",
  "iron_cache": {
    "project_id": "IRONCACHE ONLY PROJECT ID"
  }
}

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.

Setting Host

If want to set the Host, Post, and Protocol specifically, simply include those keys in that project's iron.json file:

{
  "project_id": "PROJECT ID HERE",
  "token": "YOUR TOKEN HERE",
  "port":443,
  "protocol": "https",
  "scheme":"mq-rackspace-ord.iron.io"
}