View source for Orion/Node/Getting started

Orion provides a minimal, single-user server deployment of Orion written in JavaScript that runs on [http://nodejs.org Node.js]. This implementation of Orion supports developing your own Node applications with Orion's editing environment.

==Features==
The JavaScript Orion server implementation is still very early access. There are many rough edges and missing features compared to the full Java-based Orion server. The JavaScript-based Orion server currently supports:

* 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)
* Gzip on server traffic to reduce download times
* Concatenation and minification of pages (requires a manual step)

==== Feature comparison ====
This table compares features between the Java and Node.js servers.

{| class="wikitable" style="text-align: center;"
! || Java || Node
|-
| style="text-align:left;" | Users || multiple || single or multiple
|-
| style="text-align:left;" | Login API (<tt>/login</tt>) || ✔ || ✔
|-
| style="text-align:left;" | File operations (<tt>/file</tt>) || ✔ || ✔
|-
| style="text-align:left;" | Import zip/HTTP/SFTP (<tt>/import</tt>) || ✔ || ✔
|-
| style="text-align:left;" | Export zip/SFTP (<tt>/export</tt>) || ✔ || ✔
|-
| style="text-align:left;" | Import SFTP (<tt>/import</tt>) || ✔ || 
|-
| style="text-align:left;" | Export SFTP (<tt>/export</tt>) || ✔ || 
|-
| style="text-align:left;" | Persistent user preferences (<tt>/prefs</tt>) || ✔ || ✔
|-
| style="text-align:left;" | Git (<tt>/gitapi</tt>) || ✔ || ✔
|-
| style="text-align:left;" | Deploy to Cloud Foundry (<tt>/cfapi</tt>) || ✔ || 
|-
| style="text-align:left;" | Sites (<tt>/sites</tt>) || ✔ || ✔
|-
| style="text-align:left;" | Long running tasks (<tt>/task</tt>) || ✔ || ✔
|-
| style="text-align:left;" | User API (<tt>/users</tt>) || ✔ || †
|-
|}

<nowiki>†</nowiki> Orion Node server supports these features in multi-user mode only.

== Requirements ==
* Node.js
* A modern web browser.

== Getting Orionode and starting it ==
You can obtain Orionode through npm (the easiest way) or by checking out its source repo and running it. Checking out the source is mainly of interest to developers wishing to work on or extend the Orion node server. For details on this approach see the Orion developer [[Orion/Getting_the_source#Node.js_on_local_computer| wiki page]].

=== Installing with npm ===
To install Orion with the Node Package Manager (npm), simply run the following command from the shell:
<code> npm install orion</code>
This will install Orionode into a <code>node_modules</code> subdirectory of your working directory.
* If you're not interested in developing the Orionode server, add the <code>--production</code> flag for a slightly smaller download.

==== Nodegit Installation ====
During the installation from [https://www.npmjs.com/package/orion NPM], Nodegit will try to find binaries for your installed version of Node.js / operating system. If it has them, they will be downloaded and the installation will complete normally.
If however, it does not have a pre-built version ready to go, Nodegit will start up its builder to try and create the binaries it requires. Depending on your operating system and build-time tools you have installed, this will complete normally and everything will work fine. 
If you are missing build tools that it needs to build its binaries, the install will fail.

If your build / install does fail, please read [http://www.nodegit.org/guides/install/from-source/ the Nodegit build page] to make sure you have all the expected tools installed and try running <code>npm install orion</code> again.

=== Starting and stopping the server ===
# Launch Orion by running:<br><code>npm start orion</code> 
#* If you need to pass [[#Server_command_line_arguments|command line arguments]] to the server, run the server.js file directly:<br><code>node node_modules/orion/server.js [arguments]</code>
# 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)

=== The orion.conf file ===
You can pass arguments to the server by editing the <code>orion.conf</code> file. It is found in the directory where you installed Orion (when installing from npm, this is typically <code>node_modules/orion/</code>). An alternate configuration file can be specified via [[#Server_command_line_arguments|command line arguments]].

===== Password =====
Add a line in your <code>orion.conf</code> file that looks like this:
  pwd=mysecretpassword

===== Workspace =====
Edit the <code>orion.conf</code> file and change the <code>workspace</code> option to point to a directory in your user space. If not specified, a default <code>.workspace</code> directory will be created in the Orion install directory. For example:
  workspace=/home/pi/Workspace/

== Using a global installation of Orionode ==

=== Installing with npm ===
To install Orion with the Node Package Manager (npm), simply run the following command from the shell:
<code> npm install -g orion</code>
This will install Orionode as a global package, enabling you to run from any directory.
* If you're not interested in developing the Orionode server, add the <code>--production</code> flag for a slightly smaller download.
* If you run into permissions problems, you may need to run with sudo, e.g. <code>sudo npm install -g orion</code>. (A global installation attempts to install in <code>bin</code> so that the command <code>orion</code> can be run in the shell.)

If your global installation fails because of Nodegit, please read the [[#Nodegit_Installation| Nodegit Installation]] section above.

=== Starting and stopping the server ===
# Launch Orion by running:<br><code>orion</code> 
#* There are a few different options for the global installation:
#** <code>orion</code>: launches Orion on port 8081 using current working directory
#** <code>orion <workspaceDir></code>: launches Orion on port 8081 using <workspaceDir>
#** <code>orion -p <portno></code>: launches Orion on <portno> using current working directory
#** <code>orion <workspaceDir> -p <portno></code>: launches Orion on <portno> using <workspaceDir>
#** <code>orion -w <workspaceDir> -p <portno></code>: same as above, except order can be switched
#* The global installation of Orion currently only supports the [[#Server_command_line_arguments|command line arguments]] -p and -w. It does not read from the orion.conf file.
# 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)

== Server command line arguments ==
When launching the server manually through node.js (<code>node [orion install dir]/server.js</code>), a number of optional arguments can be provided:
; <code>-c</code> or <code>-config</code>
: Path to an alternate orionode configuration file. Defaults to orion.conf. This is useful to run orionode from git sources without modifying the version controlled orion.conf file in the git working tree.
; <code>-p</code> or <code>-port</code>
: The port that the Orion server will listen on. Defaults to 8081.
; <code>-pwd</code> or <code>-password</code>
: 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 can access your Orionode server and read and write your files!). 
; <code>-w</code> or <code>-workspace</code>
: The target directory for reading and writing files. Will be created if it doesn't exist. Defaults to a subdirectory named <code>.workspace</code> in the server directory. This option can also be set in your [[#The orion.conf file|orion.conf file]].
; <code>-dev</code>
: Starts the server in development mode. In this mode, some client-side code is not cached by the browser, to ease development.
; <code>-log</code>
: Logs each request served to standard output.
Arguments passed on the command line override arguments set in the orion.conf file, when both are provided.

== 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/Documentation/User_Guide|Orion user guide]] for basic instructions).
#Use the Navigator and Edit pages to create and edit your folders and node applications.
#Use the '''Console''' page to start, stop and manage your application.

== 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.

== Security Concerns ==
No security is guaranteed or even implied at this moment. Always run Orionode with the <code>-pwd</code> flag to prevent unauthorized access to your files.

== Known Issues ==
* See the [https://bugs.eclipse.org/bugs/buglist.cgi?bug_status=UNCONFIRMED&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED&classification=ECD&component=Node&list_id=13951195&product=Orion&query_format=advanced list of open bugs].

== See also ==
* [[Orion/Node/Developing|Developing the Node server]]

[[Category:Orion|N]]
[[Category:Orion/Node|G]]