Bug 856275

Description of problem:
We received some great feedback from a user on IRC/mailing list and wanted to capture the finer points of that feedback to enable users to run the sample node app locally.


Local Deployment:  I was expecting to clone the repo, run "node server.js" and have the project running locally on my machine.
1) Possibly add to the README that npm_global_module_list contains a list of globally installed packages
2) Add version information to npm_global_module_list for package versions.
3) Possibly add a section for local deployment.




Full feedback here:
Hi all,

First, thanks for providing OpenShift to the community. I haven't done much with it yet, but just started playing with a Node.js project hosted by OpenShift. I have a couple suggestions for improvement of the Node.js documentation. Please forgive me if I've overlooked anything, or missed something in the documentation.

My Initial Experience
===============
For context, I'd like to explain my initial experience with OpenShift's Node.js support. I created an account and logged in through the web interface. I created my first Node.js project through the web interface. After setting up my ssh keys and creating the project, I was given a git URL to clone onto my machine. This part was all good. I didn't encounter any roadbumps. Additionally, my project was deployed to OpenShift and I could visit the webapp. Great!

Local Deployment
=============
This is where I first encountered issues. I was expecting to clone the repo, run "node server.js" and have the project running locally on my machine. However, upon running the command, I discovered there was a dependency on the Express Node.js module. Apparently, Express is installed globally on OpenShift, and the dependency is satisfied on the server. However, in the project that is pulled in locally, there is no indication (that I could find) on the Express dependency outside the source code in server.js.

This isn't a huge problem. I can just add "express" to package.json and let npm install the dependency. But, here I run into another issue. Which version of Express should I install? As far as I could tell, there is no indication as to which version of Express OpenShift supports. After installing the latest version of Express, there are deprecation warnings in the code. Again, I can live with that. However, the example doesn't seem to work at runtime with the latest version of Express. I basically get a page of CSS. It doesn't want to transmit the page correctly locally.

Okay, so there's a solution. If I know the explicit version of Express OpenShift is using, I can add it to my package.json and install the dependency via npm and be good to go. However, as I mentioned above, it's not documented anywhere I could find. After a lot of digging around online, I found that I could ssh into the instance running my application. Once I ssh'd into the instance, I could inspect the version of Express installed to determine the version (it appears to be 2.5.8). This was a lot of research and digging to figure out which version of Express OpenShift supports.

Once I added the explicit dependency, I was able to run server.js successfully. However, I hadn't set an environment variable for OPENSHIFT_INTERNAL_IP to my loopback address, so the server didn't accept any incoming requests. After exporting this environment variable, I had achieved success! Everything seemed to work!

TL;DR
=====
- Either explicitly document the version of Express used globally on OpenShift, or move this dependency to package.json by default. Documentation somewhere in the template project would be ideal.
- This dependency issue would also apply to any other globally installed packages (e.g. Mongo)
- In the node quickstart documentation, add a bit about setting the OPENSHIFT_INTERNAL_IP on your local machine for local deployment and testing.

All of the issues I experienced are with local deployment of the template project, but IMHO I think a lot of people trying out the Node.js support for OpenShift may take this route (using the template sample project and deploying locally). A developer bringing their existing Node project with a package.json file already written probably wouldn't experience any of these issues.

Again, please take my suggestions as just that. And if I overlooked any documentation or am incorrect at all, my apologies. I'm just hoping to help make the OpenShift service better. Thanks again for providing this service to the community, and I look forward to continuing to see it evolve.

--