TIBET

Configuration

Wins

• Single unified configuration system for client, server, and CLI.
• Command-line access to set or get system configuration values.
• Separate server-only configuration file with environment support.
• Package-controllable to support environment-specific config values.
• URL-accessible to alter client-side configuration for development.

Contents

Concepts

Cookbook

CLI Access

• The config command
• Setting A Value
• Reading A Value
• Reading Multiple Values
• Reading All Values

URL Parameters

• Setting A Single URL Parameter
• Setting Multiple URL Parameters
• Disabling URL Parsing

Boot Profiles

• Setting a profile property.

Launch Parameters

• Setting A Launch Value

Client-Side Configuration

• Reading A Runtime Client Value
• Reading Multiple Runtime Client Values
• Setting A Runtime Client Value

Server-Side Configuration

• Reading A Runtime TDS Value
• Reading Multiple Runtime TDS Values
• Setting A Runtime TDS Value

Configuration Files

• tibet.json (client)
• tds.json (server)
• tibet_cfg.js (defaults)

Configuration Resolution

Code

Concepts

Large applications benefit from configurability. From adjusting logging levels to enabling or disabling features and modules, being able to configure your application is a fundamental requirement for managing large-scale development and deployment.

TIBET uses an integrated configuration subsystem that shares configuration data between the command line tools, client stack, TIBET Data Server, and TIBET shell.

The tibet_cfg.js file provides library-level defaults. Your project's tibet.json file provides client settings and the optional tds.json file provides server settings. Common setcfg and getcfg routines provide access to configuration data along with the tibet config command:

Cookbook

CLI Access

The config command

The primary command line interface to the configuration system is the tibet config command, part of the TIBET CLI. The config command gives you complete control over project configuration by managing data in your project's tibet.json and tds.json files.

You can see the full options for the config command in your version of TIBET using the tibet help command or the --help option of the config command:

TIBET-CONFIG(1)                                     TIBET-CONFIG(1)

NAME
    tibet-config - manages and displays TIBET configuration data

SYNOPSIS
    tibet config [property[=value]] [--env <env>]

DESCRIPTION
    The config command can output one or more configuration values
    to the console based on current configuration data for your
    application or update a particular value to a string, number or
    boolean value.

    You can view the entire configuration list by leaving off any
    specific value. You can view all values for a particular prefix
    by listing just the prefix. You can view a specific value by
    naming that value directly.

    You can dump virtual paths by quoting them as in: '~app' or
    '~lib' as needed by whichever native shell you may be using.

    For set operations you can specify an optional environment
    value. In the current implementation this applies only to TDS
    settings (tds.* values).

    NOTE that if you use this command to set values it will rewrite
    tibet.json by using the beautify npm module to process the
    stringified JSON content. As a result your file may not retain
    its appearance after updates.

    Configuration data can also be updated by adding an = and value
    to a properly defined property name.

EXAMPLES
    List all configuration values:
        tibet config

    List all path values:
        tibet config '~'

    List all boot.* values:
        tibet config boot

    List a single value:
        tibet config boot.level

    Set a value (foo.bar to true here):
        tibet config foo.bar=true

February 2016                                       TIBET-CONFIG(1)

Setting A Value

To set a configuration value simply use a key=value syntax:

$ tibet config demo=true
true

To set a value that's nested use a dot-separated path:

$ tibet config test.setting=fluffy
fluffy

You can quote values as needed depending on your shell:

$ tibet config test.setting="fluffy stuff"
fluffy stuff

Boolean and numeric values are automatically converted to their proper form so they work correctly. All numeric conversions use a radix of base 10.

NOTE: If you use the command line tibet config command to set a value with a tds. prefix that value will be stored in the tds.json file rather than the tibet.json file to keep it from being exposed to the client.

Reading A Value

Reading values is simple, just name the value on the command line:

$ tibet config test.setting
fluffy stuff

Reading Multiple Values

You can see all the settings for a particular configuration prefix by using the prefix alone.

For example, you can list all the tibet-prefixed values as follows. Note that the output in these cases is JSON:

$ tibet config tibet
{
    "tibet.apptag": null,
    ...
}

Reading All Values

To view all known configuration values just leave off any parameters:

$ tibet config
{
    "~": "{path}/demo",
    ...
    ...
    "websocket.timeout": 15000
}

URL Parameters

One of the key features of the TIBET configuration subsystem is the ability to alter any parameter via the browser URL on startup.

When you launch a TIBET application by default your URL will normally look like:

http://127.0.0.1:1407

When you use a URL of this form your application will run with whatever settings are the defaults based on your tibet.json file or TP.sys.launch call.

Setting A Single URL Parameter

You can alter TIBET configuration variables on the URL by adding a fragment specifier and parameter section to that fragment:

http://127.0.0.1:1407#?boot.showlog=true

NOTE the # symbol on that URL above.

TIBET only uses the "client-specific" portion of the URL, aka the URI fragment, processing that as a combination of path and parameter data.

In the example above there is no path data (that's used for routing in the client) but there is a parameter section as signified by the ?. TIBET takes that segment and processes it just like a server might process normal parameters.

Note that you don't need to specify =true to set boolean flags to true, you can just mention the flag directly:

http://127.0.0.1:1407#?boot.showlog

Setting Multiple URL Parameters

As you might imagine, you use & to add additional parameters to the URL:

http://127.0.0.1:1407#?boot.showlog=true&boot.level=trace

The only limit is the size of URL allowed by the user's browser.

Disabling URL Parsing

For production deployment and other circumstances you may not want TIBET to parse the URL for parameters. You can make that a reality by setting boot.nourlargs to true in tibet.json file or your launch parameters as described in the discussion below.

Boot Profiles

When your application launches it reads boot.profile and boot.config configuration values to determine which application package to load. These values ultimately point to a TIBET package and a specific config within that file to load.

One aspect of a package config is that it can contain <property/> tags, tags which define key/value pairs used as part of the TIBET configuration for that package.

For example, here's a segment of the default development.xml file which describes the configurations and properties for the development profile.

<?xml version="1.0"?>

<package xmlns="http://www.technicalpursuit.com/1999/tibet"
    id="fluffy" default="base" basedir="~app_cfg">

<config id="properties" if="boot.phaseone">
    <property id="tibet.lama" value="true"/>
    <property id="debug.use_debugger" value="true"/>
    <property id="log.level" value="DEBUG"/>
</config>

<config id="base">
    <config ref="properties"/>
    <package src="standard.xml" config="base"/>
</config>

...

</package>

Note the <property/> tags above which turn on the Lama, allow the debugger keyword to trigger the debugger, and set logging to the DEBUG level.

Setting a profile property.

You can set any valid configuration property by adding a valid property tag to one or more config entries in your application package files.

For example, we can set the log.level value to DEBUG with the following entry:

    <property id="log.level" value="DEBUG"/>

Package properties are used in addition to settings in your tibet.json file whenever you launch that package/config.

Launch Parameters

Launch parameters are values you set directly in the TP.boot.launch command which triggers the TIBET Loader to start running.

Launch parameters are checked prior to reading the URL which allows you to use a launch parameter to turn off URL parsing as one example.

By default your project's index.html file will invoke TP.boot.launch without any options passed as a parameter:

TP.boot.launch();

Setting A Launch Value

You can configure your application parameters by passing a JavaScript object (not JSON) to this call:

TP.boot.launch({
    boot: { nourlargs: true }   // Turn off url argument processing.
});

As with the rest of TIBET's configuration system there are no restrictions on what values you provide as configuration properties. TIBET's configuration system will happily let you set any value without complaint.

Client-Side Configuration

At runtime your TIBET application has full access to, and control over, your application configuration using the TP.sys.getcfg and TP.sys.setcfg calls.

Reading A Runtime Client Value

The TP.sys.cfg (a shorthand for TP.sys.getcfg) method gives you access to configuration data from inside your application. For example, you can read the value for boot.level as follows:

var level = TP.sys.cfg('boot.level);

Reading Multiple Runtime Client Values

Just like the command line options, you can read multiple values by providing just the prefix for a set of values:

var bootparams = TP.sys.cfg('boot');

In this latter case the result is a TP.lang.Hash object, a dictionary whose methods give you the ability work with the parameters in a sensible fashion.

You can access the entire configuration dictionary using TP.sys.cfg without parameters:

var cfg = TP.sys.cfg();

Setting A Runtime Client Value

The TP.sys.setcfg method lets you set a configuration value at runtime. Values set in this fashion are transient, they don't persist in your project's tibet.json file, but they affect your application during runtime.

For example, you might temporarily enable code for an experimental feature with:

TP.sys.setcfg('featureX', true);

If you've wrapped that feature's code with if (TP.sys.cfg('featureX')) {...} you now have a "feature flipper" for that code.

Server-Side Configuration

The TIBET Server shares configuration data with the rest of TIBET and augments the standard tibet.json file with a tds.json file which is only readable from the server.

Reading A Runtime TDS Value

The TDS.getcfg command gives you access to configuration data from inside your server. For example, you can read the value for tds.log.level as follows:

var level = TDS.getcfg('tds.log.level);

Reading Multiple Runtime TDS Values

Just like the command line options, you can read multiple values by providing the prefix for a set of values:

var bootparams = TDS.getcfg('tds.use');

In this latter case the result is a raw JS object containing the keys and values for the properties in question (TIBET isn't present so neither is TP.core.Hash).

You can access the entire configuration dictionary using TDS.getcfg():

var cfg = TDS.getcfg();

Setting A Runtime TDS Value

The TDS.setcfg method lets you set a configuration value at runtime. Values set in this fashion are transient, they don't persist in your project's tibet.json or tds.json file, but they affect your server during runtime.

For example, you might temporarily enable code for an experimental feature with:

TDS.setcfg('featureX', true);

NOTE: If you use the command line tibet config command to set a value with a tds. prefix that value will be stored in the tds.json file rather than the tibet.json file to keep it from being exposed to the client.

Configuration Files

tibet.json (client)

Every TIBET project contains a configuration file, tibet.json, which is a JSON file containing project-specific configuration data. This file is the target for any tibet config operations which set persistent configuration values for the client.

Here's a simple example tibet.json file set up to boot the project with a full development profile that includes unminified code and unpackaged (single-file) loading.

{
    "tibet": {
        "dna": "/Users/ss/dev/TPI/TIBET/dna/default"
    },
    "boot": {
        "profile": "development@developer",
        "unminified": true,
        "unpackaged": true
    }
}

You normally don't need to edit the tibet.json file yourself, that's what tibet config is for, but you can if you like.

tds.json (server)

When using the TIBET Data Server (TDS) your project DNA will typically include a top-level tds.json file of the form:

{
    "default": {
        "port": 1407,
        "pouch": "pouch"
    },
    "development": {
        "use": {
            "watch": true
        }
    }
}

As you can see, the tds.json file includes a set of default values as well as environment-specific blocks. In the example above the typical Express application env value of development would trigger the server to set tds.use.watch to true.

NOTE: The tds prefix is implied for all values in the tds.json file.

Using the tibet config command with a tds. prefix will cause the entire set of config flags to be checked for reads, but only the tds.json file will be used for storage of new values. The tds.json file is not vended by the TDS to the client so values in the tds.json file are hidden from the client.

tibet_cfg.js (defaults)

If the tibet.json and tds.json files are so sparsely populated where do the rest of the configuration values come from?

The answer is the tibet_cfg.js file found in your version of TIBET. This file is typically found in the src/tibet/boot directory of your TIBET installation.

The tibet_cfg.js file is a series of calls to TP.sys.setcfg which define the default configuration values for TIBET.

When you run the CLI a TP.sys.setcfg method is built so calls in tibet_cfg.js run properly. This allows both the CLI and client-side runtime to share baseline configuration data. All environments load your tibet.json file. Only the TDS loads tds.json.

NOTE: Do not edit tibet_cfg.js. Edit tibet.json or tds.json instead.

Configuration Resolution

If you look back you'll see that you can configure TIBET via:

• tibet config (aka the tibet.json file).
• Your application's startup URL.
• The TP.boot.launch() method.
• tags in the application profile.

So who "wins" when these sources conflict?

Here's the processing order. Note that last one to set a particular value wins:

• tibet config (aka the tibet.json file).
• tags in the application profile.
• Any TP.boot.launch() method options.
• Your application's startup URL parameters (if boot.nourlargs !== true)

NOTE that the application's URL parameters are read only after launch() parameters and other values so boot.nourlargs will turn them off.

Descriptions for the majority of these are sparse, but usually sufficient. See the tibet_cfg.js file for more information.

Code

The configuration subsystem involves a common set of files for default values as well as the code supporting the various setcfg/getcfg APIs in TIBET.

~lib/src/tibet/boot/tds_loader_pre_template.js and ~lib/tds/tds_base.js contain the core setcfg and getcfg methods used by the client and server as well as their underlying property access methods.

Common configuration values from the library baseline are found in:

• ~lib/src/tibet/boot/tibet_cfg.js (TIBET client configuration)
• ~lib/tds/tds_cfg.js (TDS configuration baseline)

Individual projects also contain configuration files for overrides in:

• ~app/tibet.json (project client configuration)
• ~/tds.json (project TDS configuration)

Your project's load package files, found in ~app_cfg often contain <property> tags for configuration settings per boot config. A good example is the development.xml file in most projects.