bluemix-todo-apps - node overview

TodoMVC using Backbone, CouchDB/MongoDB and a node back-end, running on Bluemix.

Refer to the README.md file in the parent directory (eg, bluemix-todo-apps/README.md) for general instructions regarding this application and the database service it requires.

This application supports both Mongo DB and Couch DB (Cloudant) as a backend.

How it Works

Add items to the todo list by typing into the box and pressing Enter
Mark items as complete by clicking the checkmark to the left of the corresponding item.
Delete items by clicking the 'X' to the right of the corresponding item that appears on hover.
Edit existing todo items by double-clicking on the corresponding item.

Running the app on Bluemix

Create a Bluemix Account

Sign up for Bluemix, or use an existing account.
Download and install the Cloud-foundry CLI tool
If you have not already, download node.js and install it on your local machine.
To deploy the app, you will need the jbuild tool installed.

To install jbuild on Windows, use the command
```
npm -g install jbuild
```
To install jbuild on Mac or Linux, use the command
```
sudo npm -g install jbuild
```
Clone the app to your local environment from your terminal using the following command
```
git clone https://github.com/IBM-Bluemix/todo-apps.git
```
cd into the node folder of this newly created directory
Now its time to decide what database service you would like to use as your datastore. I will go through them one-by-one here:

Cloudant

Cloudant is IBM's NoSQL CouchDB solution. The following command will create a Cloudant service called todo-couch-db, bind it to your app, and start your app:
```
$ jbuild deploycloudant appName
```
Compose.io Mongo

Compose.io is IBM's providor of a number of fully-managed, open source DB solutions. The following steps walks you through creating a Compose Mongo instance:
- Create a Compose.io account for a 30-day free trial and select MongoDB as your database
- Once your Mongo deployment has been provisioned, create a DB called todoDB
- Navigate to the Users tab of your new DB and select Add User. Fill out your own username and password.
- Navigate to the Admin tab and note the host and port number of your primary replica set.
- Go to the Bluemix catalog, select the 'MongoDB by Compose' service, and do the following:
  - Leave the app unbound
  - Name the service todo-compose-mongo-db
  - Fill out your credentials with the info from the previous steps
  - Click 'Create'
- Now run the following command to bind this service to your app and start it up:
```
$ jbuild deploycompose appName
```
MongoDB

The following command will create a MongoDB service called todo-mongo-db, bind it to your app, and start your app:
```
$ jbuild deploymongo appName
```

Note: If the jbuild command exits the first time without deploying your app due to npm install, just run it again.

Running the app locally

To run the app locally, you will first need to have a CouchDB server and/or a Mongo DB server running locally. The code assumes that the database is using the default port.

After installing the DB server locally, and installing the app via steps 3, 5, and 6 above, you can run it with the command:

node server -d cloudant

for Couch DB or

node server -d mongo

for Mongo DB.

You should see the output like the following written to the console:

bluemix-todo-apps-node: VCAP_SERVICES environment is not set
bluemix-todo-apps-node: using database:  http://127.0.0.1:5984/todos
bluemix-todo-apps-node: server starting: http://localhost:6024

You can use the URL listed on the last line to access the application. It stores the data locally in the database listed on the second line.

About the app

CoffeeScript

This application is written in CoffeeScript and compiled into JavaScript. The CoffeeScript source is available in the lib-src directory, and the compiled JavaScript files are available in the lib directory.

The CoffeeScript files break down as follows:

cli.coffee - Handles the command-line invocation of node server; parses the command line and constructs a call to the server module.
couch-db.coffee - Handles interaction with the CouchDB database. A DB object is created to handle the interaction, which has a set of SCRUD methods (search/create/read/update/delete) to access the data.
mongo-db.coffee - Handles interaction with the Mongo database. A DB object is created to handle the interaction, which has a set of SCRUD methods (search/create/read/update/delete) to access the data.
server.coffee - Handles the HTTP server
tx.coffee - Provides a transaction object which turns HTTP requests into Database operations.
utils.coffee - Provides some utility functions used in all the modules.

npm Packages

The application makes use of the following packages from npm:

express - A framework to build web server applications
nano - A library to interface with CouchDB
nopt - A library to parse command-line arguments
ports - A library to consistently manage name http ports
q - A promises library
underscore - A utility belt library with lots of handy functions
monk - A library to interface with Mongo DB

Promises

This application makes heavy use of Q promises to handle async calls. Promises are explained in depth on Q's project page and an introduction to promises is available at the http://promisejs.org site.

Hacking

If you want to modify the source to play with it, you'll also want to have the jbuild program installed.

To install jbuild on Windows, use the command

npm -g install jbuild

To install jbuild on Mac or Linux, use the command

sudo npm -g install jbuild

The jbuild command runs tasks defined in the jbuild.coffee file. The task you will most likely use is watch, which you can run with the command:

jbuild watch

When you run this command, the application will be built from source, the server started, and tests run. When you subsequently edit and then save one of the source files, the application will be re-built, the server re-started, and the tests re-run. For ever. Use Ctrl-C to exit the jbuild watch loop.

You can run those build, server, and test tasks separately. Run jbuild with no arguments to see what tasks are available, along with a short description of them.

Troubleshooting

To troubleshoot your Bluemix app the main useful source of information is the logs. To see them, run:

  $ cf logs <application-name> --recent

License

Apache License, Version 2.0

Privacy Notice

The TodoMVC node sample web application includes code to track deployments to Bluemix and other Cloud Foundry platforms. The following information is sent to a Deployment Tracker service on each deployment:

Application Name (application_name)
Space ID (space_id)
Application Version (application_version)
Application URIs (application_uris)

This data is collected from the VCAP_APPLICATION environment variable in IBM Bluemix and other Cloud Foundry platforms. This data is used by IBM to track metrics around deployments of sample applications to IBM Bluemix. Only deployments of sample applications that include code to ping the Deployment Tracker service will be tracked.

Disabling Deployment Tracking

Deployment tracking can be disabled by removing require("cf-deployment-tracker-client").track(); from the beginning of the server.js file at the root of this repo.

ibmkaga / CloudDevOps

readme