ID-56, Documentation Updating for Dashboard 2.0

README.md

@@ -35,6 +35,7 @@ With OpenMRS ID, we are able to provide access to a huge variety of software pro
 * Node.js version in the 0.8.x tree (id.openmrs.org runs Node v0.8.26)
 * LDAP directory (tested with OpenLDAP), additionally supporting extensible objects and password policies
 * MySQL database
+* MongoDB database
 * SMTP access
 
 ##License:

development-guide.md

@@ -0,0 +1,69 @@
+Development Instructions of Dashboard
+===
+
+Dashboard is a typical [Node.js][1] web application that utilizes [Express.js][0] framework.
+
+### Key Packages
+As you may know, a Node.js application depends heavily on the modules it uses, you may take a took in `package.json`.
+
+Here are some important ones,
+
++ [Express.js][0], The framework we are using.
+    Currently, we are using the Express3, as we oringally used Express2, and some functions were lost durying the migration. We used some packages to replace the missing functionalities. Like, [EJS-locals](https://github.com/RandomEtc/ejs-locals), [connect-flash](https://github.com/jaredhanson/connect-flash).
++ [Mongoose][3], The mongodb object modeling tool.
++ [Sequelize.js][4], Package for easily communicating with MySQL.
++ [Async.js][2], As all I/O operations in Node.js all asynchronous, we use the Async.js module to do the asynchronous control flow.
++ [Lo-Dash][5], Node.js utility library.
++ [Formage][6], Mongoose monitoring tools.
++ [Mocha](http://visionmedia.github.io/mocha/), [Chai](http://chaijs.com/), Packages that used for testing.
+
+### Project Structure
+Currently, we organize the code this way.
+
+```
+/.                          where all documentation and script lies
+--/app                      all basic funtional source files
+----/app/model              where all Mongoose model lies
+----/app/routes             basic routes files
+----/app/system-modules     the system modules
+----/app/user-modules       optional function add-ons
+--/logs                     the log files
+--/resoure                  static web resouce
+--/test                     all test source files
+--/views                    webpage templates
+```
+
+Also, for any specifc system-module/user-module, it will have alike sub-structure, you may take a deep look yourself.
+
+### Testing
+The testing files are under `test` folder. If you want to run it, first you should add a `conf.js` under this folder.
+
+And the `Makefile` contains the script for running tests, you may run test easily by `make test`.
+
+### Development Rules
+Whatever by the design or due to history, we have some implicit rules.
+
++ Code style, we are following the [Felix's](http://nodeguide.com/style.html). You should follow it in most cases. However, remember it's not like the absolute laws that you cannot violate, it's just a guideline.
+
++ Global variables, for historical reason, we used a global variable `global.__commonModule` to store the path of `openmrsid-common.js`, which requires other files, and provide common share for few important instance, like the `app` object of Express. 
+
+    However, except from the convenince it brought, it may cause problems for testing and strong coupling. A suggestion is to directly require files in those functional files that might be used in other places. But you may use them in routes files.
+
++ Routes structure, we tend to split different logic of routes into different files. You may refer details in the project.
+
++ Issue tracking, you'd better open a corresponding issue for a PR, [here](issues.openmrs.org/browse/ID) 
+
++ Comments, it's a good habbit to constantly add explanatory comments. When a part of logic is too long, and when some code is complicated, just add few comments. And for some functions that maybe used externally, you may add full [JSDoc](http://en.wikipedia.org/wiki/JSDoc).
+
+### Helpful Tools
+
+For keeping a good code style, [JSHint](http://www.jshint.com/) is highly recommended, also if you want to auto beautify the code, you may use [JS-beautify](https://github.com/beautify-web/js-beautify).
+
+
+[0]: http://expressjs.com/
+[1]: http://nodejs.org/
+[2]: https://github.com/caolan/async
+[3]: http://mongoosejs.com/
+[4]: http://sequelizejs.com/
+[5]: http://lodash.com/
+[6]: https://github.com/TheNodeILs/formage

installing-openmrsid.md

@@ -1,56 +1,111 @@
 Installing OpenMRS ID
 =====
 
-(The following steps are written for and tested on Ubuntu 13.10)
+(The following steps are written for and tested on Ubuntu 13.10 & 14.04 & 12.04)
 
 1. Install and configure OpenLDAP by [following this guide][0]. 
 
 2. Install a mysql server, then create a database. This database will need to be specified in OpenMRS ID's `conf.js` later on:
 
     ```
     apt-get install mysql-server
-    mysql -uroot
+    mysql -u root -p
     > CREATE DATABASE id_dashboard
     > CHARACTER SET utf8
     > DEFAULT COLLATE utf8_general_ci;
     ```
+
+    And add a user for that database
+    ```
+    > CREATE USER 'username'@'localhost' IDENTIFIED BY 'some_pass';
+    > GRANT ALL PRIVILEGES ON id_dashboard.* TO 'username'@'localhost' WITH GRANT OPTION;
+    ```
+
+3. Install a MongoDB server and configure it:
 
-3. Install Node. For development environments, I use [nvm][1]. Install the latest from the Node 0.8.x tree:
+    For installation, you may just refer the [official documentation][3].
+    Then,
+
+    Turn on the auth mechanism, if you use the configuration file, modify it. By default, it should lie in '/etc/mongod.conf'. Find and uncomment this line.
+
+    ```
+    auth = true
+    ```
+
+    Connect to mongo
+
+    ```
+    mongo admin
+    ```
+
+    Create the root user
+
+    ```
+    db.createUser( {
+        user: 'userNameHere',
+        pwd: 'passwordHere',
+        roles: [
+            { role: 'root', db: 'admin'}
+        ]
+    })
+    ```
+
+    You can check the user by `db.auth('username', 'password')`
+
+    Switch to the db you want,
+
+    ```
+    use yourDB
+    ```
+
+    Then create the user dashboard needs
+
+    ```
+    db.createUser( {
+        user: 'userNameHere',
+        pwd: 'passwordHere',
+        roles: [
+            { role: 'readWrite', db: 'yourDB'}
+        ]
+    })
+    ```
+
+4. Install Node. For development environments, I use [nvm][1]. Install the latest from the Node 0.8.x tree:
 
 	 ```
-     curl https://raw.githubusercontent.com/creationix/nvm/v0.6.1/install.sh | sh
+     curl https://raw.githubusercontent.com/creationix/nvm/v0.13.1/install.sh | bash
 
      # Restart your terminal session
      nvm install v0.8
      ```
-
-4. Clone [openmrs-contrib-id][2] and enter the project directory.
+
+     You may experience problems that reports "No command 'nvm' nvm found...", there might be some problem happened to your bash configuration files. Usually it's easy to solve this by just adding this line to your '.bashrc'.
+     ```
+     [[ -s $HOME/.nvm/nvm.sh ]] && . $HOME/.nvm/nvm.sh
+     ```
+
+5. Clone [openmrs-contrib-id][2] and enter the project directory.
 
 	```
     git clone https://github.com/openmrs/openmrs-contrib-id.git
     cd openmrs-contrib-id
     ```
 
-5. Install project dependencies. This uses the `npm-shrinkwrap.json` file in the project to ensure the same dependency versions are installed that we use in production. The LDAP module we use needs to be manually built, as well.
+6. Install project dependencies. This uses the `npm-shrinkwrap.json` file in the project to ensure the same dependency versions are installed that we use in production.
+
+    First, the [LDAP][4] module, which has C and libldap requirements, needs few packages for building. On Ubuntu, **make sure the `build-essential`, `libldap2-dev`, and `uuid-dev` packages are installed**.
+
+    Run this and wait.
 
     ```
     npm install
     ```
 
-6. Build the LDAP module, which has C and libldap requirements. On Ubuntu, make sure the `build-essential`, `libldap2-dev`, and `uuid-dev` packages are installed, then run:
-
-	```
-	cd node-modules/LDAP
-	node-waf configure
-	node-waf build
-	cd ../..
-	```
-
 7. Copy `app/conf.example.js` to `app/conf.js`. Edit `conf.js` and modify configuration with:
 
 	1. LDAP credentials for the `omrsid` account
 	2. LDAP resource uri's (e.g. replace `dc=example` with `dc=openmrs,dc=org`)
-	3. Mysql database name and credentials
+	3. Mysql/MongoDB database name and credentials
 	4. Postfix mail sending credentials and port
 	5. reCAPTCHA keys (if you have them—they are required for signup)
 
@@ -66,3 +121,5 @@ Installing OpenMRS ID
 [0]: https://gist.github.com/elliottwilliams/9548288
 [1]: https://github.com/creationix/nvm
 [2]: https://github.com/openmrs/openmrs-contrib-id
+[3]: http://docs.mongodb.org/manual/tutorial/install-mongodb-on-ubuntu/
+[4]: https://github.com/jeremycx/node-ldap

package.json

@@ -40,7 +40,7 @@
     "express-debug": "~1.1.0"
   },
   "scripts": {
-    "test": "mocha app/**/*.test.js"
+    "test": "make test"
   },
   "repository": {
     "type": "git",