Have questions? Stuck? Please check our FAQ for some common questions and answers.

Note: This page refers to the legacy GUI, not GUI2. See Appendix I - GUI2 Development instead

To help with UI development we provide a dedicated environment that introduce an auto reload feature and allow you to change your javascript files without recompiling the application.


  1. NodeJS & NPM 
  2. *nix environment

    NodeJS version

    UI Development server uses a special `harmony_destructuring` flag that works well with node versions > 5.x

    For node version >= 6, you may want to use `–harmony_destructuring_bind` instead.

    Disabling JS minification

    From ONOS 1.10 onwards, JS & CSS files will be minified for better performance. However this minification would prevent the file changes getting picked up by development server.

    So make sure you comment out 40th line in `tools/gui/gulp-tasks/bundles/bundle-js/index.js` before attempting to use this.

Installing NodeJS 5.x from tar.gz option:

Though there are several versions of NodeJS and several ways to install NodeJS, installing from pre-built tar.gz package is the most efficient way.

  •  Download Node 5.x version using wget
  • Install NodeJS binary in /usr/local as follows
  • NodeJS 5.x installation
    cd /usr/local
    tar --strip-components 1 -xzf <path-to-downloaded>/node-v5<ver>-linux-x64.tar.gz
  • Verify installation
  • Verifying Installation
    :~/onos/web/gui/src/main/webapp$ node -v

Installing & Starting Development Server:

  1. Enter `web/gui/src/main/webapp/` folder

  2. Run `npm install` to install required dependency

  3. Run `npm start` to open start the development environment

In the console you should see something like:

Development Server Console
In the console you should see something like:
Dev server is up and listening on http://localhost: 8182
[BS] Proxying: http://localhost:8181
[BS] Access URLs:
       Local: http://localhost:3000
          UI: http://localhost:3002
 UI External:
[BS] Watching files...

To open ONOS visit the local URL (eg: `http://localhost:3000`) plus `/onos/ui`
(eg: `http://localhost:3000/onos/ui`)

Loading files from external applications

The UI development environment provide the ability to serve UI files from an external forlder that can be specified with:

`ONOS_EXTERNAL_APP_DIRS="appName:path-to-the-first-folder" npm start`

`ONOS_EXTERNAL_APP_DIRS="sampleCustom:../../meow/sample/meowster-sample/" npm start`

Note that ONOS_EXTERNAL_APP_DIRS is an environment variable,so it can be set with

export ONOS_EXTERNAL_APP_DIRS="sampleCustom:../../meow/sample/meowster-sample/"