TIBET

TIBET+CouchDB

Wins

• Turnkey NoSQL application architecture combining TIBET and CouchDB.
• Highly-scalable server with built-in conflict detection and replication.
• Offline operation with online syncing thanks to PouchDB integration.
• Integrated lightweight workflow via the TIBET Workflow System (TWS).
• Command-line support via tibet couch and tibet tws commands.

Contents

Concepts

Cookbook

Getting Started

• Installing CouchDB
• Creating A TIBET+CouchDB Project

Database Operations

• Confirm CouchDB Is Running
• Creating A Project Database
• Pushing Your App To CouchDB
• Removing Your Project Database
• Viewing Your App In CouchDB

Development

• Running Your CouchDB App
• Freezing Library Code
• Thawing Library Code
• Adding Workflow Support
• Adding CORS Support

code

Concepts

Before the advent of the web most enterprise applications were built with a Client/Server architecture. The servers? Relational databases like Oracle, Sybase, and DB2. The clients? Desktop applications built with PowerBuilder, Delphi, Visual C++, et. al. On the wire? Pure data sent on transactional boundaries.

Today's terminology of microservices, REST APIs, and NoSQL tends to obscure it but in many ways the web is returning to that Client/Server model, one where powerful clients (HTML5 browsers) access server-side logic (RESTful microservices) and the content on the wire (XML or JSON documents) is pure data sent on transactional boundaries.

CouchDB was designed specifically for this "Web Client/Server" era. It's a NoSQL database that communicates via HTTP and JSON. A database with built-in replication, version-based conflict detection, and change notification. A database whose views, queries, and procedures are written in JavaScript. A database that can host web applications itself.

TIBET+CouchDB isn't a pure couchapp per se, there are no show or list functions involved; to use modern terminology, it's a spin on a "serverless" configuration where CouchDB provides persistence and TIBET provides the "edge computing" application infrastructure.

We're not suggesting that every web application is a suitable target for this approach, but a surprising number of small business and department-level applications formerly built using VisualBasic, Delphi, etc. are perfect targets for TIBET+CouchDB.

The screen above shows a default TIBET project startup page but a closer look shows this application launched directly from CouchDB with no application server or other components required. TIBET handles the client logic, including running offline if needed. CouchDB handles the session, storage, clustering, and replication. For customer-facing versions put it all behind nginx or a similar reverse proxy and you're good to go.

Combining TIBET with CouchDB makes good technical and business sense.

CouchDB provides scalability, clustering, versioning, replication, and change notification. TIBET provides a stack powerful enough to build pure Client/Server web applications.

With fewer moving parts your development, deployment, and production operation are simplified. With a more distributed architecture you get increased scalability, increased fault tolerance, faster development, and lower total cost of ownership.

With TIBET+CouchDB you can progress seamlessly from prototype to production, from demo app to department app to Cloud app.

To further simplify your efforts, the TIBET CLI's couch and tws commands let you interact with CouchDB directly. Using the CLI you can manage views, documents, couchapps, the TIBET Workflow System's flow and task definitions, and much more.

Via the TIBET Lama you can browse your CouchDB servers, databases, views, documents, and more. Drag a view into the Lama's UI and you get an instant master/detail table and form. Drag a JSON document into the UI and get a simple CRUD form. It's that simple.

Upcoming improvements will also let you manage CouchDB directly from the Lama, replacing the need for a separate administration tool.

Cookbook

Getting Started

Installing CouchDB

For local development purposes you can install the latest CouchDB for your platform by following the instructions at the CouchDB Home Page.

Configuring CouchDB

CouchDB comes configured right out of the box to perform most common tasks. Note that, as of Couch 3.X, that Couch no longer defaults to running the 'admin party' for security reasons. Therefore, in order to make your TIBET+CouchDB app initially accessible for developer purposes, you must set it to use HTTP Basic authentication. To do so:

1. Edit CouchDB's .ini file for your installation (or use CouchDB's Fauxton administration tool) and, under the [httpd] section, add the following key/value pair:

WWW-Authenticate = Basic realm="administrator"

2. Ensure that the TIBET couch.auth_scheme configuration variable is set to basic. This is the default, so it shouldn't be a problem.

We recommend using another authentication scheme for production system. TIBET supports CouchDB cookie authentication. To use it, make the following changes:

1. Change the TIBET couch.auth_scheme configuration variable is to cookie.

2. Change your CouchDB installation to use SSL. Note that, the standard CouchDB SSL configuration will run CouchDB under port 6984 instead of 5984, so make the necessary adjustments in the following examples.

To configure the latest CouchDB to use SSL, follow the instructions at: HTTPS (SSL/TLS) Options.

Testing CouchDB Installation

When you're done use curl or a similar command to confirm CouchDB is ready:

$ curl -X GET http://127.0.0.1:5984

{"couchdb":"Welcome","version":"3.1.0","git_sha":"ff0feea20","uuid":"ea5e561327bce0241dfe5e301c80efe2","features":["access-ready","partitioned","pluggable-storage-engines","reshard","scheduler"],"vendor":{"name":"The Apache Software Foundation"}}

Creating A TIBET+CouchDB (CouchDB-bootable) Project

TIBET+CouchDB projects are built using TIBET's standard tibet clone/tibet init approach. Simply add --dna couch to get a CouchDB-bootable project:

A 'default' TIBET project can also connect to and observe change feeds from CouchDB. Only use the 'couch' DNA if you also intend to launch your application directly from CouchDB.

$ tibet clone {{appname}} --dna couch
$ cd {{appname}}
$ tibet init

Database Operations

Pushing Your App To CouchDB

To store your application code in CouchDB for execution you need to push your application to the database server. Before you can push and successfully launch your application however you need to marshal the various resources necessary.

Application Resources

If you'll be launching out of CouchDB using a production (build) profile you'll need to do a tibet build of your application to create the proper packages.

tibet build --minify

Library Resources

To ensure all the various library packages are available for use by your application you need to use tibet freeze to ensure a copy of the TIBET code is available in the proper location for upload.

tibet freeze --raw --force

Pushing Application to CouchDB

With your resources marshalled, use tibet couch pushapp to push to the database:

tibet couch pushapp {{appname}}
CouchDB url [http://127.0.0.1:5984] ?
using base url 'http://127.0.0.1:5984'.
marshalling content for: http://127.0.0.1:5984/{{db_name}}/_design/{{appname}}
application loaded at http://127.0.0.1:5984/{{db_name}}/_design/{{appname}}

If you get an error stating that You are not a server admin. one option is to adjust your parameter values to include a valid username/password combination for a CouchDB administrator. We've used admin and notsecure below:

tibet couch pushapp {{appname}}
CouchDB url [http://127.0.0.1:5984] ? http://admin:notsecure@127.0.0.1:5984
using base url 'http://admin:notsecure@127.0.0.1:5984'.
marshalling content for: http://127.0.0.1:5984/{{db_name}}/_design/{{appname}}
application loaded at http://127.0.0.1:5984/{{db_name}}/_design/{{appname}}

A more secure approach is to export COUCH_USER and COUCH_PASS environment variables to keep from exposing authentication values directly.

export COUCH_USER={username}
export COUCH_PASS={password}

NOTE: The first time this command is run, it will automatically create a CouchDB database to hold your application. This will be named the same as your project name.

NOTE: If you are using a pre-existing database to store your application, you must use a project name that matches that database name.

Removing Your Project Database

Before proceeding…are you SURE?

Really SURE?

Use tibet couch removedb and use the full word yes to confirm when prompted:

$ tibet couch removedb
CouchDB base [http://127.0.0.1:5984] ?
using base url 'http://127.0.0.1:5984'.
Database name [{{appname}}] ?
Delete database [http://127.0.0.1:5984/{{appname}}] ? Enter 'yes' to confirm: yes
deleting database: http://127.0.0.1:5984/{{appname}}
database removed.

Viewing The CouchDB Design Document

When you push your application code to CouchDB it is stored in the form of a CouchDB design document. You can view this document by navigating to a URL of the form: http://127.0.0.1:5984/{{db_name}}/_design/{{appname}}, replacing db_name and appname appropriately.

As the screenshot here shows, your application's resources are stored as attachments to the design document. You normally don't need to interact with your application in this environment however, TIBET's tools do all the heavy lifting for you.

Development

Running Your CouchDB App

There are actually two (2) ways to run your application: via the TIBET Data Server (TDS) and via CouchDB directly (which is what we've been documenting so far in this document). The easiest during development is to leverage the TDS and then push to your CouchDB database for testing but we'll cover both here.

CouchDB Launch

Launching your application directly from CouchDB is a simple matter of accessing http://127.0.0.1:5984/{{db_name}}/_design/{{appname}}/index.html from a supported browser, provided that you've previously used tibet couch pushapp to store a copy in the project database.

So, for example, if your app was named couchtest, you would use the following URLs to launch the application:

Built, production application:
http://127.0.0.1:5984/couchtest/_design/couchtest/index.html

Developer application:
http://127.0.0.1:5984/couchtest/_design/couchtest/index.html#?boot.profile=development@developer

TIBET Data Server (TDS) Launch

While TIBET can be configured to automatically push new changes on the file system into the database we think it's a better idea to develop on the TDS and push to the database intermittently, perhaps when you need to integration test the application.

To run the application via the TDS first confirm CouchDB is running.

With CouchDB running use tibet start to run the TDS:

$ tibet start

                                 ,`
                           __,~//`
  ,///,_            .~////////'`
 '///////,       //////''`
        '//,   ///'`
           '/_/'
             `
   ////////////////////     ///////////////////  ////
   `//'````````````///      `//'```````````````  '''
    /`              //       /'
   /                //      '/
  ,/____             /'    ,/_____
 ////////;,,,_       //   ,//////////;,_
            '`'/,_   '/              `'///,_
                `'/,_ /                   '//,
                   '/,/,                    '/_
                     `/,                     `/,
                       '                      `/
                                              '/
                                               /
                                               '

info: {{appname}} 0.1.0 (development) running on TIBET at http://127.0.0.1:1407

Freezing Library Code

Normally you develop with TIBET being pulled into your application via a link to the standard node_modules directory. Pushing all of this directory into your database is clearly not a good idea so TIBET provides a way to freeze a copy of the specific library code your application requires.

$ tibet freeze --raw --force

--force specified, cleansing/rebuilding target directory.
freezing packaged library resources...
freezing library dependencies...
freezing runtime library resources...
freezing raw library source...
freezing raw library tests...
freezing raw library demos...
updating embedded lib_root references...
updating project lib_root setting...

Thawing Library Code

If you want to return your project to working with a dynamic version of TIBET you can thaw it via the tibet thaw command. Note that because it removes files the thaw command requires use of the --force flag:

tibet thaw --force
updating embedded lib_root references...
updating project lib_root setting...
Application thawed. TIBET now boots from node_modules.

Adding Workflow Support

TIBET's CouchDB integration also includes a lightweight workflow engine as part of the TIBET Data Server (TDS) known as the TIBET Workflow System (TWS).

To run the TWS you must be running the TDS as part of your application architecture, however you can choose the configuration. In other words, you can launch your application directly from CouchDB and leverage the TDS purely for its workflow capabilities or you can use a more traditional approach and launch your application from the TDS, keeping CouchDB behind the app/workflow server. Either model will work.

See the documentation on the TIBET Workflow System (TWS) for details.

Adding CORS Support

See https://github.com/pouchdb/add-cors-to-couchdb

Code

There are a number of areas of integration between TIBET and CouchDB.

The TIBET CLI commands tibet couch and tibet tws provide command line access to general CouchDB functionality and TWS functionality respectively. You'll find these commands in ~lib/src/tibet/cli.

The TIBET Workflow System (TWS) is a combination of command line tools, TIBET Data Server (TDS) plugins, and prebuilt template files.

The TDS plugin most responsible for TWS operation is the tasks.js plugin found in ~lib/tds/plugins. There's also a couch.js plugin for the TDS which handles CouchDB change feed monitoring and other operations not directly associated with the TDS.

TIBET's TDS plugins and CLI commands make heavy use of the helpers found in ~lib/etc/helpers/couch_helpers.js.

Template files for both "couchapps" and the TWS can be found in the library DNA directories for couch and default projects in ~lib/dna under the couch directories for each DNA type. You'll find this couch directory at the top level (~) of your project.