Skip to main content

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

Difference between revisions of "Orion/Releng Builds"

(Minification)
(Running orion-server builds)
 
(50 intermediate revisions by 4 users not shown)
Line 1: Line 1:
 
Orion currently has 3 kinds of builds:  
 
Orion currently has 3 kinds of builds:  
* The '''[[#PDE build | PDE build]]''' uses infrastructure from Eclipse platform releng. Offical [http://download.eclipse.org/orion/ Orion releases] are produced by this build.
+
* The '''[[#Tycho build | Tycho build]]''' is based on [https://eclipse.org/tycho/ Tycho] and Maven. It produces the official [http://download.eclipse.org/orion/ Orion downloads].
* The '''[[#Tycho build | Tycho build]]''' is based on [https://eclipse.org/tycho/ Tycho] and Maven. Compared to the PDE build, the Tycho build is easier for downstream products to consume, and easier to reproduce in other environments.
+
 
* The '''[[#Node build | Node build]]''' is a small script that runs on [https://node.js.org Node.js]. It produces an Orion server that runs under Node.js.
 
* The '''[[#Node build | Node build]]''' is a small script that runs on [https://node.js.org Node.js]. It produces an Orion server that runs under Node.js.
 +
* The '''[[#WAR build | WAR build]]''' is capability that can run within Eclipse. It produces a war file that can run Orion within an application container such as Tomcat or WebSphere.
  
 
= How to contribute =
 
= How to contribute =
Line 14: Line 14:
  
 
#See [[Orion/Getting the source]] for instructions on how to set up your workspace to work with Orion source code.  
 
#See [[Orion/Getting the source]] for instructions on how to set up your workspace to work with Orion source code.  
#(If you want to try running the PDE build locally): Import ''''org.eclipse.orion.releng'''' into your workspace. It is located in the [http://git.eclipse.org/c/orion/org.eclipse.orion.server.git/ org.eclipse.orion.server.git] repository under the releng folder.
 
  
 
=== Contributing your changes ===
 
=== Contributing your changes ===
Line 26: Line 25:
 
== Minification ==
 
== Minification ==
  
The Orion build performs minification of client pages and plugins. This section has instructions on how to add new content for minification in the build.
+
The Orion build performs optimization of client pages and plugins using RequireJS. Note the distinction between ''concatenation'' (inlining a module's AMD dependencies to reduce HTTP overhead) and ''minification'' (shrinking a module's JavaScript code size by removing whitespace). The build minifies all JavaScript code automatically, but getting your module concatenated requires an extra step. This section has instructions on how to add new content for concatenation in the build.
  
=== Adding a new module to the client build ===
+
=== Adding a new module to the optimization ===
If you're adding a new page or plugin to the Orion client UI, there's usually just one step required to get it optimized:
+
To add a new page or plugin for concatenation, you must update this file: <tt>releng/org.eclipse.orion.client.releng/builder/scripts/orion.build.js</tt> Find the property <tt>modules</tt>, and add an entry for your page/plugin.
* Add an entry to the <tt>modules</tt> section of <tt>orion.build.js</tt>.
+
  
Every entry needs a <tt>name</tt> property and a <tt>bundle</tt>, which tells the builder which bundle the minified module should be copied back into. For example, here is the Git Commit page's entry:
+
Every entry needs a <tt>name</tt> property giving the module's web path. For example, here is the Git Commit page's entry:
  
<source lang="javascript" enclose="div" line="line">
+
<source lang="javascript" enclose="div" >
{ name: "git/git-commit",
+
    { name: "git/git-commit" },
  bundle: "${orionClient}/bundles/org.eclipse.orion.client.git"
+
},
+
 
</source>
 
</source>
  
^ Ant-style property replacement is supported in the <tt>bundle</tt> field, but <tt>${orionClient}</tt> is the only property you should use there. The PDE, Hudson, and Node builds all share <tt>orion.build.js</tt>, so your new module will be correctly built everywhere.
+
The Tycho and Node builds all share <tt>orion.build.js</tt>, so your new module will be correctly built everywhere.
  
==== How optimized modules are generated ====
+
=== Adding a new client bundle to the JS build ===
For every module <tt>{name}</tt> listed in the <tt>modules</tt> section:
+
# Add an entry to the <tt>bundles</tt> section of <tt>orion.build.js</tt>. (Ant-style property replacement is supported within the bundles entry, but <tt>${orionClient}</tt> is the only property you should use there.)
* The build outputs an optimized file, named <tt>built-{name}.js</tt>, with AMD dependencies inlined and code minified.  
+
# If your bundle contains any JSDocs, add an entry to the <tt>jsdocs</tt> section of <tt>orion.build.js</tt>.
* The build also determines the ''caller'' -- usually it's the HTML page that calls <tt>require(["{name}.js"])</tt> or <tt>&lt;script data-main="{name}" ... /&gt;</tt>.
+
# For each of the bundle's modules you want to optimize, add an entry to the <tt>modules</tt> section of <tt>orion.build.js</tt>. (see [[#Adding a new module to the optimization|previous section]]).
* The caller is modified such that the optimized file <tt>built-{name}.js</tt> is loaded rather than the original <tt>{name}.js</tt>.
+
# Add a <tt>pom.xml</tt> file in the root folder of your bundle.
 +
# Add an entry to the <tt>&lt;modules&gt;</tt> section of the client repo's [http://git.eclipse.org/c/orion/org.eclipse.orion.client.git/tree/pom.xml top-level <tt>pom.xml</tt>]. This ensures that the Maven builder finds your bundle.
 +
# Update the <tt>selfHostingRules.js</tt> file by adding an entry for the new bundle. This is required for your bundle's resources to be accessible when [[Orion/Selfhosting|self-hosting Orion]].
  
For a module <tt>{name}.js</tt>, the build by convention looks for a caller named <tt>{name}.html</tt>. If the caller is not named according to convention, it must be specified in the module entry using a <tt>caller</tt> property, so that the build can locate it. As of this writing, the caller must live in the same folder as the module.
+
=== Building stand-alone features ===
 +
Orion pages and plugins are handled by a multi-module invocation of r.js that optimizes all of them in one shot. However, stand-alone features need different build config options, which means r.js must be invoked separately for each of these features.
  
For example, this is how the JS tools web worker (which is loaded by another script file, not an HTML file) is optimized:
+
To build a stand-alone feature, you must add logic to the <tt>requirejs</tt> task in the Ant script <tt>orion.mini.xml</tt>. You must invoke <tt>r.js</tt>, passing the build file for your feature. Here is an example showing how a file used for the standalone Orion editor is minified:
  
<source lang="javascript" enclose="div" line="line">
+
<source lang="xml" enclose="div" line="line" highlight="6, 13-17, 22-33">
  { name: "javascript/plugins/javascriptPluginWorker",
+
  <!-- Clean widget output directory -->
  bundle: "${orionClient}/bundles/org.eclipse.orion.client.javascript",
+
<target name="widgetClean" depends="widget.check" if="widget.run">
  caller: "javascriptWorkerBootstrap.js"  
+
    <delete dir="${widgetOutDirectory}" />
},
+
    <mkdir dir="${widgetOutDirectory}" />
 +
 
 +
    <copy file="${builder}/scripts/editor.build-js.js" tofile="${staging}/editor.build-js.js" overwrite="true"/>
 +
    <!-- ... -->
 +
</target>
 +
 
 +
<target name="requirejs" depends="checkDirs, cleanStaging, cleanOptimized">
 +
    <!-- ... -->
 +
 
 +
    <!-- build standalone editor (unless skipEditor is set) -->
 +
    <antcall target="editorOptimize">
 +
        <param name="staging" value="${staging}" />
 +
        <param name="out" value="${widgetOutDirectory}" />
 +
    </antcall>
 +
 
 +
    <!-- ... -->
 +
</target>
 +
 
 +
<target name="editorOptimize" unless="skipEditor">
 +
    <sequential>
 +
        <!-- Invoke r.js -->
 +
        <widgetOptimizeFile
 +
            out="${out}/built-editor-amd.min.js"
 +
            buildfile="${staging}/editor.build-js.js"
 +
            optimize="closure"
 +
            staging="${staging}" />
 +
 
 +
        <!-- Additional calls to r.js can be placed here, if needed -->
 +
    </sequential>
 +
</target>
 
</source>
 
</source>
  
^ Here, the build will modify the caller <tt>javascriptWorkerBootstrap.js</tt> such that it loads the optimized module "built-javascriptPluginWorker.js" instead of "javascriptPluginWorker.js".
+
== Deploying builds to orion.eclipse.org or orionhub.org ==
  
=== Adding a new client bundle to the JS build ===
+
Builds are deployed using the script [http://git.eclipse.org/c/orion/org.eclipse.orion.server.git/tree/releng/org.eclipse.orion.releng/builder/scripts/deploy.sh deploy.sh]. This script should be copied to your home directory and run from there. Your home directory will contain a symlink to the downloads directory, so you can perform a deploy directly from the downloads area. The script takes a single argument which is the location of the zip containing the download. For our servers we want the Linux 64-bit build. It is useful to log the output of this script so it can be reviewed later. Example:
# Add an entry to the bundles section of <tt>orion.build.js</tt>.
+
# If your bundle contains any JSDocs, add an entry to the <tt>jsdocs</tt> section of <tt>orion.build.js</tt>.
+
# Add module entries for any of the bundle's modules you want minified (see [[#Adding a new module to the client build|previous section]]).
+
# Add an entry to the <tt>&lt;modules&gt;</tt> section of the client repo's [http://git.eclipse.org/c/orion/org.eclipse.orion.client.git/tree/pom.xml top-level <tt>pom.xml</tt>]. This ensures that the Maven builder finds your bundle.
+
  
=== Building stand-alone features ===
+
./deploy.sh -archive downloads/orion/drops/I201201102230/eclipse-orion-I20120110-2230-linux.gtk.x86_64.zip >> deploy.log
Right now stand-alone features (such as the <tt>built-editor.min.js</tt>, the standalone Orion editor) are still handled separately by the build script. You must add logic to <tt>orion.mini.xml</tt> that invokes <tt>r.js</tt>, passing the build file for your feature. Use the standalone editor build as a reference.
+
  
= PDE build =
+
This script simply copies the build onto the deployment server, and invokes an upgrade script on that server - [http://git.eclipse.org/c/orion/org.eclipse.orion.server.git/tree/releng/org.eclipse.orion.releng/builder/scripts/upgrade.sh upgrade.sh]. The upgrade script shuts down the old server, moves it, unzips and configures the new build, and finally starts it.
The PDE builds follow many of the same practices used by the [[Platform-releng|Eclipse Platform Project]]. The builds are based on [[PDE/Build]] and run automatically on build.eclipse.org via cron job.  
+
  
There is only one kind of build. Integration builds run daily from tagged repository versions.  [http://help.eclipse.org/topic//org.eclipse.pde.doc.user/tasks/pde_fetch_phase.htm Map files] are used to specify where a project is located in the repository and what version of that project to use in the build. The map files are located in the [http://git.eclipse.org/c/orion/org.eclipse.orion.server.git/tree/releng/org.eclipse.orion.releng/maps/orion.map org.eclipse.orion.releng] project. The builder itself performs the tagging so all the latest changes in "master" stream are picked up by every build. No manual tagging by committers is required.
+
The entire deploy/upgrade process takes about 5 seconds when it runs smoothly. Occasionally there will be a communication error copying the new build onto the target machine. In this case simply re-running the script usually succeeds.
  
== How the build works ==
+
=== Server configuration ===
  
=== Bootstrap ===
+
The [[Orion/Server_admin_guide#Server_configuration_file|server configuration file]] on [https://orion.eclipse.org orion.eclipse.org] and [https://orionhub.org orionhub.org] is found in <tt>~admin/current/orion.conf</tt>. This file gets copied into the server by the deployment script. So, any change made to this configuration file will take effect only on the next deployment.
  
The build is kicked off by a "bootstrap" script that is not under version control. The only purpose of this script is to fetch the real build script and invoke the build. The script is located at:
 
  
/opt/buildhomes/e4Build/bootstrap.orion.sh
+
= Tycho build =
 +
The Tycho builds use the [https://eclipse.org/tycho/ Eclipse Tycho] infrastructure ([https://wiki.eclipse.org/Category:Tycho Category:Tycho]), centered around [http://maven.apache.org/ Maven]. Orion committers can manage Tycho builds using the [https://hudson.eclipse.org/orion/ Orion Hudson instance]. We have 2 flavors of Tycho builds: ''development'', which build off the master branch, and ''stable'', which build off a stable branch that only production-ready features are merged into. Stable typically trails dev by a few weeks.
  
The build type is passed as an argument. -I means integration build (with tagging). -N is equivalent but does not perform any tagging (in both cases the contents of master are used to perform the build).
+
== Build jobs ==
  
You can also pass an -email argument to cause the build notifications to only be sent to an individual. This is useful for test builds:
+
=== [https://hudson.eclipse.org/orion/job/orion-client-dev/ orion-client-dev] ===
 +
Builds Orion's client-side JavaScript code and performs JS minification. JavaScript tests are optionally executed (requires Sauce Labs and Cloud Foundry).
  
bootstrap.orion.sh -I -email bob_mackenzie@example.com
+
=== [https://hudson.eclipse.org/orion/job/orion-server-dev/ orion-server-dev] ===
 +
Downstream project of orion-client-dev. Builds Orion's Java server and runs Java tests.
  
The bootstrap script is typically invoked by a cron entry in the e4Build user account. For example here is a cron entry to start a build every Wednesday at 8:55am:
+
Stable jobs: [https://hudson.eclipse.org/orion/job/orion-client-stable/ orion-client-stable], [https://hudson.eclipse.org/orion/job/orion-server-stable/ orion-server-stable]
  
55 08 * * Wed /opt/buildhomes/e4Build/bootstrap.orion.sh -I
+
== Running orion-client builds ==
 +
You must have Apache Maven installed and on your system <tt>PATH</tt>.  
  
Invoke "crontab -e" to edit the cron entries (using vi), or "crontab -l" to simply list them.
+
To run a complete build, <tt>cd</tt> to the directory where you checked out the org.eclipse.orion.client repo, and run:
  
=== masterBuild.sh ===
+
$ mvn clean install
  
The bootstrap fetches and invokes the main build script, called [http://git.eclipse.org/c/orion/org.eclipse.orion.server.git/tree/releng/org.eclipse.orion.releng/builder/scripts/masterBuild.sh masterBuild.sh]. This script is under version control, so you need to push any changes to this script into the master branch for them to take effect. If you scroll to the very bottom of this script you can see the steps it performs:
+
A complete build takes 8-15 minutes to complete. To speed up the build, various features can be disabled by setting system properties passed to Maven with the <tt>-D</tt> argument. For example, this command runs a build without generating JSDocs for the Orion source.
  
  tagRepositories # perform auto-tagging of the Orion git repositories
+
  $ mvn -DskipJsdoc clean install
updateRelengProject # fetch latest from Orion releng project (our scripts and maps)
+
updateBaseBuilder # fetch the PDE builder to use in the build
+
setProperties # various initialization steps
+
runBuild # invoke the PDE build
+
runTests # invoke client and server tests
+
publish # send results email
+
  
=== build log ===
 
  
The results of the build, including any failures from any step, can found found in the build log at:
+
==== A Note about Node.js ====
 +
If you're running the build on Linux, Windows, or OS X, it should successfully download and run Node.js to perform JS minification. On more exotic platforms, this might fail, in which case you can run the build under Java 8's Nashorn JS engine instead by setting the <tt>-DskipNode</tt> system property or ''disabling'' the nodejs profile using <tt>-P '!nodejs'</tt>. Nashorn requires Java 8 or higher.
  
/shared/eclipse/e4/orion/logs/current.log
 
  
This is the first place to check when the build fails. It is typically very long so it is often helpful to use <tt>tail</tt> to start near the end. This exact same log gets copied into the download directory so it is available for reference for any build we produce. For example:
+
{| class="wikitable"
 +
|+System Properties
 +
|-
 +
|<tt>skipNode</tt>
 +
|Do not download Node.js; run the client minification under Nashorn instead. (The same effect can be achieved by disabling the <tt>nodejs</tt> profile, i.e. <tt>mvn -P '!nodejs'</tt>.)
 +
|-
 +
|<tt>skipJsdoc</tt>
 +
|Do not generate JSDoc.
 +
|-
 +
|<tt>skipCommitBrowser</tt>
 +
|Do not generate the stand-alone git commit browser widget.
 +
|-
 +
|<tt>skipCompareEditor</tt>
 +
|Do not generate the stand-alone compare viewer widget.
 +
|-
 +
|<tt>skipEditor</tt>
 +
|Do not generate the stand-alone Orion editor widget (<tt>built-editor.js</tt>).
 +
|-
 +
|<tt>skipEmbeddedEditor</tt>
 +
|Do not generate the stand-alone [[Orion/How_Tos/Editor_Build|Orion JS editor]] (<tt>built-codeEdit.zip</tt>).
 +
|-
 +
|<tt>skipEditorStylers</tt>
 +
|Do not generate the stand-alone editor stylers.
 +
|-
 +
|<tt>skipOrionUI</tt>
 +
|Do not [http://requirejs.org/docs/optimization.html optimize] the Orion pages and plugins. This option will make the build substantially faster, at the cost of slower-loading pages when the build is deployed to a web server.
 +
|-
 +
|<tt>orion.client.build.skip</tt>
 +
|Skips all of the above mentioned components. This saves the most time.
 +
|}
  
/home/data/httpd/download.eclipse.org/orion/drops/I201201110855/buildLog-I20120111-0855.txt
+
== Running orion-server builds ==
 +
You must have Apache Maven 3.x installed and on your system <tt>PATH</tt>.
  
=== Repository cache ===
+
To run a complete build, run:
  
For performance reasons, PDE build maintains a cache of fetched prerequisite bundles. This lives at /shared/eclipse/e4/orion/target/transformedRepos on the build machine. The build will pick up the newest version of each required bundle from that location. If you ever need to force the build to go back to an *older* version of a bundle, this cache needs to be cleared. Simply delete the transformedRepos directory prior to the build.
+
  % git clone http://git.eclipse.org/gitroot/orion/org.eclipse.orion.client.git
 +
  % git clone http://git.eclipse.org/gitroot/orion/org.eclipse.orion.server.git
 +
  % cd org.eclipse.orion.server
 +
  % mvn clean install -P platform-kepler -Dorion.client.build.skip -DskipTests
 +
  % cd releng/org.eclipse.orion.server.repository/target/products/org.eclipse.orion/linux/gtk/x86_64/eclipse/
 +
  % ./orion
  
== Deploying builds to orion.eclipse.org or orionhub.org ==
+
If you want to have the client minified, then do not include
  
Builds are deployed using the script [http://git.eclipse.org/c/orion/org.eclipse.orion.server.git/tree/releng/org.eclipse.orion.releng/builder/scripts/deploy.sh deploy.sh]. This script should be copied to your home directory and run from there. Your home directory will contain a symlink to the downloads directory, so you can perform a deploy directly from the downloads area. The script takes a single argument which is the location of the zip containing the download. For our servers we want the Linux 64-bit build. It is useful to log the output of this script so it can be reviewed later. Example:
+
  -Dorion.client.build.skip
  
./deploy.sh -archive downloads/orion/drops/I201201102230/eclipse-orion-I20120110-2230-linux.gtk.x86_64.zip >> deploy.log
+
If you want to run the tests, then do not include
  
This script simply copies the build onto the deployment server, and invokes an upgrade script on that server - [http://git.eclipse.org/c/orion/org.eclipse.orion.server.git/tree/releng/org.eclipse.orion.releng/builder/scripts/upgrade.sh upgrade.sh]. The upgrade script shuts down the old server, moves it, unzips and configures the new build, and finally starts it.
+
  -DskipTests
  
The entire deploy/upgrade process takes about 5 seconds when it runs smoothly. Occasionally there will be a communication error copying the new build onto the target machine. In this case simply re-running the script usually succeeds.
+
== JavaScript tests ==
 +
For good coverage of client-side JavaScript unit tests, it is desirable to run the tests under various web browsers. As of May 2014, unit tests in the <tt>orion-client-dev</tt> Hudson job execute in the [https://saucelabs.com/ Sauce Labs] cloud which provides testing under various browser+OS platforms.  
  
=== Server configuration ===
+
==== Architecture ====
 +
The pom file responsible for managing the tests is [https://github.com/eclipse/orion.client/blob/master/releng/org.eclipse.orion.client.releng/pom.xml <tt>releng/org.eclipse.orion.client.releng/pom.xml</tt>].
  
The [[Orion/Server_admin_guide#Server_configuration_file|server configuration file]] on [https://orion.eclipse.org orion.eclipse.org] and [https://orionhub.org orionhub.org] is found in <tt>~admin/current/orion.conf</tt>. This file gets copied into the server by the deployment script. So, any change made to this configuration file will take effect only on the next deployment.
+
For Sauce Labs to run our tests, Orion's test code must be hosted on a web server that is accessible by the Sauce Labs cloud. Sauce Labs does provide a tunnel solution for testing code behind a firewall, but it does not work behind a proxy, which makes it unsuitable for [https://wiki.eclipse.org/Hudson#Why_use_a_Proxy.3F Eclipse's Hudson environment].
  
 +
For this reason, the test code is hosted on an external server that the build dynamically deploys to. The POM starts off by deploying a small test runner application to a [http://en.wikipedia.org/wiki/Cloud_Foundry Cloud Foundry environment] (see [https://github.com/eclipse/orion.client/blob/master/releng/org.eclipse.orion.client.releng/test/Gruntfile.js <tt>Gruntfile.js</tt>] for the test runner source.) The test runner is responsible for hosting the Orion client code as a web server, and invoking the Sauce Labs API to kick off the tests.
  
= Tycho build =
+
Sauce Labs uses its browser farm to load each test page's URL in turn and execute the tests. Each test page must use the [[#Mocha–Sauce Labs integration|Mocha–Sauce wrapper]] in order to correctly call back to Sauce at this step. The test pages return xUnit reports to Sauce showing passes and failures. Those reports are then echoed back to the test runner app, which collects them.
The Tycho builds use the [https://eclipse.org/tycho/ Eclipse Tycho] infrastructure, centered around [http://maven.apache.org/ Maven]. Orion committers can managed Tycho builds using the [https://hudson.eclipse.org/orion/ Orion Hudson instance]. The build comprises 2 jobs:
+
  
; [https://hudson.eclipse.org/orion/job/orion-client/ orion-client]
+
When all tests have finished, the runner enters a dormant state. In this state, any requests to <tt>https://{test_runner_url}/testresults</tt> will return a zip of all the test results. The build grabs the results, unzips them, and finishes.
: Builds Orion's client-side JavaScript code and performs JS minification.
+
  
; [https://hudson.eclipse.org/orion/job/orion-server/ orion-server]
+
==== Maven setup ====
: Downstream project of orion-client. Builds Orion's Java server and runs the tests.
+
To run the tests, Maven must be configured with a <tt>settings.xml</tt> file that contains the secret CF and Sauce authentication credentials. The file is generally located at <tt>$HOME/.m2/settings.xml</tt> and it should look like this:
 +
<source lang="xml">
 +
<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0"
 +
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 +
    xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 http://maven.apache.org/xsd/settings-1.0.0.xsd">
 +
    <servers>
 +
        <server>
 +
            <id>orion-test-server</id>
 +
            <username>[Cloud Foundry username]</username>
 +
            <password>[Cloud Foundry password]</password>
 +
        </server>
 +
    </servers>
 +
    <profiles>
 +
        <profile>
 +
            <id>orion-test</id>
 +
            <properties>
 +
                <SAUCE_USERNAME>[Sauce Labs username]</SAUCE_USERNAME>
 +
                <SAUCE_ACCESS_KEY>[Sauce Labs Access Key]</SAUCE_ACCESS_KEY>
 +
            </properties>
 +
        </profile>
 +
    </profiles>
 +
</settings>
 +
</source>
  
As of this writing, Tycho builds only run Orion's Java server tests; Orion's JavaScript tests are not yet supported.
+
Additionally, some CF-related properties must be passed to Maven. This picture shows the required properties in Hudson. Your values for these settings will differ depending on what CF endpoint you're using. Note also that the profile <tt>orion-test</tt> must be set, otherwise the tests will not run.
 +
 
 +
[[Image:Orion-test-maven-properties.png]]
 +
 
 +
==== Mocha–Sauce Labs integration ====
 +
Orion has a Sauce-enabled Mocha wrapper ([https://github.com/eclipse/orion.client/blob/master/bundles/org.eclipse.orion.client.core/web/mocha/sauce.js sauce.js]) which all mocha test pages must load. <!-- The wrapper manages communication with the Sauce Labs API that's wrangling the various browsers. --> The wrapper has 2 jobs:
 +
* '''Generate an xUnit report''' in addition to the regular HTML output displayed on the test page. The xUnit report is later downloaded by Hudson, and used to power the test results view on the build pages.
 +
* '''Compress the xUnit report.''' Sauce Labs has a 64KB limit on the request size returned from a browser. Because the xUnit output often exceeds 64KB, the Sauce wrapper compresses the output before sending it. The test runner application expands the output again when it obtains the test results from Sauce Labs.
 +
 
 +
= WAR build =
 +
=== WAR for Apache Tomcat ===
 +
To create and run a code.war to run within Apache Tomcat:
 +
 
 +
1) Download and unzip the latest Tomcat 8 into a folder something like <tt>/somewhere/apache-tomcat-8.0.12</tt>. Your java JRE will be in your path. Do not forget to:
 +
  % export CATALINA_HOME=/somewhere/apache-tomcat-8.0.12
 +
  % chmod +x $CATALINA_HOME/bin/*.sh
 +
  % export CATALINA_HOME=/ibm/apache-tomcat-8.0.12
 +
 
 +
2) Setup your Orion server development environment with Eclipse ( see [https://wiki.eclipse.org/Orion/Getting_the_source Getting the source])
 +
 
 +
3) In the <tt>org.eclipse.orion.server.war</tt> project, import the <tt>eclipse.equinox.servletbridge.psf</tt> project set file to import the Eclipse Equinox Servletbridge bundles used for the WAR file.
 +
 
 +
4) Open the <tt>war.product</tt> editor and select the Eclipse Product export wizard link in the editor.
 +
 
 +
5) Change the Root Directory field to <tt>WEB-INF</tt> and the Archive file to <tt>$CATALINA_HOME/webapps/code.war</tt>. The Allow for binary cycles should be selected.
 +
 
 +
6) Select the Finish button and the code.war is created.
 +
 
 +
7) Set the environment variable with required JVM properties (a custom logback is optional).
 +
  % export CATALINA_OPTS="-Dorion.core.configFile=$CATALINA_HOME/conf/orion.conf -Dlogback.configurationFile=$CATALINA_HOME/conf/logback.xml"
 +
 
 +
8) Create the file <tt>$CATALINA_HOME/conf/orion.conf</tt> and add any specific configuration properties that you need ( see [https://wiki.eclipse.org/Orion/Server_admin_guide Server Admin Guide]). At minimum you need to set the context root as:
 +
  orion.context.path=/code
 +
 
 +
9) If required, create the file <tt>$CATALINA_HOME/conf/logback.xml</tt> with any custom logging settings you need.
 +
 
 +
10) Setup your users within Tomcat. In the simple case, update the <tt>$CATALINA_HOME/conf/tomcat-users.xml</tt> and add users that will be used within Orion. These users need to have the "orion" role. Something like:
 +
  <tomcat-users>
 +
    <role rolename="manager-gui"/>
 +
    <role rolename="orion"/>
 +
    <user username="orion" password="orion" roles="orion"/>
 +
    <user username="admin" password="admin" roles="orion,manager-gui"/>
 +
  </tomcat-users>
 +
 
 +
11) Start Tomcat and navigate to <tt>http://localhost:8080/code/</tt>.
 +
 
 +
12) Login with your Tomcat user from (9).
 +
 
 +
=== WAR for IBM WebSphere Application Server Liberty Core ===
 +
 
 +
The steps for Liberty are very similar to those for the Tomcat WAR.
 +
 
 +
1) Download and install Liberty into a folder something like <tt>/ibm/Liberty</tt>.
 +
 
 +
2) Create your default server:
 +
  % /ibm/Liberty/bin/server create
 +
  Server defaultServer created.
 +
 
 +
3) Create a <tt>server.env</tt> file to specify your Java JRE:
 +
  % cat server.env
 +
  JAVA_HOME=/usr/lib/ibm-java-x86_64-71
 +
 
 +
4) Repeat steps (2) to (6) as in the Tomcat WAR but install the WAR into <tt>/ibm/Liberty/usr/servers/defaultServer/apps</tt>.
 +
 
 +
5) Create a <tt>jvm.properties</tt> file with required JVM properties. Something like:
 +
  % cat jvm.properties
 +
  -Xms2048m
 +
  -Xmx4096m
 +
  -Xmn1024m
 +
  -Dorion.core.configFile=/ibm/Liberty/usr/servers/defaultServer/orion.conf
 +
  -Dlogback.configurationFile=/ibm/Liberty/usr/servers/defaultServer/logback.xml
 +
  -Dosgi.instance.area=/ibm/Liberty/usr/servers/defaultServer/serverworkspace
 +
 
 +
6) Create the file <tt>/ibm/Liberty/usr/servers/defaultServer/orion.conf</tt> as in step (8) of the Tomcat WAR.
 +
 
 +
7) If required, create the file <tt>/ibm/Liberty/usr/servers/defaultServer/logback.xml</tt> as in step (9) of the Tomcat WAR.
 +
 
 +
8) Setup the <tt>server.xml</tt> for the server. Again you can customize your authentication, but a simple example file is something like:
 +
<pre>
 +
    <server description="Orion server">
 +
 
 +
        <!-- Enable features -->
 +
        <featureManager>
 +
            <feature>jsp-2.2</feature>
 +
            <feature>adminCenter-1.0</feature>
 +
            <feature>appSecurity-2.0</feature>
 +
            <feature>servlet-3.0</feature>
 +
        </featureManager>
 +
 
 +
        <variable name="defaultHostName" value="localhost" />
 +
 
 +
        <basicRegistry id="basic">
 +
            <user name="ahunter" password="test1234" />
 +
            <user name="admin" password="admin" />
 +
        </basicRegistry>
 +
 
 +
        <administrator-role>
 +
          <user>ahunter</user>
 +
          <user>admin</user>
 +
        </administrator-role>
 +
 
 +
        <keyStore id="defaultKeyStore" password="Liberty" />
 +
 
 +
        <httpEndpoint id="defaultHttpEndpoint"
 +
                      host="localhost"
 +
                      httpPort="8080"
 +
                      httpsPort="9443">
 +
            <accessLogging maxFiles="10"/>
 +
        </httpEndpoint>
 +
 
 +
        <applicationMonitor dropinsEnabled="false" />
 +
 
 +
        <application
 +
            id="code"
 +
            location="/ibm/Liberty/usr/servers/defaultServer/apps/code.war"
 +
            name="code"
 +
            context-root="code"
 +
            type="war">
 +
 
 +
            <classloader apiTypeVisibility="spec, ibm-api, third-party"/>
 +
 
 +
            <application-bnd>
 +
                <security-role name="orion">
 +
                    <user name="ahunter"/>
 +
                    <special-subject type="ALL_AUTHENTICATED_USERS" />
 +
                </security-role>
 +
            </application-bnd>
 +
        </application>
 +
 
 +
    </server>
 +
</pre>
 +
 
 +
9) Start the server:
 +
  % /ibm/Liberty/bin/server start
 +
  Starting server defaultServer.
 +
  Server defaultServer started with process ID 6688.
 +
 
 +
10) Login with your Libery user from (8).
  
 
= Node build =
 
= Node build =
The Node build produces a Node.js-based Orion server with minified client-side JavaScript code.
+
The Node build is a [http://gruntjs.com Grunt] script that produces a self-contained, Node.js-based Orion server with optimized client-side JavaScript code.  
  
As of this writing, the Node build does not happen automatically. Members of the Orion dev team run the build manually
+
The script runs automatically before Orion is published to the [https://www.npmjs.org/package/orion npm repository], but it can be run manually as well. The Orion dev team publishes builds on a regular basis, at least once per [https://wiki.eclipse.org/Orion/Plan milestone].
- to prepare Orion for publishing to the [https://npmjs.org/ npm repository]. Builds are published on a regular basis, at least once per [https://wiki.eclipse.org/Orion/Plan milestone].
+
  
== Running the build ==
+
== Running the Node build script ==
Run the shell script <tt>make-publish.sh</tt> from the <tt>modules/orionode/build/</tt> directory:
+
First, you should also install grunt globally:
  
<source lang="bash" >
+
<pre>
$ cd modules/orionode/build
+
npm install -g grunt
$ ./make-publish.sh /path/to/tempDir
+
</pre>
</source>
+
 
 +
Then ensure you have the dev dependencies the Orion Node server needs:
 +
 
 +
<pre>
 +
$ cd modules/orionode
 +
$ npm install
 +
</pre>
 +
 
 +
To run the build, simply run <tt>grunt</tt> from the orionode folder:
 +
 
 +
<pre>
 +
$ cd modules/orionode
 +
$ grunt
 +
 
 +
< lots of output >
 +
 
 +
Done, without errors.
 +
$
 +
</pre>
 +
 
 +
When the script finishes, <tt>modules/orionode</tt> contains a complete optimized server suitable for publishing to npm. Running <tt>node server.js</tt> as normal will launch the optimized server.
 +
 
 +
To produce a standalone optimized tarball of Orion, use the <tt>npm pack</tt> command:
 +
 
 +
<pre>
 +
$ npm pack
 +
 
 +
> orion@0.0.27 prepublish .
 +
> grunt
 +
 
 +
< lots of output >
 +
 
 +
Done, without errors.
 +
orion-0.0.27.tgz
 +
$
 +
</pre>
 +
 
 +
=== How it works ===
 +
The script copies all the client code from the top-level <tt>bundles/</tt> folder of the Orion client repo into <tt>modules/orionode/orion.client/bundles</tt>. The code is then "staged" (i.e. the runtime web-path structure is recreated on disk) to a temp directory, and RequireJS optimization is performed. After optimization, minified code and source maps are copied back into the bundle folders that they originated from. The end result is a self-contained directory.
 +
 
 +
To build a customized Orion server, edit <tt>Gruntfile.js</tt>. You can supply an alternative path to the Orion client code, or a different RequireJS build configuration (take care to maintain the Orion "shape", however: for example your build config must have a <tt>bundles</tt> property).
 +
 
 +
=== Publishing to npm (for package maintainers) ===
 +
There's a <tt>publish.sh</tt> script that performs a build and then publishes to the npm package repository if the build succeeded. You must be a maintainer of the <tt>orion</tt> package to publish, contact @mamacdon if you need access.
 +
 
 +
<pre>
 +
$ ./publish.sh
 +
<lots of grunt output>
 +
<lots of npm output>
  
The script takes a single argument, which is the output directory where the minified server will be generated. '''Everything in <tt>tempDir</tt> gets deleted''', so '''do not''' publish to an important directory.
+
</pre>
  
 
[[Category:Orion|Releng Builds]]
 
[[Category:Orion|Releng Builds]]
 
[[Category:Releng|Orion Releng Builds]]
 
[[Category:Releng|Orion Releng Builds]]

Latest revision as of 11:40, 3 March 2016

Orion currently has 3 kinds of builds:

  • The Tycho build is based on Tycho and Maven. It produces the official Orion downloads.
  • The Node build is a small script that runs on Node.js. It produces an Orion server that runs under Node.js.
  • The WAR build is capability that can run within Eclipse. It produces a war file that can run Orion within an application container such as Tomcat or WebSphere.

How to contribute

This section applies to all builds.

Contributing changes to the build

Contributing to a build is easy: just commit your code to the master stream of the Orion repository and it will be included in the next integration build.

Setting up your workspace

  1. See Orion/Getting the source for instructions on how to set up your workspace to work with Orion source code.

Contributing your changes

Once you have made code changes, you can contribute them to the Integration build as follows:

  • Commit your changes to the local repository and push them to the master
git commit -a -m "fix lots of bugs"                   #commits all changes
git push                                              #push local commits to the master

Minification

The Orion build performs optimization of client pages and plugins using RequireJS. Note the distinction between concatenation (inlining a module's AMD dependencies to reduce HTTP overhead) and minification (shrinking a module's JavaScript code size by removing whitespace). The build minifies all JavaScript code automatically, but getting your module concatenated requires an extra step. This section has instructions on how to add new content for concatenation in the build.

Adding a new module to the optimization

To add a new page or plugin for concatenation, you must update this file: releng/org.eclipse.orion.client.releng/builder/scripts/orion.build.js Find the property modules, and add an entry for your page/plugin.

Every entry needs a name property giving the module's web path. For example, here is the Git Commit page's entry:

    { name: "git/git-commit" },

The Tycho and Node builds all share orion.build.js, so your new module will be correctly built everywhere.

Adding a new client bundle to the JS build

  1. Add an entry to the bundles section of orion.build.js. (Ant-style property replacement is supported within the bundles entry, but ${orionClient} is the only property you should use there.)
  2. If your bundle contains any JSDocs, add an entry to the jsdocs section of orion.build.js.
  3. For each of the bundle's modules you want to optimize, add an entry to the modules section of orion.build.js. (see previous section).
  4. Add a pom.xml file in the root folder of your bundle.
  5. Add an entry to the <modules> section of the client repo's top-level pom.xml. This ensures that the Maven builder finds your bundle.
  6. Update the selfHostingRules.js file by adding an entry for the new bundle. This is required for your bundle's resources to be accessible when self-hosting Orion.

Building stand-alone features

Orion pages and plugins are handled by a multi-module invocation of r.js that optimizes all of them in one shot. However, stand-alone features need different build config options, which means r.js must be invoked separately for each of these features.

To build a stand-alone feature, you must add logic to the requirejs task in the Ant script orion.mini.xml. You must invoke r.js, passing the build file for your feature. Here is an example showing how a file used for the standalone Orion editor is minified:

  1.  <!-- Clean widget output directory -->
  2.  <target name="widgetClean" depends="widget.check" if="widget.run">
  3.     <delete dir="${widgetOutDirectory}" />
  4.     <mkdir dir="${widgetOutDirectory}" />
  5.  
  6.     <copy file="${builder}/scripts/editor.build-js.js" tofile="${staging}/editor.build-js.js" overwrite="true"/>
  7.     <!-- ... -->
  8.  </target>
  9.  
  10.  <target name="requirejs" depends="checkDirs, cleanStaging, cleanOptimized">
  11.      <!-- ... -->
  12.  
  13.      <!-- build standalone editor (unless skipEditor is set) -->
  14.      <antcall target="editorOptimize">
  15.          <param name="staging" value="${staging}" />
  16.          <param name="out" value="${widgetOutDirectory}" />
  17.      </antcall>
  18.  
  19.      <!-- ... -->
  20.  </target>
  21.  
  22.  <target name="editorOptimize" unless="skipEditor">
  23.      <sequential>
  24.          <!-- Invoke r.js -->
  25.          <widgetOptimizeFile
  26.             out="${out}/built-editor-amd.min.js"
  27.             buildfile="${staging}/editor.build-js.js"
  28.             optimize="closure"
  29.             staging="${staging}" />
  30.  
  31.          <!-- Additional calls to r.js can be placed here, if needed -->
  32.      </sequential>
  33.  </target>

Deploying builds to orion.eclipse.org or orionhub.org

Builds are deployed using the script deploy.sh. This script should be copied to your home directory and run from there. Your home directory will contain a symlink to the downloads directory, so you can perform a deploy directly from the downloads area. The script takes a single argument which is the location of the zip containing the download. For our servers we want the Linux 64-bit build. It is useful to log the output of this script so it can be reviewed later. Example:

./deploy.sh -archive downloads/orion/drops/I201201102230/eclipse-orion-I20120110-2230-linux.gtk.x86_64.zip >> deploy.log

This script simply copies the build onto the deployment server, and invokes an upgrade script on that server - upgrade.sh. The upgrade script shuts down the old server, moves it, unzips and configures the new build, and finally starts it.

The entire deploy/upgrade process takes about 5 seconds when it runs smoothly. Occasionally there will be a communication error copying the new build onto the target machine. In this case simply re-running the script usually succeeds.

Server configuration

The server configuration file on orion.eclipse.org and orionhub.org is found in ~admin/current/orion.conf. This file gets copied into the server by the deployment script. So, any change made to this configuration file will take effect only on the next deployment.


Tycho build

The Tycho builds use the Eclipse Tycho infrastructure (Category:Tycho), centered around Maven. Orion committers can manage Tycho builds using the Orion Hudson instance. We have 2 flavors of Tycho builds: development, which build off the master branch, and stable, which build off a stable branch that only production-ready features are merged into. Stable typically trails dev by a few weeks.

Build jobs

orion-client-dev

Builds Orion's client-side JavaScript code and performs JS minification. JavaScript tests are optionally executed (requires Sauce Labs and Cloud Foundry).

orion-server-dev

Downstream project of orion-client-dev. Builds Orion's Java server and runs Java tests.

Stable jobs: orion-client-stable, orion-server-stable

Running orion-client builds

You must have Apache Maven installed and on your system PATH.

To run a complete build, cd to the directory where you checked out the org.eclipse.orion.client repo, and run:

$ mvn clean install

A complete build takes 8-15 minutes to complete. To speed up the build, various features can be disabled by setting system properties passed to Maven with the -D argument. For example, this command runs a build without generating JSDocs for the Orion source.

$ mvn -DskipJsdoc clean install


A Note about Node.js

If you're running the build on Linux, Windows, or OS X, it should successfully download and run Node.js to perform JS minification. On more exotic platforms, this might fail, in which case you can run the build under Java 8's Nashorn JS engine instead by setting the -DskipNode system property or disabling the nodejs profile using -P '!nodejs'. Nashorn requires Java 8 or higher.


System Properties
skipNode Do not download Node.js; run the client minification under Nashorn instead. (The same effect can be achieved by disabling the nodejs profile, i.e. mvn -P '!nodejs'.)
skipJsdoc Do not generate JSDoc.
skipCommitBrowser Do not generate the stand-alone git commit browser widget.
skipCompareEditor Do not generate the stand-alone compare viewer widget.
skipEditor Do not generate the stand-alone Orion editor widget (built-editor.js).
skipEmbeddedEditor Do not generate the stand-alone Orion JS editor (built-codeEdit.zip).
skipEditorStylers Do not generate the stand-alone editor stylers.
skipOrionUI Do not optimize the Orion pages and plugins. This option will make the build substantially faster, at the cost of slower-loading pages when the build is deployed to a web server.
orion.client.build.skip Skips all of the above mentioned components. This saves the most time.

Running orion-server builds

You must have Apache Maven 3.x installed and on your system PATH.

To run a complete build, run:

 % git clone http://git.eclipse.org/gitroot/orion/org.eclipse.orion.client.git
 % git clone http://git.eclipse.org/gitroot/orion/org.eclipse.orion.server.git
 % cd org.eclipse.orion.server 
 % mvn clean install -P platform-kepler -Dorion.client.build.skip -DskipTests 
 % cd releng/org.eclipse.orion.server.repository/target/products/org.eclipse.orion/linux/gtk/x86_64/eclipse/ 
 % ./orion

If you want to have the client minified, then do not include

 -Dorion.client.build.skip

If you want to run the tests, then do not include

 -DskipTests

JavaScript tests

For good coverage of client-side JavaScript unit tests, it is desirable to run the tests under various web browsers. As of May 2014, unit tests in the orion-client-dev Hudson job execute in the Sauce Labs cloud which provides testing under various browser+OS platforms.

Architecture

The pom file responsible for managing the tests is releng/org.eclipse.orion.client.releng/pom.xml.

For Sauce Labs to run our tests, Orion's test code must be hosted on a web server that is accessible by the Sauce Labs cloud. Sauce Labs does provide a tunnel solution for testing code behind a firewall, but it does not work behind a proxy, which makes it unsuitable for Eclipse's Hudson environment.

For this reason, the test code is hosted on an external server that the build dynamically deploys to. The POM starts off by deploying a small test runner application to a Cloud Foundry environment (see Gruntfile.js for the test runner source.) The test runner is responsible for hosting the Orion client code as a web server, and invoking the Sauce Labs API to kick off the tests.

Sauce Labs uses its browser farm to load each test page's URL in turn and execute the tests. Each test page must use the Mocha–Sauce wrapper in order to correctly call back to Sauce at this step. The test pages return xUnit reports to Sauce showing passes and failures. Those reports are then echoed back to the test runner app, which collects them.

When all tests have finished, the runner enters a dormant state. In this state, any requests to https://{test_runner_url}/testresults will return a zip of all the test results. The build grabs the results, unzips them, and finishes.

Maven setup

To run the tests, Maven must be configured with a settings.xml file that contains the secret CF and Sauce authentication credentials. The file is generally located at $HOME/.m2/settings.xml and it should look like this:

<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 http://maven.apache.org/xsd/settings-1.0.0.xsd">
    <servers>
        <server>
            <id>orion-test-server</id>
            <username>[Cloud Foundry username]</username>
            <password>[Cloud Foundry password]</password>
        </server>
    </servers>
    <profiles>
        <profile>
            <id>orion-test</id>
            <properties>
                <SAUCE_USERNAME>[Sauce Labs username]</SAUCE_USERNAME>
                <SAUCE_ACCESS_KEY>[Sauce Labs Access Key]</SAUCE_ACCESS_KEY>
            </properties>
        </profile>
    </profiles>
</settings>

Additionally, some CF-related properties must be passed to Maven. This picture shows the required properties in Hudson. Your values for these settings will differ depending on what CF endpoint you're using. Note also that the profile orion-test must be set, otherwise the tests will not run.

Orion-test-maven-properties.png

Mocha–Sauce Labs integration

Orion has a Sauce-enabled Mocha wrapper (sauce.js) which all mocha test pages must load. The wrapper has 2 jobs:

  • Generate an xUnit report in addition to the regular HTML output displayed on the test page. The xUnit report is later downloaded by Hudson, and used to power the test results view on the build pages.
  • Compress the xUnit report. Sauce Labs has a 64KB limit on the request size returned from a browser. Because the xUnit output often exceeds 64KB, the Sauce wrapper compresses the output before sending it. The test runner application expands the output again when it obtains the test results from Sauce Labs.

WAR build

WAR for Apache Tomcat

To create and run a code.war to run within Apache Tomcat:

1) Download and unzip the latest Tomcat 8 into a folder something like /somewhere/apache-tomcat-8.0.12. Your java JRE will be in your path. Do not forget to:

 % export CATALINA_HOME=/somewhere/apache-tomcat-8.0.12
 % chmod +x $CATALINA_HOME/bin/*.sh
 % export CATALINA_HOME=/ibm/apache-tomcat-8.0.12

2) Setup your Orion server development environment with Eclipse ( see Getting the source)

3) In the org.eclipse.orion.server.war project, import the eclipse.equinox.servletbridge.psf project set file to import the Eclipse Equinox Servletbridge bundles used for the WAR file.

4) Open the war.product editor and select the Eclipse Product export wizard link in the editor.

5) Change the Root Directory field to WEB-INF and the Archive file to $CATALINA_HOME/webapps/code.war. The Allow for binary cycles should be selected.

6) Select the Finish button and the code.war is created.

7) Set the environment variable with required JVM properties (a custom logback is optional).

 % export CATALINA_OPTS="-Dorion.core.configFile=$CATALINA_HOME/conf/orion.conf -Dlogback.configurationFile=$CATALINA_HOME/conf/logback.xml"

8) Create the file $CATALINA_HOME/conf/orion.conf and add any specific configuration properties that you need ( see Server Admin Guide). At minimum you need to set the context root as:

 orion.context.path=/code

9) If required, create the file $CATALINA_HOME/conf/logback.xml with any custom logging settings you need.

10) Setup your users within Tomcat. In the simple case, update the $CATALINA_HOME/conf/tomcat-users.xml and add users that will be used within Orion. These users need to have the "orion" role. Something like:

 <tomcat-users>
   <role rolename="manager-gui"/>
   <role rolename="orion"/>
   <user username="orion" password="orion" roles="orion"/>
   <user username="admin" password="admin" roles="orion,manager-gui"/>
 </tomcat-users>

11) Start Tomcat and navigate to http://localhost:8080/code/.

12) Login with your Tomcat user from (9).

WAR for IBM WebSphere Application Server Liberty Core

The steps for Liberty are very similar to those for the Tomcat WAR.

1) Download and install Liberty into a folder something like /ibm/Liberty.

2) Create your default server:

 % /ibm/Liberty/bin/server create
 Server defaultServer created.

3) Create a server.env file to specify your Java JRE:

 % cat server.env 
 JAVA_HOME=/usr/lib/ibm-java-x86_64-71

4) Repeat steps (2) to (6) as in the Tomcat WAR but install the WAR into /ibm/Liberty/usr/servers/defaultServer/apps.

5) Create a jvm.properties file with required JVM properties. Something like:

 % cat jvm.properties
 -Xms2048m
 -Xmx4096m
 -Xmn1024m
 -Dorion.core.configFile=/ibm/Liberty/usr/servers/defaultServer/orion.conf
 -Dlogback.configurationFile=/ibm/Liberty/usr/servers/defaultServer/logback.xml
 -Dosgi.instance.area=/ibm/Liberty/usr/servers/defaultServer/serverworkspace

6) Create the file /ibm/Liberty/usr/servers/defaultServer/orion.conf as in step (8) of the Tomcat WAR.

7) If required, create the file /ibm/Liberty/usr/servers/defaultServer/logback.xml as in step (9) of the Tomcat WAR.

8) Setup the server.xml for the server. Again you can customize your authentication, but a simple example file is something like:

    <server description="Orion server">

        <!-- Enable features -->
        <featureManager>
            <feature>jsp-2.2</feature>
            <feature>adminCenter-1.0</feature>
            <feature>appSecurity-2.0</feature>
            <feature>servlet-3.0</feature>
        </featureManager>

        <variable name="defaultHostName" value="localhost" />

        <basicRegistry id="basic">
            <user name="ahunter" password="test1234" />
            <user name="admin" password="admin" />
        </basicRegistry>

        <administrator-role>
           <user>ahunter</user>
           <user>admin</user>
        </administrator-role>

        <keyStore id="defaultKeyStore" password="Liberty" />

        <httpEndpoint id="defaultHttpEndpoint"
                      host="localhost"
                      httpPort="8080"
                      httpsPort="9443">
            <accessLogging maxFiles="10"/>
        </httpEndpoint>

        <applicationMonitor dropinsEnabled="false" />

        <application
            id="code"
            location="/ibm/Liberty/usr/servers/defaultServer/apps/code.war"
            name="code"
            context-root="code"
            type="war">

            <classloader apiTypeVisibility="spec, ibm-api, third-party"/>

            <application-bnd>
                <security-role name="orion">
                    <user name="ahunter"/>
                    <special-subject type="ALL_AUTHENTICATED_USERS" />
                </security-role>
            </application-bnd>
        </application>

    </server>

9) Start the server:

 % /ibm/Liberty/bin/server start
 Starting server defaultServer.
 Server defaultServer started with process ID 6688.

10) Login with your Libery user from (8).

Node build

The Node build is a Grunt script that produces a self-contained, Node.js-based Orion server with optimized client-side JavaScript code.

The script runs automatically before Orion is published to the npm repository, but it can be run manually as well. The Orion dev team publishes builds on a regular basis, at least once per milestone.

Running the Node build script

First, you should also install grunt globally:

npm install -g grunt

Then ensure you have the dev dependencies the Orion Node server needs:

$ cd modules/orionode
$ npm install

To run the build, simply run grunt from the orionode folder:

$ cd modules/orionode
$ grunt

< lots of output >

Done, without errors.
$ 

When the script finishes, modules/orionode contains a complete optimized server suitable for publishing to npm. Running node server.js as normal will launch the optimized server.

To produce a standalone optimized tarball of Orion, use the npm pack command:

$ npm pack

> orion@0.0.27 prepublish .
> grunt

< lots of output >

Done, without errors.
orion-0.0.27.tgz
$

How it works

The script copies all the client code from the top-level bundles/ folder of the Orion client repo into modules/orionode/orion.client/bundles. The code is then "staged" (i.e. the runtime web-path structure is recreated on disk) to a temp directory, and RequireJS optimization is performed. After optimization, minified code and source maps are copied back into the bundle folders that they originated from. The end result is a self-contained directory.

To build a customized Orion server, edit Gruntfile.js. You can supply an alternative path to the Orion client code, or a different RequireJS build configuration (take care to maintain the Orion "shape", however: for example your build config must have a bundles property).

Publishing to npm (for package maintainers)

There's a publish.sh script that performs a build and then publishes to the npm package repository if the build succeeded. You must be a maintainer of the orion package to publish, contact @mamacdon if you need access.

$ ./publish.sh
<lots of grunt output>
<lots of npm output>

Back to the top