A centralized paradigm of configuration management.
Clone or download
Failed to load latest commit information.
dot-net Fix broken markdown rendering May 31, 2017
.gitignore Bump version to 1.1.0-alpha1 Jun 26, 2014
CHANGELOG.md Release v1.2.1 Oct 25, 2016
CONTRIBUTING.md Add a few guidelines to the contributing doc Apr 22, 2014
LICENSE.txt add MIT license Jan 29, 2014



Build Status

Often, multiple related projects will need access to the same configuration values, which can be problematic if the projects use different technologies. Typically, configuration values are then stored in multiple places, making managing these values difficult.

Centroid lets you take control of your configurations by making it easy to work with a central configuration file that is accessible by various languages using a single API. Currently, Centroid supports Python, .NET, and Ruby.

Key Features of Centroid

  • Unified API supports multiple languages
  • Convenient method for retrieving all configuration values for a specific environment: environment-specific values are merged with values that apply to all environments
  • Ability to use native-language conventions to look up a key (underscores and case are ignored)
  • Ability to load the configuration file as a file or a string

Using Centroid

To use Centroid, you must first install the package for each desired language. Refer to the language-specific documents for installation instructions.

Once a Centroid package is installed, complete the following two items. Examples of both items are available later in this document.

  1. Declare your application's configuration values in JSON.
  2. Create an instance of the Config class to use the API. Refer to the language-specific documents for details specific to each language.

Using Native-language Conventions

Because Centroid ignores underscores and case, you can use native-language conventions to look up a key.

For example, your JSON configuration file could use camelCase while your Config class uses snake_case, PascalCase, or camelCase as appropriate for the language.


JSON Configuration File

The following example demonstrates storing a database's server address configuration value.

    "database": {
        "serverAddress": "my-server.local"

However, applications typically have different configuration values for each environment. For example, dev and prod environments use different servers and user accounts. But applications usually also have configuration values that are the same across all environments.

To create an environment-based configuration, make the top-level objects in the JSON represent the various environments, as in the example below. List the configuration values specific to an environment under the appropriate top-level object.

Also create an all top-level object. List the configuration values that are the same across all environments within this all environment.

    "dev": {
        "someResource": {
            "server": "resource-dev.local"
    "prod": {
        "someResource": {
            "server": "resource-prod.local"
    "all": {
        "keys": {
            "ssh": "path/to/id_rsa.pub"

Note: Refer to the language-specific documents for information on using the environment instance method to retrieve environment-based configurations.

API (Config Class)

Note: These Config class examples assume a JSON configuration file with the following:

    "database": {
        "serverAddress": "my-server.local"

The following Python example demonstrates loading a file (config.json) and retrieving the database’s server address using a snake_case property (database.server_address).

# my_app.py
config = Config.from_file("config.json")
server = config.database.server_address # => "my-server.local"

The following C# example demonstrates loading the JSON as a string and then retrieving the database's server address using a PascalCase property (Database.ServerAddress).

// MyApp.cs
var json = @"{ ""database"": { ""serverAddress"": ""my-server.local"" } }";
dynamic config = new Config(json);
var server = config.Database.ServerAddress; // => "my-server.local"

Refer to the language-specific documents for additional details about using the API, including examples of using the environment instance method.

Language-specific Documents

Each language has a separate document with information specific to that language.


See Contributing.


Thanks to all contributors!


Centroid is licensed under the MIT License.