TIBET Logo

TIBET+CouchDB

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
Database Operations
Development

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.


TIBET+CouchDB

TIBET+CouchDB Example


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 framework 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 Sherpa you can browse your CouchDB servers, databases, views, documents, and more. Drag a view into the Sherpa'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.

TIBET+CouchDB

Sherpa CouchDB Login


Upcoming improvements will also let you manage CouchDB directly from the Sherpa, 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.

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":"2.0.0","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  --dna couch
$ cd 
$ tibet init

Database Operations

Confirming CouchDB Is Running

Use curl or a similar command to confirm CouchDB is accessible:

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

{"couchdb":"Welcome","version":"2.0.0","vendor":{"name":"The Apache Software Foundation"}}

Creating A Project Database

Use the tibet couch createdb command to construct the project database. Replace `` with your application name or whatever you want as the application database name:

$ tibet couch createdb
CouchDB url [http://127.0.0.1:5984] ?
using base url 'http://127.0.0.1:5984'.
Database name [] ?
creating database: http://127.0.0.1:5984/
database ready at http://127.0.0.1:5984/

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 createdb
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'.
Database name [] ?
creating database: http://127.0.0.1:5984/
database ready at http://127.0.0.1:5984/

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}

Pushing Your App To CouchDB

To store your application code in CouchDB for execution you need to push your application to the database. 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
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

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

tibet couch pushapp
CouchDB url [http://127.0.0.1:5984] ?
using base url 'http://127.0.0.1:5984'.
Database name [] ?
Application name [] ?
marshalling content for: http://127.0.0.1:5984//_design/
application loaded at http://127.0.0.1:5984//_design/

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 [] ?
Delete database [http://127.0.0.1:5984/] ? Enter 'yes' to confirm: yes
deleting database: http://127.0.0.1:5984/
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//_design/, replacing db_name and appname appropriately.

TIBET+CouchDB Design Doc

TIBET+CouchDB Design Doc


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 three (3) ways to run your application: from the file system, via the TDS, and via CouchDB. The easiest during development is to leverage the TDS and then push to your CouchDB database for testing but we'll cover all three here.

File Launch

To run from the file system you'll need to follow the instructions found in the Zero Server document. Your CouchDB project can be run (subject to JSON data access) from the file system provided you are using TIBET's virtual URIs.

CouchDB Launch

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

TIBET+CouchDB

TIBET+CouchDB Example


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:  0.1.0 (development) running on TIBET at http://127.0.0.1:1407

Freezing TIBET 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 TIBET 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.