yellow team mailing list archive

[Gary Poster <gary.poster@xxxxxxxxxxxxx>]

Gary Poster has proposed merging lp:~gary/charms/precise/juju-gui/trunk into lp:~juju-gui/charms/precise/juju-gui/trunk.

Requested reviews:
  Juju GUI Hackers (juju-gui)

For more details, see:
https://code.launchpad.net/~gary/charms/precise/juju-gui/trunk/+merge/139968

Update documentation

The README was incorrect, and did not warn users about current issues with the charm.  Update the README and HACKING documentation to give more complete instructions and better detail.

https://codereview.appspot.com/6945058/

-- 
https://code.launchpad.net/~gary/charms/precise/juju-gui/trunk/+merge/139968
Your team Juju GUI Hackers is requested to review the proposed merge of lp:~gary/charms/precise/juju-gui/trunk into lp:~juju-gui/charms/precise/juju-gui/trunk.

=== modified file 'HACKING.txt'
--- HACKING.txt	2012-12-13 13:50:59 +0000
+++ HACKING.txt	2012-12-14 17:10:30 +0000
@@ -2,39 +2,39 @@
 Juju GUI Charm Development
 ==========================
 
-
-Testing
-=======
-
-There are two types of tests for the charm: unit tests and functional tests.
-
-
-Unit Tests
-----------
-
-The unit tests do not require a functional Juju environment, and can be run
-with this command::
-
-    python tests/unit.test
-
-Unit tests should be created in the "tests" subdirectory and be named in the
-customary way (i.e., "test_*.py").
-
-
-Functional Tests
-----------------
-
-Running the functional tests requires a Juju testing environment as provided
-by the Jitsu test command.  All files in the tests directory which end with
-".test" will be run in a Juju Jitsu test environment.
-
-
-Functional Test Setup
-~~~~~~~~~~~~~~~~~~~~~
-
-At the time of this writing the Jitsu test command is not yet released.  To run
-it you must first install it locally.  The files may be installed globally, or
-into your home directory (as here)::
+Contacting the Developers
+=========================
+
+Hi.  Thanks for looking at the charm.  If you are interested in helping us
+develop, we'd love to hear from you.  Our developer-oriented discussions
+happen on freenode's IRC network in the #juju-gui channel, and you can also
+join `the GUI developers mailing list
+<https://lists.ubuntu.com/mailman/listinfo/juju-gui>`_.
+
+
+Getting Started
+===============
+
+First, you need a configured Juju environment: see the Juju docs about
+`getting started <https://juju.ubuntu.com/docs/getting-started.html>`. If you
+do not yet have an environment defined, the Jitsu command "setup-environment"
+is an easy way to get started.
+
+You'll also need some dependencies and developer basics.
+
+  $ sudo apt-get install bzr autoconf libtool python-charmhelpers
+
+Next, you need the bzr branch.  We work from
+`lp:~juju-gui/charms/precise/juju-gui/trunk
+<https://code.launchpad.net/~juju-gui/charms/precise/juju-gui/trunk>`_.
+
+You could start hacking now, but there's a bit more to do to prepare for
+running and writing tests.
+
+We use the Jitsu test command to run our functional tests.  At the time of
+this writing it is not yet released.  To run it you must first install it
+locally.  The files may be installed globally, or into your home directory (as
+here)::
 
     sudo apt-get install autoconf libtool python-charmhelpers
     bzr branch lp:~jimbaker/juju-jitsu/unit-test jitsu-unit-test
@@ -57,12 +57,34 @@
 
 Now you are ready to run the functional tests (see the next section).
 
-
-Running the Functional Tests
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Jitsu requires the charm directory be named the same as the charm and it be the
-current working directory when the tests are run::
+Testing
+=======
+
+There are two types of tests for the charm: unit tests and functional tests.
+
+
+Unit Tests
+----------
+
+The unit tests do not require a functional Juju environment, and can be run
+with this command::
+
+    python tests/unit.test
+
+Unit tests should be created in the "tests" subdirectory and be named in the
+customary way (i.e., "test_*.py").
+
+
+Functional Tests
+----------------
+
+Running the functional tests requires a Juju testing environment as provided
+by the Jitsu test command (see `Getting Started`_, above).  All files in the
+tests directory which end with ".test" will be run in a Juju Jitsu test
+environment.
+
+Jitsu requires the charm directory to be named the same as the charm and to be
+the current working directory when the tests are run::
 
     JUJU_REPOSITORY=/path/to/charm/repo ~/bin/jitsu test juju-gui \
         --logdir /tmp --timeout 40m
@@ -70,20 +92,22 @@
 This command will bootstrap the default Juju environment specified in your
 ``~/.juju/environments.yaml``.
 
-If you are going to run the tests often, you probably want to set up LXC and
-run the tests locally by setting your default environment to a "local" one.
-Among other things you will need to install apt-cacher-ng and LXC to do so.
+LXC
+~~~
+
+Unfortunately, we have not found LXC-based Juju environments to be reliable
+for these tests.  At this time, we recommend using other environments, such as
+OpenStack; but we will periodically check the tests in LXC environments
+because it would be great to be able to use it.  If you do want to use LXC,
+you will need to install the apt-cacher-ng and lxc packages.
 
 Unfortunately, currently running tests on a local environment is quite slow
 (with quantal host and precise container at least), so you may want to further
 increase the ``jitsu test`` command timeout.
 
-If Jitsu generates errors about not being able bootstrap::
+If Jitsu generates errors about not being able to bootstrap...::
 
     CalledProcessError: Command '['juju', 'bootstrap']'...
 
-...or it hangs, then you may need to bootstrap the environment yourself and
+...or if it hangs, then you may need to bootstrap the environment yourself and
 pass the --no-bootstrap switch to Jitsu.
-
-If you do not yet have an environment defined, the Jitsu command
-"setup-environment" is an easy way to get started.

=== modified file 'README.txt'
--- README.txt	2012-12-13 13:00:12 +0000
+++ README.txt	2012-12-14 17:10:30 +0000
@@ -5,27 +5,101 @@
 This charm makes it easy to deploy a Juju GUI into an existing environment.
 
 
+Warning
+=======
+
+The GUI and charm have two important limitations that we are actively working
+on.  We plan to publicly announce this charm once these limitations are
+resolved.  We expect this to happen in early January, 2013.
+
+First, there is no security.  Anyone who can connect to your machines can
+connect to the websocket that controls your Juju instance.  To mitigate the
+problem, make sure that the machine that runs your GUI charm can only be
+accessed by machines you control.  The upcoming solution will use HTTPS and a
+password (specifically, your Juju environment's admin-secret).
+
+Second, the charm uses the GUI trunk by default, rather than a release.  This
+introduces unnecessary fragility and slowness.  Again, we are working to fix
+this.
+
+
 Deploying the Juju GUI
 ======================
 
-Deploying the Juju GUI is obviously accomplished using Juju itself.
-
-You need a configured Juju environment: see the Juju docs about
-`getting started <https://juju.ubuntu.com/docs/getting-started.html>`_).
-
-Then you need to link this checkout of the Juju GUI charm from within the
-charm repository::
-
-  $ ln -s /path/to/charm/checkout/ /path/to/charm/repo/juju-gui
-
-Deploying parameters may be configured by creating a configuration file in
-YAML format. A synopsis of the available options is found in ``config.yaml``.
-
-Finally, run the following commands::
+Deploying the Juju GUI is accomplished using Juju itself.
+
+You need a configured and bootstrapped Juju environment: see the Juju docs
+about `getting started <https://juju.ubuntu.com/docs/getting-started.html>`_,
+and then run the usual bootstrap command.
 
   $ juju bootstrap
-  $ juju deploy --config config.yaml juju-gui
-  $ juju expose
-
-It will take a while, run ``juju status`` until the unit machine is active.
-The Juju GUI will then be accessible at <http://unit-machine-name/>.
+
+Next, you simply need to deploy the charm and expose it.  (See also `Deploying
+with Jitsu`_ below, for another option.)
+
+  $ juju deploy cs:~juju-gui/precise/juju-gui
+  $ juju expose juju-gui
+
+Finally, you need to identify the GUI's URL--sadly, the most annoying part of
+the process at the moment.  Right now (see the warning section above about not
+yet working with GUI releases) it can take an excessive amount of time for the
+GUI to be built and to start--20 minutes or more.  This command will let you
+see when it is ready to go by giving you regular status updates.
+
+  $ watch juju status
+
+Eventually, after many minutes, at the end of the status you will hopefully see
+something that looks like this:
+
+services:
+  juju-gui:
+    charm: cs:~juju-gui/precise/juju-gui-7
+    exposed: true
+    relations: {}
+    units:
+      juju-gui/0:
+        agent-state: started
+        machine: 1
+        open-ports:
+        - 80/tcp
+        - 8080/tcp
+        public-address: ec2-204-236-250-8.compute-1.amazonaws.com
+
+That tells me I can go to the public-address in my browser
+(http://ec2-204-236-250-8.compute-1.amazonaws.com/ in this example), and start
+configuring the rest of Juju with the GUI.  You should see something similar.
+
+Again, until we switch to releases, the charm is fragile.  As I write this,
+when run withing the charm, the GUI appears to not be connecting properly to
+Juju.  Until the charm works with QA'd releases rather than branches (soon!),
+be prepared for unpleasant surprises like this.
+
+
+Deploying with Jitsu
+--------------------
+
+The instructions above cause you to use a separate machine to work with the
+GUI.  If you'd like to reduce your machine footprint (and perhaps your costs),
+you can colocate the GUI with the Juju bootstrap node.  This approach will
+change in the future (probably with the Juju shipped with Ubuntu 13.04), so be
+warned.
+
+For now, though, install Jitsu...::
+
+  $ sudo apt-get install juju-jitsu
+
+...and then replace "juju deploy cs:~juju-gui/precise/juju-gui" from the
+previous instructions with this::
+
+  $ jitsu deploy-to 0 cs:~juju-gui/precise/juju-gui
+
+Contacting the Developers
+=========================
+
+If you run into problems with the charm, please feel free to contact us on the
+`Juju mailing list <https://lists.ubuntu.com/mailman/listinfo/juju>`_, or on
+freenode's IRC network on #juju.  We're not always around (working hours in
+Europe and NA are your best bets), but if you send us a mail or ping "jujugui"
+we will eventually get back to you.
+
+If you want to help develop the charm, please see the charm's HACKING.txt.

=== modified file 'revision'
--- revision	2012-12-10 19:11:50 +0000
+++ revision	2012-12-14 17:10:30 +0000
@@ -1,1 +1,1 @@
-14
+15