TIBET Logo

TIBET Data Server (TDS)

TIBET Server

wins

  • Powerful Node.js Express server with modular, plugin-based architecture.
  • Pre-configured plugins for security, authentication, logging, and more.
  • Specialized plugins supporting interactive development via TIBET Sherpa.
  • Fully integrated with CouchDB for a full TIBET+Express+Couch (TEC) stack.
  • Fully supported as part of the overall TIBET ecosystem.

contents

concepts

cookbook

Operation

code


concepts

For projects without an existing investment in a server technology or those looking to migrate to a Node.js-based solution we provide the TIBET Data Server (TDS).

There are good reasons for TIBET to include an optional server:

  • Browser security limitations severely restrict file-launched applications.
  • Traditional web servers are often designed for server-heavy processing.
  • TIBET's interactive development benefits from more Server integration.
  • Department-level applications and sales demos don't need a heavy server.
  • Offering a full-stack solution allows you to get a fully-supported stack.

We use the TDS in our daily development and as the default server for our Enterprise clients. It might be optional but it's powerful, extensible, and supported.

TDS Startup

TDS Startup


The TDS is pluggable, leveraging pre-built middleware components for logging, compression, session management, security, authentication, and more. Many of the TDS's plugins are themselves pluggable. For example, the authentication module wraps passport.js, letting you integrate with a wide variety of authentication approaches from OAuth2 to LDAP.

The TDS is designed to speed development with automatic route and mock generation. Using the TDS you can quickly serve static JSON or XML data behind public or private handlers, eliminating boilerplate for mocking static or dynamic data.

TIBET-specific TDS plugins are also leveraged to support fast development via the Sherpa. Pre-built handlers support bi-directional file change management, TIBET CLI invocation, TIBET Workflow System features, administrative APIs, and more.

Configuration

The TDS draws its configuration data from two files: tibet.json and tds.json. The tibet.json file contains TIBET's default configuration values and information in that file is shared by both client and server. The tds.json file is only available to the TDS.

For brevity we'll skip the tibet.json file. Here's a sample tds.json file.

{
    "default": {
        "port": 1407,
        "pouch": "pouch",
        "plugins": {
            "tds": [
                "couch",
                "tasks"
            ]
        }
    },
    "development": {
        "plugins": {
            "tds": [
                "cli",
                "couch",
                "patch",
                "tasks",
                "watch"
            ]
        },
        "use": {
            "couch": true,
            "watch": true
        },
        "port": 2345
    }
}

As you can see here, the TDS configuration file is segmented by 'environment'. Top-level keys must match the current Express env value or default values will be used.

Core Plugins

The TDS is a highly modular server whose functionality is driven by a set of prebuilt plugins you can adjust or replace to meet your needs:

//  ---
//  Plugins
//  ---

//  Shared options which allow modules to essentially share values like the
//  logger, authentication handler, etc.
options = {app: app, argv: argv, env: env};

plugins = TDS.getcfg('tds.plugins.core');
if (!plugins) {
    plugins = [
        "preload",
        "body-parser",
        "logger",
        "compression",
        "reconfig",
        "public-static",
        "session",
        "security",
        "view-engine",
        "authenticate",
        "private-static",
        "routes",
        "pouchdb",
        "tds",
        "proxy",
        "fallback",
        "errors"
    ];
}

Each TIBET project with a TDS component gets its own copy of these plugins, allowing you to adjust their behavior as you see fit.


cookbook

Starting The TDS

Use the tibet start command to start the TDS.

You can use tibet start --help to get the current set of options:

tibet start --help

TIBET-START(1)

NAME
       tibet-start - starts the project's TIBET Data Server

SYNOPSIS
         tibet start

DESCRIPTION
       Starts the project's TIBET Data Server, if available.

       Many TIBET dna templates provide a simple Node.js-based server. If
       the current project contains either a server.js file or can invoke
       'npm start' this command will try to start that server.

       The optional --env parameter lets you specify an environment setting
       such as development or production. The default is development.
       The current setting is announced in the server startup banner

       The --tds.port parameter lets you specify a port other than
       the registered TIBET Data Server port (which is port 1407).

       If your server includes TDS features you can optionally add
       command-line parameters to provide the various modules of the TDS
       with config data. All values for the tds are supported. See the
       output of tibet config tds for a list of current options.

                                               April 2016                                 TIBET-START(1)

By default the TDS uses port 1407 and will output the current application name, version, and 'environment' (env), along with the launch URL:

tibet start

...snipped...

info: hello 0.1.0 (development) running on TIBET at http://127.0.0.1:1407

Stopping The TDS

The server doens't require any special process to stop it. You can use ^C or whatever is appropriate for your particular platform:

^C
1518899202129 [7] TDS processing shutdown request (server)
1518899202156 [7] TDS shutting down HTTP server (server)
1518899202204 [7] TDS shutting down TDS middleware (server)
1518899202204 [7] TDS TDS middleware shut down (server)
1518899202204 [7] TDS shutdown complete (server)

Configuring The TDS

Use the tibet config command to query or configure TDS settings.

Query A Value

Supply a single value to the tibet config command:

tibet config tds.port
1407

Use the --env flag of tibet config to specify a particular 'environment' block.

Query All Values

Querying for all TDS settings via tibet config tds:

tibet config tds
{
    "tds.auth.strategy": "tds",
    "tds.cli.uri": "/_tds/cli",
    "tds.color.alert": "yellow",
    "tds.color.crit": "red",
    "tds.color.data": "grey",
    "tds.color.debug": "green",
    "tds.color.emerg": "red",
    "tds.color.error": "red",
    "tds.color.help": "cyan",
    "tds.color.info": "green",
    "tds.color.input": "grey",
    "tds.color.notice": "yellow",
    "tds.color.prompt": "grey",
    "tds.color.silly": "magenta",
    "tds.color.verbose": "cyan",
    "tds.color.warn": "yellow",
    "tds.color.warning": "yellow",
    "tds.cookie.key1": "T1B3TC00K13",
    "tds.cookie.key2": "31K00CT3B1T",
    "tds.https": false,
    "tds.job.uri": "/_tds/jobs",
    "tds.log.count": 5,
    "tds.log.file": "~app_log/tds-.log",
    "tds.log.format": "dev",
    "tds.log.level": "info",
    "tds.log.routes": false,
    "tds.log.size": 5242880,
    "tds.max_bodysize": "5mb",
    "tds.patch.root": "~",
    "tds.patch.uri": "/_tds/patch",
    "tds.port": 2345,
    "tds.pouch": "pouch",
    "tds.pouch.name": "tds",
    "tds.pouch.prefix": "./pouch/",
    "tds.pouch.route": "/db",
    "tds.proxy.map": null,
    "tds.secret.key": "ThisIsNotSecureChangeIt",
    "tds.session.key": "T1B3TS3SS10N",
    "tds.session.store": "memory",
    "tds.stop_onerror": true,
    "tds.use.mocks": false,
    "tds.watch.event": "fileChange",
    "tds.watch.heartbeat": 10000,
    "tds.watch.ignore": ["node_modules","TIBET-INF/tibet"],
    "tds.watch.root": "~app",
    "tds.watch.uri": "/_tds/watch",
    "tds.webdav.mount": "/",
    "tds.webdav.root": "~app",
    "tds.webdav.uri": "/_tds/webdav"
}

Set A Value

Set a value using tibet config =:

tibet config tds.port=2345
2345

Use the --env flag of tibet config to specify a particular 'environment' block. The default environment will be taken from your current shell.

The value you set should be echo'd back to the command line. If you don't see the value echo properly it was not set for some reason.

When you supply a value for a tds-prefixed setting that value will be stored in the tds.json file which is used only by the TDS. The client does not have access to this file.

Changing The Port

You can change the port for one-time startup using the --tds.port option:

tibet start --tds.port 3456

To change the port for a project permanently use the tibet config command:

tibet config tds.port=3456

Changing Logging Level

To change the logging level for a single session use the --tds.log.level flag:

tibet start --tds.log.level DEBUG

To change the level for a project permanently use the tibet config command:

tibet config tds.log.level=DEBUG

code

If you look at the prior list of plugins you'll see that there's a tds plugin in that list.

The tds plugin provides access to one or more "TDS extensions", a set of optional plugins which can be loaded to support things like proxying, pouchdb/couchdb, development file access, live-patching, and more.

These extentions are part of the TIBET library, not part of your project, so their functionality is fixed. The can be found in ~lib/etc/tds/plugins:

tds-cli.js
tds-couch.js
tds-patch.js
tds-tasks.js
tds-watch.js
tds-webdav.js

TDS plugins are controlled by TIBET Configuration settings, in particular the overall tds.plugins.tds value.

If the value for tds.plugins.tds is invalid or empty no TDS plugins are loaded. Using a value of * will cause all plugins to load. Otherwise the specific list should be provided as an array (usually in tds.json):

"plugins": {
    "tds": [
        "couch",
        "tasks"
    ]
}
tds-cli

The tds-cli plugin allows you to invoke tibet commands from the TIBET Sherpa, a feature used by the Sherpa to support features like adding new tags or types to your application. This feature requires you to log in to the TDS for security.

tds-couch

The tds-couch plugin integrates the TDS with CouchDB, allowing you to build applications that leverage both the TDS and CouchDB.

tds-patch

The tds-patch plugin provides the Sherpa with access to patch functionality which supports pushing client-side code changes to the server for storage. When you push a code, style, or template change in the sherpa the patch feature is invoked.

tds-tasks

The tds-tasks plugin is the foundation of the TIBET Workflow System (TWS), a lightweight workflow engine driven by state changes in CouchDB relative to 'job' documents and their related workflow and task definitions.

tds-watch

The tds-watch plugin provides the TDS with support for TIBET's 'live patching' functionality as well as automatic push to CouchDB. When the watch plugin detects a change it notifies any connected TIBET clients and those clients can then optionally load the changes and refresh affected components. Full reloads are never done.

tds-webdav

The tds-webdav plugin provides simple WebDAV support. It's currently disabled.