Difference between revisions of "Orion/Node/Getting started"

From Eclipsepedia

< Orion‎ | Node
Jump to: navigation, search
(Running the tests)
(Developing a node.js application)
Line 51: Line 51:
 
#Use <code>node start yourApp.js</code> to start your application.
 
#Use <code>node start yourApp.js</code> to start your application.
 
#Use <code>node list</code> to monitor all the applications you've started and still running.
 
#Use <code>node list</code> to monitor all the applications you've started and still running.
#Use <code>node stop PID</code> ot stop an application if you want to force it to stop.
+
#Use <code>node stop PID</code> to stop an application if you want to force it to stop.
  
 
== Debugging a node.js application ==
 
== Debugging a node.js application ==

Revision as of 10:49, 18 January 2013

Orionode is a minimal, single-user sever deployment of Orion used for Node development with Orion's editing environment.

Contents

Features

  • Basic Navigator operations (Create file/folder, delete file/folder, copy/move/rename a file)
  • Basic Editor operations (Edit file, save file, ETags)
  • Plugin operations (Install/uninstall plugins)
  • Shell command for launching a node app (type help node in the Shell page to find out more)
  • Shell command for supporting npm. (works the same as the usual npm console command).
  • Gzip on server traffic to reduce download times
  • Concatenation and Minification of pages (requires a manual step)
  • Client caching for static HTML+JS content (cache time: 2 hours)

Requirements

  • Node.js and npm.
  • A modern web browser with Web Socket support (for example: Firefox 15, Chrome 22, Internet Explorer 10, Safari 6).

Getting Orionode and starting it

  1. Get the Orion source. You only need to get the client source.
  2. Open a command shell and change directory to org.eclipse.orion.client/modules/orionode.
  3. Run npm install command to automatically download Orionode's dependencies. This will take a few minutes.
    • If you're not interested in developing the server, you can instead run npm install --production, which omits the dev-time dependencies for a smaller download.
  4. Verify the default path of npm-cli.js.
    1. In the same directory, open the server.conf file. The default value of npm_path is ../lib/node_modules/npm/bin/npm-cli.js. This is the npm module path to support npm command. Make sure if this default path is correct, relative to the node executable in your environment.
    2. If you installed a recent version of Node.js, npm should be installed automatically. The default value of npm_path should work in most cases.
    3. How to confirm: For instance, if you are using Bash just type which npm and see where the command is. The command should eventually use the npm-cli.js file. Make sure your npm-cli.js matches the npm_path value. If not, then change the npm-path value to match your environment. It can be either an absolute path or a path relative to your node executable.
  5. Create a one-line "password.txt" file containing a secret password. If you do not want a separate file for password, you can still define that in the server.conf or just leave the pwd value as empty.
  6. Launch the Orionode server.
    • If you installed by checking out the Git repo, run this command from a shell node server.js [-p port] [-w directory] [-password password.txt].
    • If you're not passing any command-line arguments to the server, you can just use npm start.
  7. Go to http://localhost:8081 (or whatever port you chose) in your web browser to start using Orionode.

Server command line arguments

All these arguments are optional.

-p or -port
The port that the Orion server will listen on. Defaults to 8081.
-pwd or -password
Path to a file containing a password. If provided, Orionode will enforce HTTP Basic Authentication with the password (the auth 'User' field is ignored -- Orionode only verifies the password). Use caution: if you don't provide a password file, no authentication is used (so anyone request can read and write your files!).
-w or -workspace
The target directory for reading and writing files. Will be created if it doesn't exist. Defaults to a subdirectory named .workspace in the repository folder.
-dev
Starts the server in development mode. In this mode, some client-side code is not cached by the browser, to ease development.
-log
Logs each request served to standard output.

Developing a node.js application

Now in the browser you can start to develop your node.js applications. Orionode uses the same client code as Orion does. Refer to Orion user guide for the client usage. Please note that the sites and git pages are not available in Orionode. Here is a typical workflow:

  1. Use Navigator and Edit pages to create and edit your folders and node applications.
  2. Go to Shell page.
  3. cd to the folder where your application lives.
  4. Use npm install to install your dependency packages if needed. You can basically use all the npm arguments here.
  5. Use node start yourApp.js to start your application.
  6. Use node list to monitor all the applications you've started and still running.
  7. Use node stop PID to stop an application if you want to force it to stop.

Debugging a node.js application

You can use Orionode to debug your node.js application. If you have exisiting node.js applications, make sure the code is under a subfolder in the -w option when you start Orionnode. This will give you easy access to your node.js apps from within Orionode. You can also create a new node.js application in your workspace.

  1. After Orionode starts, open the shell page and use help to see what commands are available.
  2. cd to the folder where your application lives.
  3. Use node debug yourApp.js givenPort to start your app in debug mode. You can start multiple apps in debug mode by repeating this step.
  4. In the return value of the node debug command, you will see a "debugURL" string.
  5. Copy and paste the debug URL into a webkit browser (e.g., Chrome, Safari) and start debugging. The URL normally looks something like: http://yourOrionNodeServer:8900/debug?port=theGivenPort.

Concatenation and Minification

By default the pages served up by Orionode are not concatenated or minified, so they will load rather slowly. You can mitigate this by running the client-side build. To do this, just run build.js, found in the build directory:

   orionode $ node ./build/build.js
   -------------------------------------------------------
   [lots of output]
   orionode $

Clear your browser cache. The next time you load Orionode, it should be much faster.

Other ways of using Orionode

You can use Orionode as a file server, to access your local files from http://www.orionhub.org/ (or any other Orion installation). All you need is Orionode and a publicly-accessible URL pointing to your local Orionode server.

  1. Visit this page on your Orionode server (the hostname will differ from this example) and copy its URL:http://yourOrionNodeServer:8081/plugins/fileClientPlugin.html
  2. Log in to Orionhub.
  3. Click the user menu in the top right-hand corner of the page, then click Settings.
  4. Select the Plugins category, click Install, paste in the URL, click Submit.
  5. Return to the Navigator page. Your Orionode files should appear as a new filesystem in the left-hand sidebar.

Unit tests

Our unit tests are written against the Mocha test framework.

Running the tests

From the org.eclipse.orion.client/modules/orionode directory, just run the command:

 npm test

This will invoke Mocha and produce console output showing which tests passed and failed.

If you want to pass custom arguments to Mocha, you'll need to invoke it explicitly like this:

 ./node_modules/mocha/bin/mocha [debug] [options] [files]

To make this easier, you can install Mocha as a global npm package (npm install mocha -g), and then invoke it as simply mocha from a command shell.

Writing more tests

When you're prototyping a new feature, writing unit tests for it is always a good idea. Here's how to write a test:

  1. Create a new file my_tests.js in the org.eclipse.orion.client/modules/orionode/test/ directory.
  2. Write your tests in the file. Here are two resources to help you get started:
  3. Run the tests.
    • You don't have to register your new tests with the framework; it will discover anything in the test/ directory automatically.

Helper data or classes should go in test/support/.

Security Concerns

No security is guaranteed or even implied at this moment. Always run Orionode with the -pwd flag to prevent unauthorized access to your files.

Known Issues

  • See the list of open bugs.
  • There is no way to provide standard input to a running Node.js app.
  • No source control integration yet. E.g.: Git support.