Notice: This Wiki is now read only and edits are no longer possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.
Orion/Node/Getting started
Orionode is a minimal, single-user server 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
You can obtain Orionode through npm (the easiest way) or by checking out its source repo and running it.
Installing with npm
To install Orion with the Node Package Manager (npm), simply run the following command from the shell:
- Run this command from a shell:
npm install orion
This should install Orionode into a node_modules subdirectory of your working directory.
- If you're not interested in developing the Orionode server, add the
--production
flag for a slightly smaller download.
- If you're not interested in developing the Orionode server, add the
Installing from source
- Get the Orion source. You only need to get the client source.
- Open a command shell and change directory to org.eclipse.orion.client/modules/orionode.
- Run the
npm install
command to automatically download Orionode's dependencies.- 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.
- If you're not interested in developing the server, you can instead run
Starting and stopping the server
- Launch Orion by running:
npm start orion
- If you need to pass command line arguments to the server, run the server.js file directly:
node node_modules/orion/server.js [arguments]
- If you need to pass command line arguments to the server, run the server.js file directly:
- Go to http://localhost:8081 (or whatever port you provided in the server arguments) in your web browser to start using Orionode.
- Stop the server by sending a kill signal from the console (typically Ctrl+C)
Other recommended steps
These are not strictly necessary to run the server, but recommended anyway.
Password
- Create a one-line "password.txt" file containing a secret password.
- Launch the Orionode server with the
-password password.txt
argument.
You can also provide a password in an orion.conf
file by including a line like:pwd=mysecretpassword
Making sure Orionode can launch npm
Orionode lets you use npm
commands in the Orion shell to manage the dependencies of a project you're writing. To do this, the server makes a guess about the path where the npm internals (specifically, npm-cli.js
) are located on your computer. If you installed a recent version of Node.js, npm should be installed automatically and the guess should work. If you installed npm separately, this guess may be wrong. If you see an error message when launching the server or when you try to run npm commands in the Orion shell, it means the server failed to guess where npm lives, so you have to specify the path to npm-cli.js
yourself:
- Find out where npm lives on your computer (npm must be in your PATH environment variable for this to work). From a command shell, run:
- On Windows:
where npm
- On Mac OS/Linux:
which npm
- The returned path will be a shell script (or a symbolic link to a script) that launches
npm-cli.js
. The path tonpm-cli.js
is what we need. Open up the script in a text editor, and copy the path ofnpm-cli.js
.
- On Windows:
- In the server directory, open the
orion.conf
file. You'll find anpm_path
option (by default its value is empty). - Set the value of
npm_path
option equal to the path tonpm-cli.js
.- You can provide the path as an absolute path, or a path relative to your node executable.
- Start or restart the server. If you do not see any "npm" errors printed to the console, your npm path is set properly.
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 server directory. -
-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 largely the UI you're accustomed to from Orion. (Refer to Orion user guide for basic instructions). Please note that the Sites and Git pages are not available in Orionode. Here is a typical workflow:
- Use the Navigator and Edit pages to create and edit your folders and node applications.
- Go to the Shell page.
cd
to the folder where your application lives.- Use
npm install
to install your dependency packages if needed. You can use basically all the npm arguments here. - Use
node start yourApp.js
to start your application. - Use
node list
to monitor all the applications you've started and still running. - 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 existing node.js applications, make sure the code is under a subfolder of the workspace (path provided by 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.
- After Orionode starts, open the shell page and use help to see what commands are available.
cd
to the folder where your application lives.- 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. - In the return value of the
node debug
command, you will see a "debugURL" string. - 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 org.eclipse.orion.client/modules/orionode/build
directory:
node ./build/build.js
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.
- Visit this page on your Orionode server (the hostname will differ from this example) and copy its URL:http://yourOrionNodeServer:8081/plugins/fileClientPlugin.html
- Log in to Orionhub.
- Click the user menu in the top right-hand corner of the page, then click Settings.
- Select the Plugins category, click Install, paste in the URL, click Submit.
- 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:
- Create a new file
my_tests.js
in theorg.eclipse.orion.client/modules/orionode/test/
directory. - Write your tests in the file. Here are two resources to help you get started:
- Mocha reference: the general structure of a test.
- Superagent reference: how to write concise assertions for testing HTTP.
- Run the tests.
- You don't have to register your new tests with the framework; it will discover anything in the
test/
directory automatically.
- You don't have to register your new tests with the framework; it will discover anything in the
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.