Bug 856275 - Nodejs cartridge self-documentation - Request to add enough data to enable users to test the sample apps locally
Nodejs cartridge self-documentation - Request to add enough data to enable us...
Status: CLOSED CURRENTRELEASE
Product: OpenShift Origin
Classification: Red Hat
Component: Containers (Show other bugs)
2.x
Unspecified Unspecified
low Severity low
: ---
: ---
Assigned To: Ram Ranganathan
libra bugs
: Triaged
Depends On:
Blocks:
  Show dependency treegraph
 
Reported: 2012-09-11 11:35 EDT by Nam Duong
Modified: 2015-05-14 18:59 EDT (History)
6 users (show)

See Also:
Fixed In Version:
Doc Type: Bug Fix
Doc Text:
Story Points: ---
Clone Of:
Environment:
Last Closed: 2012-11-06 13:50:00 EST
Type: Bug
Regression: ---
Mount Type: ---
Documentation: ---
CRM:
Verified Versions:
Category: ---
oVirt Team: ---
RHEL 7.3 requirements from Atomic Host:
Cloudforms Team: ---


Attachments (Terms of Use)

  None (edit)
Description Nam Duong 2012-09-11 11:35:08 EDT
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.

--
Comment 1 Ram Ranganathan 2012-09-25 14:01:49 EDT
Fixed with pull request: 
    https://github.com/openshift/crankcase/pull/529

Waiting on merge.
Comment 2 Jianwei Hou 2012-09-27 04:06:29 EDT
Verified on devenv_2242

Steps:
1. Create a nodejs app
2. In app's local repo, check npm_global_module_list and README files
in npm_global_module_list, there are a list of modules and instructions for getting module versions
in README, there is a instruction to setup application locally
3. Follow the instruction to setup app locally.
4. Start app, and check app is running locally
node server.js
curl 127.0.0.1:8080

Result:
App is setup and run locally
..........................
<h1>
    Welcome to OpenShift
  </h1>
  <p>
    Place your application here
  </p>
  <p>
    In order to commit to your new project, go to your projects git repo (created with the rhc app create command).  Make your changes, then run:
  </p>
  <pre>
...........................
Comment 3 Peter Ruan 2012-09-27 12:27:06 EDT
verified on devenv_2236

it's not fesible to have do #2.

Note You need to log in before you can comment on or make changes to this bug.