~hatch/juju-gui/browser-fix-1217060

.. Run "make view-main-doc" to render this file and read it in the browser

   alongside the whole project documentation. To do this, you need the

   dependencies described in the "Documentation" section below.

=======

HACKING

=======

Here is how to develop on this codebase.

Developer Install

=================

Before you get the GUI you need to get Juju. We use the fresh one from the Juju

PPA. For PyJuju, the original Python-based implementation, we also use a custom

branch of Juju that supplies the websocket API we need.  (GoJuju, the newer

Go-based implementation, will have a websocket API provided for us directly as

part of the software.)

::

  sudo add-apt-repository ppa:juju/pkgs

  sudo apt-get update

  sudo apt-get install juju zookeeper

Next you will also need to get the Juju branch that has API access.

Currently that work resides in a pipeline of Juju branches. The

recommended branch to use as a server is ``rapi-rollup`` by hazmat::

  bzr branch lp:~hazmat/juju/rapi-rollup

For development, we always use a nice testing script in that branch that

allows you to interact with Juju without actually deploying real machines.  In

the rapi-rollup branch, run ``python improv.py -h`` to get an idea of its

capabilities.  Note that your Python needs Twisted and Zookeeper installed,

but the ``sudo apt-get install juju zookeeper`` command above should have

already taken care of that for you.

Go ahead and use the branch's ``sample.json`` file to pre-populate the

environment.  In the future, you might want to investigate the ``large.json``

also available there.

::

  python improv.py -f sample.json

Now it is time to actually get the GUI itself set up.  Juju GUI uses

nodejs-based development tools, so you will need ``nodejs`` from Chris

Lea's node PPA. You also need ImageMagick for sprite generation, lbox to

propose branches, python-sphinx and python-yaml to build docs, PyTZ to make

releases, python-shelltoolbox and python-selenium for browser tests, and

python-virtualenv to build the Google Closure linter tools locally::

  sudo add-apt-repository ppa:chris-lea/node.js

  sudo add-apt-repository ppa:gophers/go

  sudo apt-get update

  sudo apt-get install nodejs imagemagick lbox python-sphinx python-yaml \

    python-tz python-virtualenv python-shelltoolbox python-selenium \

    python-tornado python-gflags

See :ref:`Browser Testing <browser-testing>` if you are curious about the

reason for ``python-shelltoolbox`` and ``python-selenium``.

The jshint linter will be installed locally per branch, but if you want editor

integration, you may want to install ``jshint`` globally in your system.  More

importantly, to support testing from the command line, ``phantomjs`` and

``mocha-phantomjs`` should be installed globally.

::

  sudo npm install -g jshint@2.1.3 mocha-phantomjs@2.0.0 phantomjs@1.9.1-0

Note: Make sure to get the latest phantomjs from npm and not rely on an older

.deb packaged version. mocha-phantomjs will fail silently when running.

If you receive an error installing phantomjs, you can manually download and

unpack the archive and then arrange for the ``phantomjs`` executable to be

located on your path (e.g., by linking it into ``~/bin``).

The Juju GUI can now be installed and run with::

  bzr branch lp:juju-gui trunk

  cd trunk

  make devel

It may take a while for the server to start the first time as npm will

need to download packages.  When ready, the server will print::

  Server listening on 8888

You can then access the GUI at <http://localhost:8888/>.

If you receive an error like::

  fs.js:837

     throw errnoException(errno, 'watch');

           ^

  Error: watch ENOSPC

You can increase your watch limit by creating or editing::

  /etc/sysctl.d/10-inotify.conf

Add in the following::

  # expand inotify limit

  fs.inotify.max_user_watches=16384

Then::

  sudo sysctl -p

  cat /proc/sys/fs/inotify/max_user_watches

If it does not echo ``16384`` then you will need to restart.

Note that the Makefile supports ``make help`` to try to introduce some of the

more important targets.  Also note that if you use the "make prod" target

while using the PyJuju ``rapi-rollup`` improv script, the password you should

use is "admin," despite the help text you see.

Typical Bzr workflow

=====================

Bazaar allows you to work in a lot of different workflows. Here is one that

works well for our environemnt, if you are not already familiar with bzr.

To set up the environment::

  bzr init-repo juju-gui

  cd juju-gui

  bzr branch lp:juju-gui trunk

  mkdir yourUseName

  bzr branch trunk/{featureBranchName}

To link branch to ticket::

  bzr commit --fixes=lp:{ticketNumber}

To push code::

  bzr push lp:~{yourUserName}/juju-gui/{featureBranchName}

To submit for review::

  lbox propose -cr

After review, to merge into trunk::

  lbox submit

Working with a Real Juju

========================

The easiest way to work with a real Juju installation, as opposed to the

``improv`` script described above, is to use the Juju charm.  See

<http://jujucharms.com/~juju-gui/precise/juju-gui> or

<http://jujucharms.com/charms/precise/juju-gui> for details.

Alternatively, you can try the instructions below, but be warned that they

have bit-rotted and we have not felt the need to update them.  If you get them

to work, please update the docs and submit a branch for review (see below).

Bit-Rotted Instructions

-----------------------

You can use the GUI with any environment, but for development purposes, a

local environment works well. One environment option specific to this branch

is the ``api-port``. An appropriate sample configuration::

  default: dev

  environments:

    dev:

      type: local

      data-dir: /home/kapil/.juju/local

      admin-secret: b3a5dee4fb8c4fc9a4db04751e5936f4

      default-series: precise

      juju-origin: ppa

      api-port: 8081

Note that ``juju-origin`` is set to the PPA, the API server runs outside of

the container, and it is launched using whichever branch you are using.

Also note that the ``api-port`` should be set at ``8081``, which the GUI's

initial environment connection currently defaults to.

You will need to bootstrap the local environment, and deploy one service.

The API server needs access to the provisioning credentials which are

lazily initialized in Juju upon usage.

``Juju-gui`` and ``rapi-rollup`` can communicate via an encrypted WebSocket

connection: to enable it, add the following line to the config above::

  api-secure: true

You will also need to edit ``app/config-debug.js`` and ``app/config-prod.js``

replacing ``ws://localhost:8081/ws`` with ``wss://localhost:8081/ws``.

By default, ``rapi-rollup`` uses a self-signed certificate; because of that you

will need to visit the <https://localhost:8081/ws> WebSocket URL with your

browser and accept the included self-signed certificate, or the WebSocket

encrypted connection will not work.

In order to use a different certificate you add an ``api-keys`` option to the

config above: its value will be the path of the directory containing the

certificate and the private key, whose filenames will have to be respectively

``juju.crt`` and ``juju.key``.

After this, the GUI should be functional (it automatically polls the

API server for establishing a websocket).

Running Unit Tests

==================

``make test-prod`` or ``make test-debug`` will run the CLI based test

runner. If you need to debug a test in the browser, use ``make test-server``.

Running Lint

============

Run the linters with ``make lint``.  ``make beautify`` will use the Google

Closure tools to try and force the code to conform to some of the guidelines,

with variable success.  It can help, but we suggest you first commit your code

to your branch and only then run make beautify, so you can easily see and

evaluate the changes it made.

If you have done a large refactoring and the yuidoc linter complains about a

lot of code that no longer exists or has been moved or renamed, note that

``make undocumented`` can reproduce the undocumented file so as to quiet the

linter. If you need to do this, please make sure that the length (``wc -l``)

of the new "undocumented" file is the same or smaller than it was before.

.. _all-docs:

Documentation

=============

The ``make docs`` command generates the code and the project documentation

together. The ``make view-docs`` command does the above and also opens both

docs in the browser.

Code Documentation

------------------

Generated documentation for the JavaScript code is available in the ``yuidoc/``

directory.  You can build and view the docs by running::

  make view-code-doc

See the :ref:`style guide <embedded-docs>` document for details on how to

write the embedded documentation.

Project Documentation

---------------------

The project documentation is available in the ``docs/`` directory. As already

mentioned in the developer installation instructions above, it needs Sphinx

and Python-yaml.  To build and view the documentation, use these commands::

  make view-main-doc

Filing Bugs

===========

Please file bugs here:

https://bugs.launchpad.net/juju-gui/+filebug

Proposing Branches

==================

We use ``lbox`` to propose branches for review and submit them to the trunk.

Gustavo Niemeyer has `a helpful blogpost`_ about this tool.  See the

:ref:`Process document <preparing-reviews>` for a step-by-step checklist on how

to prepare branches for review.

.. _`a helpful blogpost`:

    http://blog.labix.org/2011/11/17/launchpad-rietveld-happycodereviews

Making Targets Quickly Without Bazaar

=====================================

Within a checkout, a lightweight checkout, or a branch, you may run make as

``NO_BZR=1 make [target]`` in order to prevent the Makefile from running any

Bazaar commands, all of which access the parent branch over the network. Where

Bazaar may have provided information such as the revno, sensible defaults are

used instead.  Because many of these Bazaar commands are used to populate

variables regardless of the target, defining NO_BZR will have an effect on all

targets, except ``dist``, which will refuse to complete.

Note that this allows one to run any make target from the working copy, even

if it is a lightweight checkout, by skipping steps that involve network access

through Bazaar.  Because of this, make will assume that the revno is

0 and that the branch is clean and up to date without checking that it is a

checkout of trunk.  The resulting tarball or build may be used to test

releases by hand or in the charm.

Making Releases

===============

See the :ref:`Process document <make-releases>` for step-by-step checklists to

make developer and stable releases.  The following is additional detail and an

overview.

To make a release, you must either be in a checkout of ``lp:juju-gui``

without uncommitted changes, or you must override one of the

`pertinent variable names`_ to force a release.

.. _`pertinent variable names`:

    `Potentially Useful Release-Oriented Makefile Variables`_

To make the release tarball use ``make distfile``.

In order to make and upload the release (``make dist``), you also need to have

a GPG key, and the ``python-pytz`` package installed (as well as

``launchpadlib``, but that is installed by default in Ubuntu).

Potentially Useful Release-Oriented Makefile Variables

------------------------------------------------------

The following is a list of pertinent Makefile variables.

``FINAL``

  Set ``FINAL`` to any non-empty value to make a final release. This will cause

  the ``bzr revno`` to be omitted from the tarball name, and (if you use the

  release target) will cause the release to be uploaded to the stable series

  rather than the trunk series. Example usage::

    FINAL=1 make dist

``PROD``

  By default, releases will be uploaded to ``staging.launchpad.net``, which is

  a separate version of Launchpad that uses a temporary database.  This can be

  convenient for trying out the release process in the Makefile without

  affecting our actual production releases.  Set ``PROD`` to any non-empty

  value to send uploads to ``launchpad.net``, the production version of

  Launchpad, when you are ready to make a real release.

  Note that you may need to ask the webops to turn off the two-factor

  authentication on your Launchpad staging account in order for the staging to

  work. Go to the ``#launchpad-ops`` channel on the Canonical IRC server and

  ask something like "webops, could you disable 2FA on my staging account?".

  Example usage::

    PROD=1 make dist

``IS_TRUNK_BRANCH``

  Set this to any non-empty value to force the Makefile to believe it is

  working with a trunk checkout. Example usage::

    IS_TRUNK_BRANCH=1 make dist

``BRANCH_IS_CLEAN``

  Set this to any non-empty value to force the Makefile to believe that the

  current code tree has no changes. Example usage::

    BRANCH_IS_CLEAN=1 make dist

``BRANCH_IS_GOOD``

  Set this to any non-empty value to force the Makefile to bypass checks of

  ``IS_TRUNK_BRANCH`` and ``BRANCH_IS_CLEAN``. Example usage::

    BRANCH_IS_GOOD=1 make dist

Updating the ``nodejs`` dependencies

====================================

The ranges of allowed versions for the ``nodejs`` dependency packages are

specified in the top-level ``package.json`` file. However, the actual installed

versions are frozen in the top-level ``npm-shrinkwap.json`` file, which

overrides the former.

The ``npm-shrinkwap.json`` file is generated by the ``npm shrinkwrap`` command

(see `shrinkwrap - Lock down dependency versions`_) on the basis of the

packages currently installed by any of the ``make build-[something]`` commands.

The procedure for updating the dependency versions is described in the

`Building shrinkwrapped packages`_ section of the aforementioned document. In

a nutshell:

1) review the ``package.json`` file and see whether any constraints may be

   updated, in order to allow using newer package versions;

2) delete the ``npm-shrinkwrap.json`` file;

3) run ``make``, getting all new dependencies;

4) check that everything works well;

If everything is fine, regenerate the ``npm-shrinkwap.json`` file by running

the ``npm shrinkwrap`` command.

If something is broken find the culprit, adjust the ``package.json`` file

accordingly, and go back to step #3.

Alternatively, you might use the ``npm outdated`` command to get the update

candidates, and do the job one step at a time rather than all at once.

.. _`shrinkwrap - Lock down dependency versions`:

    https://npmjs.org/doc/shrinkwrap.html

.. _`Building shrinkwrapped packages`:

    https://npmjs.org/doc/shrinkwrap.html#Building-shrinkwrapped-packages