Merge lp:~koolhead17/pyjuju/jujudoc into lp:pyjuju

[koolhead17]

I have modified 2 files currently :-

1. write-charm.rst

We need to create separate revision file for charms, done that and explained about the revision file.

2. provider-configuration-local.rs
Added :

       control-bucket
       juju-origin

[Kapil Thangavelu (hazmat)]

this is pretty indecipherable due to how merge was setup. the underlying changes should be reflected already (revision as separate file), although the local provider could still use origin info, control-bucket doesn't apply to it.

review: Needs Fixing

[Kapil Thangavelu (hazmat)]

also please note that docs are now in a separate docs branch with a much wider reviewer base and committer audience and are part of the charmers review queue (http://jujucharms.com/review-queue).

Unmerged revisions

2. By Atul Jha <email address hidden> on 2012-01-18

added saperate revision file or write-charm.rst and added missing config files for provider-configuration-local.rst file

1. By Kapil Thangavelu on 2011-12-09

move docs over

=== added file 'Makefile'
--- Makefile	1970-01-01 00:00:00 +0000
+++ Makefile	2012-01-18 20:50:30 +0000
@@ -0,0 +1,132 @@
+# Makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    =
+SPHINXBUILD   = python source/generate_modules.py ../juju source/generated && sphinx-build
+PAPER         =
+BUILDDIR      = build
+
+# Internal variables.
+PAPEROPT_a4     = -D latex_paper_size=a4
+PAPEROPT_letter = -D latex_paper_size=letter
+ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
+
+.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest
+
+help:
+	@echo "Please use \`make <target>' where <target> is one of"
+	@echo "  html       to make standalone HTML files"
+	@echo "  dirhtml    to make HTML files named index.html in directories"
+	@echo "  singlehtml to make a single large HTML file"
+	@echo "  pickle     to make pickle files"
+	@echo "  json       to make JSON files"
+	@echo "  htmlhelp   to make HTML files and a HTML help project"
+	@echo "  qthelp     to make HTML files and a qthelp project"
+	@echo "  devhelp    to make HTML files and a Devhelp project"
+	@echo "  epub       to make an epub"
+	@echo "  latex      to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
+	@echo "  latexpdf   to make LaTeX files and run them through pdflatex"
+	@echo "  text       to make text files"
+	@echo "  man        to make manual pages"
+	@echo "  changes    to make an overview of all changed/added/deprecated items"
+	@echo "  linkcheck  to check all external links for integrity"
+	@echo "  doctest    to run all doctests embedded in the documentation (if enabled)"
+	@echo "  clean      to clean (remove) everything under the build directory"
+
+clean:
+	-rm -rf $(BUILDDIR)/*
+	-rm -rf source/generated
+
+html:
+	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
+
+dirhtml:
+	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
+
+singlehtml:
+	$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
+	@echo
+	@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
+
+pickle:
+	$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
+	@echo
+	@echo "Build finished; now you can process the pickle files."
+
+json:
+	$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
+	@echo
+	@echo "Build finished; now you can process the JSON files."
+
+htmlhelp:
+	$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
+	@echo
+	@echo "Build finished; now you can run HTML Help Workshop with the" \
+	      ".hhp project file in $(BUILDDIR)/htmlhelp."
+
+qthelp:
+	$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
+	@echo
+	@echo "Build finished; now you can run "qcollectiongenerator" with the" \
+	      ".qhcp project file in $(BUILDDIR)/qthelp, like this:"
+	@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/juju.qhcp"
+	@echo "To view the help file:"
+	@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/juju.qhc"
+
+devhelp:
+	$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
+	@echo
+	@echo "Build finished."
+	@echo "To view the help file:"
+	@echo "# mkdir -p $$HOME/.local/share/devhelp/juju"
+	@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/juju"
+	@echo "# devhelp"
+
+epub:
+	$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
+	@echo
+	@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
+
+latex:
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	@echo
+	@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
+	@echo "Run \`make' in that directory to run these through (pdf)latex" \
+	      "(use \`make latexpdf' here to do that automatically)."
+
+latexpdf:
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	@echo "Running LaTeX files through pdflatex..."
+	make -C $(BUILDDIR)/latex all-pdf
+	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
+
+text:
+	$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
+	@echo
+	@echo "Build finished. The text files are in $(BUILDDIR)/text."
+
+man:
+	$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
+	@echo
+	@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
+
+changes:
+	$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
+	@echo
+	@echo "The overview file is in $(BUILDDIR)/changes."
+
+linkcheck:
+	$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
+	@echo
+	@echo "Link check complete; look for any errors in the above output " \
+	      "or in $(BUILDDIR)/linkcheck/output.txt."
+
+doctest:
+	$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
+	@echo "Testing of doctests in the sources finished, look at the " \
+	      "results in $(BUILDDIR)/doctest/output.txt."

=== renamed file 'Makefile' => 'Makefile.moved'
=== added directory 'source'
=== added directory 'source/_static'
=== added directory 'source/_templates'
=== added file 'source/_templates/project-links.html'
--- source/_templates/project-links.html	1970-01-01 00:00:00 +0000
+++ source/_templates/project-links.html	2012-01-18 20:50:30 +0000
@@ -0,0 +1,9 @@
+<h3>Launchpad</h3>
+<ul>
+  <li>
+    <a href="https://launchpad.net/~juju">Overview</a>
+  </li>
+  <li>
+    <a href="https://code.launchpad.net/~juju">Code</a>
+  </li>
+</ul>

=== added file 'source/about.rst'
--- source/about.rst	1970-01-01 00:00:00 +0000
+++ source/about.rst	2012-01-18 20:50:30 +0000
@@ -0,0 +1,38 @@
+About juju
+==========
+
+Since long ago, Linux server deployments have been moving towards the
+collaboration of multiple physical machines. In some cases, different servers
+run each a different set of applications, bringing organization, isolation,
+reserved resources, and other desirable characteristics to the composed
+assembly. In other situations, servers are set up with very similar
+configurations, so that the system becomes more scalable by having load
+distributed among the several instances, and so that the overall system becomes
+more reliable when the failure of any individual machine does not affect the
+assembly as a whole. In this reality, server administrators become invaluable
+maestros which orchestrate the placement and connectivity of services within
+the assembly of servers.
+
+Given that scenario, it's surprising that most of the efforts towards advancing
+the management of software configuration are still bound to individual machines.
+Package managers, and software like dbus and gconf are examples of this. Other
+efforts do look at the problem of managing multiple machines as a unit, but
+interestingly, they are still a mechanism for scaling up the management of
+services individually. In other words, they empower the administrator with the
+ability to tweak the individual configuration of multiple services at once,
+but they do not collaborate towards offering services themselves and other tools
+the understanding of the composed juju. This distinction looks subtle in
+principle, but it may be a key factor in enabling all the parties (system
+administrators, software developers, vendors, and integrators) to collaborate
+in deploying, maintaining, and enriching distributed software configurations.
+
+This is the challenge which motivates the research happening through the
+juju project at Canonical. juju aims to be a service deployment and
+orchestration tool which enables the same kind of collaboration and ease of
+use which today is seen around package management to happen on a higher
+level, around services.  With juju, different authors are able to create
+services independently, and make those services communicate through a simple
+configuration protocol.  Then, users can take the product of both authors
+and very comfortably deploy those services in an environment, in way
+resembling how people are able to install a network of packages with a single
+command via APT.

=== added file 'source/charm-upgrades.rst'
--- source/charm-upgrades.rst	1970-01-01 00:00:00 +0000
+++ source/charm-upgrades.rst	2012-01-18 20:50:30 +0000
@@ -0,0 +1,117 @@
+Charm Upgrades
+================
+
+
+Upgrading a charm
+-------------------
+
+A charm_ can be upgraded via the command line using the following
+syntax::
+
+  $ juju upgrade-charm <service-name>
+
+In the case of a local charm the sytax would be::
+
+  $ juju upgrade-charm --repository=principia <service-name>
+
+This will examine the named service, determine its charm, and check the
+charm's originating repository for a newer version of the charm.
+If a newer charm version is found, it will be uploaded to the juju
+environment, and downloaded to all the running units of the service.
+The unit agent will switch over to executing hooks from the new charm,
+after executing the `upgrade-charm` hook.
+
+.. _charm: ../charm.html
+
+
+Charm upgrade support
+-----------------------
+
+A charm author can add charm specific support for upgrades by
+providing an additional hook that can customize its upgrade behavior.
+
+The hook ``upgrade-charm`` is executed with the new charm version
+in place on the unit. juju guarantees this hook will be the first
+executed hook from the new charm.
+
+The hook is intended to allow the charm to process any upgrade
+concerns it may have with regard to upgrading databases, software, etc
+before its new version of hooks are executed.
+
+After the ``upgrade-charm`` hook is executed, new hooks of the
+charm will be utilized to respond to any system changes.
+
+Futures
+-------
+
+The ``upgrade-charm`` hook will likely need access to a new cli-api
+to access all relations of the unit, in addition to the standard hook
+api commands like ``relation-list``, ``relation-get``,
+``relation-set``, to perform per unit relation upgrades.
+
+The new hook-cli api name is open, but possible suggestions are
+``unit-relations`` or  ``query-relations`` and would list
+all the relations a unit is a member of.
+
+Most `server` services have multiple instances of a named relation.
+Else name iteration of the charm defined relations would suffice.
+It's an open question on how these effectively anonymous instances
+of a named relation would be addressed.
+
+The existing relation-* cli would also need to be extended to take
+a relation parameter, or documented usage of environment variables
+when doing relation iteration during upgrades.
+
+Internals
+---------
+
+The upgrade cli updates the service with its new unit, and sets
+an upgrade flag on each of its units. The unit agent then processes
+the upgrade using the workflow machinery to execute hooks and
+track upgrades across service units.
+
+A unit whose upgrade-charm hook fails will be left running
+but won't process any additional hooks. The hooks will continue
+to be queued for execution.
+
+The upgrade cli command is responsible for
+
+ - Finding the named service.
+
+ - Determining its charm.
+
+ - Determining if a newer version of the charm exists in the
+   origin repository.
+
+ - Uploading the new version of the charm to the environment's machine
+   provider storage.
+
+ - Updating the service state with a reference to the new charm.
+
+ - Marking the associated unit states as needing an upgrade.
+
+As far as determining newer versions, the cli will assume the same charm
+name with the max version number that is greater than the installed to
+be an upgrade.
+
+The unit agent is responsible for
+
+ - Watching the unit state for upgrade changes.
+
+ - Clearing the upgrade setting on the unit state.
+
+ - Downloading the new charm version.
+
+ - Stopping hook execution, hooks will continue to queue while
+   the execution is stopped.
+
+ - Extracting the charm into the unit container.
+
+ - Updating the unit charm reference.
+
+ - Running the upgrade workflow transition which will run the
+   upgrade-charm hook, and restart normal hook execution.
+
+Only the charm directory within a unit container/directory is
+replaced on upgrade, any existing peristent data within the unit
+container is maintained.

=== added file 'source/charm.rst'
--- source/charm.rst	1970-01-01 00:00:00 +0000
+++ source/charm.rst	2012-01-18 20:50:30 +0000
@@ -0,0 +1,379 @@
+Charms
+======
+
+Introduction
+------------
+
+Charms define how services integrate and how their service units
+react to events in the distributed environment, as orchestrated by
+juju.
+
+This specification describes how charms are defined, including their
+metadata and hooks. It also describes the resources available to hooks
+in working with the juju environment.
+
+
+The metadata file
+-----------------
+
+The `metadata.yaml` file, at the root of the charm directory,
+describes the charm. The following fields are supported:
+
+  * **name:** - The charm name itself. Charm names are formed by
+    lowercase letters, digits, and dashes, and must necessarily
+    begin with a letter and have no digits alone in a dashed
+    section.
+
+  * **summary:** - A one-line description of the charm.
+
+  * **description:** - Long explanation of the charm and its
+    features.
+
+  * **provides:** - The deployed service unit must have the given
+    relations established with another service unit whose charm
+    requires them for the service to work properly. See below for how
+    to define a relation.
+
+  * **requires:** - The deployed service unit must have the given
+    relations established with another service unit whose charm
+    provides them for the service to work properly. See below for how
+    to define a relation.
+
+  * **peers:** - Relations that are established with P2P semantics
+    instead of a provides/requires (or client/server) style.  When the
+    charm is deployed as a service unit, all the units from the
+    given service will automatically be made part of the relation.
+    See below for how to define a relation.
+
+
+Relations available in `provides`, `requires`, and `peers` are defined
+as follows:
+
+  * **provides|requires|peers:**
+
+    * **<relation name>:** - This name is a user-provided value which
+      identifies the relation uniquely within the given charm.
+      Examples include "database", "cache", "proxy", and "appserver".
+
+      Each relation may have the following fields defined:
+
+      * **interface:** - This field defines the type of the
+        relation. The relation will only be established with service
+        units that define a compatible relation with the same
+        interface. Examples include "http", "mysql", and
+        "backup-schedule".
+
+      * **limit:** - The maximum number of relations of this kind
+        which may be established to other service units.  Defaults to
+        1 for `requires` relations, and to "none" (no limit) for
+        `provides` and `peers` relations. While you may define it,
+        this field is not yet enforced by juju.
+
+      * **optional:** - Whether this relation is required for the
+        service unit to function or not.  Defaults to `false`, which
+        means the relation is required. While you may define it, this
+        field is not yet enforced by juju.
+
+      As a shortcut, if these properties are not defined, and instead
+      a single string value is provided next to the relation name, the
+      string is taken as the interface value, as seen in this
+      example::
+
+          requires:
+            db: mysql
+
+Some sample charm definitions are provided at the end of this
+specification.
+
+
+Hooks
+-----
+
+juju uses hooks to notify a service unit about changes happening
+in its lifecycle or the larger distributed environment. A hook running
+for a service unit can query this environment, make any desired local
+changes on its underlying machine, and change the relation
+settings.
+
+Each hook for a charm is implemented by placing an executable with
+the desired hook name under the ``hooks/`` directory of the charm
+directory.  juju will execute the hook based on its file name when
+the corresponding event occurs.
+
+All hooks are optional. Not including a corresponding executable in
+the charm is treated by juju as if the hook executed and then
+exited with an exit code of 0.
+
+All hooks are executed in the charm directory on the service unit.
+
+The following hooks are with respect to the lifecycle of a service unit:
+
+  * **install** - Runs just once during the life time of a service
+    unit. Currently this hook is the right place to ensure any package
+    dependencies are met. However, in the future juju will use the
+    charm metadata to perform this role instead.
+
+  * **start** - Runs when the service unit is started. This happens
+    before any relation hooks are called. The purpose of this hook is
+    to get the service unit ready for relations to be established.
+
+  * **stop** - Runs when the service unit is stopped. If relations
+    exist, they will be broken and the respective hooks called before
+    this hook is called.
+
+The following hooks are called on each service unit as the membership
+of an established relation changes:
+
+  * **<relation name>-relation-joined** - Runs upon each time a remote
+    service unit joins the relation.
+
+  * **<relation name>-relation-changed** - Runs upon each time the
+    following events occur:
+
+    1. A remote service unit joins the relation, right after the
+       **<relation name>-relation-joined** hook was called.
+
+    2. A remote service unit changes its relation settings.
+
+    This hook enables the charm to modify the service unit state
+    (configuration, running processes, or anything else) to adapt to
+    the relation settings of remote units.
+
+    An example usage is that HAProxy needs to be aware of web servers
+    as they become available, including details like its IP
+    address. Web server service units can publish their availability
+    by making the appropriate relation settings in the hook that makes
+    the most sense. Assume the HAProxy uses the relation name of
+    ``server``. Then upon that happening, the HAProxy in its
+    ``server-relation-changed hook`` can then change its own
+    configuration as to what is available to be proxied.
+
+  * **<relation name>-relation-departed** - Runs upon each time a
+    remote service unit leaves a relation. This could happen because
+    the service unit has been removed, its service has been destroyed,
+    or the relation between this service and the remote service has
+    been removed.
+
+    An example usage is that HAProxy needs to be aware of web servers
+    when they are no longer available. It can remove each web server
+    its configuration as the corresponding service unit departs the
+    relation.
+
+This relation hook is with respect to the relation itself:
+
+  * **<relation name>-relation-broken** - Runs when a relation which
+    had at least one other relation hook run for it (successfully or
+    not) is now unavailable. The service unit can then clean up any
+    established state.
+
+    An example might be cleaning up the configuration changes which
+    were performed when HAProxy was asked to load-balance for another
+    service unit.
+
+Note that the coupling between charms is defined by which settings
+are required and made available to them through the relation hooks and
+how these settings are used. Those conventions then define what the
+relation interface really is, and the **interface** name in the
+`metadata.yaml` file is simply a way to refer to them and avoid the
+attempting of incompatible conversations.  Keep that in mind when
+designing your charms and relations, since it is a good idea to
+allow the implementation of the charm to change and be replaced with
+alternative versions without changing the relation conventions in a
+backwards incompatible way.
+
+
+Hook environment
+----------------
+
+Hooks can expect to be invoked with a standard environment and
+context. The following environment variables are set:
+
+  * **$JUJU_UNIT_NAME** - The name of the local unit executing,
+    in the form ``<service name>/<unit sequence>``. E.g. ``myblog/3``.
+
+Hooks called for relation changes will have the follow additional
+environment variables set:
+
+  * **$JUJU_RELATION** - The relation name this hook is running
+    for.  It's redundant with the hook name, but is necessary for
+    the command line tools to know the current context.
+
+  * **$JUJU_REMOTE_UNIT** - The unit name of the remote unit
+    which has triggered the hook execution.
+
+
+Hook commands for working with relations
+----------------------------------------
+
+In implementing their functionality, hooks can leverage a set of
+command tools provided by juju for working with relations.  These
+utilities enable the hook to collaborate on their relation settings,
+and to inquire about the peers the service unit has relations with.
+
+The following command line tools are made available:
+
+  * **relation-get** - Queries a setting from an established relation
+    with one or more service units.  This command will read some
+    context information from environment variables (e.g.
+    $JUJU_RELATION_NAME).
+
+    Examples:
+
+    Get the IP address from the remote unit which triggered the hook
+    execution::
+
+        relation-get ip
+
+    Get all the settings from the remote unit which triggered the hook
+    execution::
+
+        relation-get
+
+    Get the port information from the `wordpress/3` unit::
+
+        relation-get port wordpress/3
+
+    Get all the settings from the `wordpress/3` unit, in JSON format::
+
+        relation-get - wordpress/3
+
+  * **relation-set** - Changes a setting in an established relation.
+
+    Examples:
+
+    Set this unit's port number for other peers to use::
+
+        relation-set port=8080
+
+    Change two settings at once::
+
+        relation-set dbname=wordpress dbpass="super secur3"
+
+    Change several settings at once, with a JSON file::
+
+        cat settings.json | relation-set
+
+    Delete a setting::
+
+        relation-set name=
+
+  * **relation-list** - List all service units participating in the
+    established relation.  This list excludes the local service unit
+    which is executing the command. For `provides` and `requires`
+    relations, this command will always return a single service unit.
+
+    Example::
+
+        MEMBERS=$(relation-list)
+
+Changes to relation settings are only committed if the hook exited
+with an exit code of 0. Such changes will then trigger further hook
+execution in the remote unit(s), through the **<relation
+name>-relation-changed** hook. This mechanism enables a general
+communication mechanism for service units to coordinate.
+
+
+Hook commands for opening and closing ports
+-------------------------------------------
+
+Service exposing determines which ports to expose by using the
+``open-port`` and ``close-port`` commands in hooks. They may be
+executed within any charm hook. The commands take the same
+arguments::
+
+    open-port port[/protocol]
+
+    close-port port[/protocol]
+
+These commands are executed immediately; they do not depend on the
+exit status of the hook.
+
+As an example, consider the WordPress charm, which has been deployed
+as ``my-wordpress``. After completing the setup and restart of Apache,
+the ``wordpress`` charm can then publish the available port in its
+``start`` hook for a given service unit::
+
+    open-port 80
+
+External access to the service unit is only allowed when both
+``open-port`` is executed within any hook and the administrator has
+exposed its service.  The order in which these happen is not
+important, however.
+
+.. note::
+
+    Being able to use any hook may be important for your charm.
+    Ideally, the service does not have ports that are vulnerable if
+    exposed prior to the service being fully ready. But if that's the
+    case, you can solve this problem by only opening the port in the
+    appropriate hook and when the desired conditions are met.
+
+Alternatively, you may need to expose more than one port, or expose
+ports that don't use the TCP protocol. To expose ports for
+HTTP and HTTPS, your charm could instead make these settings::
+
+    open-port 80
+    open-port 443
+
+Or if you are writing a charm for a DNS server that you would like
+to expose, then specify the protocol to be UDP::
+
+    open-port 53/udp
+
+When the service unit is removed or stopped for any reason, the
+firewall will again be changed to block traffic which was previously
+allowed to reach the exposed service. Your charm can also do this to
+close the port::
+
+    close-port 80
+
+To be precise, the firewall is only open for the exposed ports during
+the time both these conditions hold:
+
+    * A service has been exposed.
+    * A corresponding ``open-port`` command has been run (without a
+      subsequent ``close-port``).
+
+
+Sample metadata.yaml files
+--------------------------
+
+Below are presented some sample metadata files.
+
+
+MySQL::
+
+  name: mysql
+  revision: 1
+  summary: "A pretty popular database"
+
+  provides:
+    db: mysql
+
+
+Wordpress::
+
+  name: wordpress
+  revision: 3
+  summary: "A pretty popular blog engine"
+  provides:
+    url:
+      interface: http
+
+  requires:
+    db:
+     interface: mysql
+
+
+Riak::
+
+  name: riak
+  revision: 7
+  summary: "Scalable K/V Store in Erlang with Clocks :-)"
+  provides:
+    endpoint:
+      interface: http
+
+  peers:
+    ring:
+      interface: riak

=== added file 'source/conf.py'
--- source/conf.py	1970-01-01 00:00:00 +0000
+++ source/conf.py	2012-01-18 20:50:30 +0000
@@ -0,0 +1,225 @@
+# -*- coding: utf-8 -*-
+#
+# juju documentation build configuration file, created by
+# sphinx-quickstart on Wed Jul 14 09:40:34 2010.
+#
+# This file is execfile()d with the current directory set to its containing dir.
+#
+# Note that not all possible configuration values are present in this
+# autogenerated file.
+#
+# All configuration values have a default; values that are commented out
+# serve to show the default.
+
+import sys, os
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+sys.path.insert(0, os.path.abspath('../..'))
+
+# -- General configuration -----------------------------------------------------
+
+# If your documentation needs a minimal Sphinx version, state it here.
+#needs_sphinx = '1.0'
+
+# Add any Sphinx extension module names here, as strings. They can be extensions
+# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
+import sphinx
+
+extensions = ['sphinx.ext.autodoc']
+
+if [int(x) for x in sphinx.__version__.split(".")] > [1, 0]:
+    if "singlehtml" not in sys.argv:
+        # singlehtml builder skips the step that would cause the _modules
+        # directory to be created, so source links don't work
+        extensions.append('sphinx.ext.viewcode')
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# The suffix of source filenames.
+source_suffix = '.rst'
+
+# The encoding of source files.
+#source_encoding = 'utf-8-sig'
+
+# The master toctree document.
+master_doc = 'index'
+
+# General information about the project.
+project = u'juju'
+copyright = u'2010, Canonical'
+
+# The version info for the project you're documenting, acts as replacement for
+# |version| and |release|, also used in various other places throughout the
+# built documents.
+#
+# The short X.Y version.
+version = '1.0'
+# The full version, including alpha/beta/rc tags.
+release = '1.0dev'
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#language = None
+
+# There are two options for replacing |today|: either, you set today to some
+# non-false value, then it is used:
+#today = ''
+# Else, today_fmt is used as the format for a strftime call.
+#today_fmt = '%B %d, %Y'
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+exclude_patterns = []
+
+# The reST default role (used for this markup: `text`) to use for all documents.
+#default_role = None
+
+# If true, '()' will be appended to :func: etc. cross-reference text.
+#add_function_parentheses = True
+
+# If true, the current module name will be prepended to all description
+# unit titles (such as .. function::).
+#add_module_names = True
+
+# If true, sectionauthor and moduleauthor directives will be shown in the
+# output. They are ignored by default.
+#show_authors = False
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
+# A list of ignored prefixes for module index sorting.
+#modindex_common_prefix = []
+
+
+# -- Options for HTML output ---------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+html_theme = 'default'
+
+# Theme options are theme-specific and customize the look and feel of a theme
+# further.  For a list of options available for each theme, see the
+# documentation.
+#html_theme_options = {}
+
+# Add any paths that contain custom themes here, relative to this directory.
+#html_theme_path = []
+
+# The name for this set of Sphinx documents.  If None, it defaults to
+# "<project> v<release> documentation".
+#html_title = None
+
+# A shorter title for the navigation bar.  Default is the same as html_title.
+#html_short_title = None
+
+# The name of an image file (relative to this directory) to place at the top
+# of the sidebar.
+#html_logo = None
+
+# The name of an image file (within the static path) to use as favicon of the
+# docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
+# pixels large.
+#html_favicon = None
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+#html_static_path = ['_static']
+
+# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
+# using the given strftime format.
+#html_last_updated_fmt = '%b %d, %Y'
+
+# If true, SmartyPants will be used to convert quotes and dashes to
+# typographically correct entities.
+#html_use_smartypants = True
+
+# Custom sidebar templates, maps document names to template names.
+html_sidebars = {
+   'index': 'project-links.html'
+}
+# Additional templates that should be rendered to pages, maps page names to
+# template names.
+#html_additional_pages = {}
+
+# If false, no module index is generated.
+html_domain_indices = False
+
+# If false, no index is generated.
+#html_use_index = True
+
+# If true, the index is split into individual pages for each letter.
+#html_split_index = False
+
+# If true, links to the reST sources are added to the pages.
+#html_show_sourcelink = True
+
+# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
+#html_show_sphinx = True
+
+# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
+#html_show_copyright = True
+
+# If true, an OpenSearch description file will be output, and all pages will
+# contain a <link> tag referring to it.  The value of this option must be the
+# base URL from which the finished HTML is served.
+#html_use_opensearch = ''
+
+# If nonempty, this is the file name suffix for HTML files (e.g. ".xhtml").
+#html_file_suffix = ''
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'jujudoc'
+
+
+# -- Options for LaTeX output --------------------------------------------------
+
+# The paper size ('letter' or 'a4').
+#latex_paper_size = 'letter'
+
+# The font size ('10pt', '11pt' or '12pt').
+#latex_font_size = '10pt'
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title, author, documentclass [howto/manual]).
+latex_documents = [
+  ('index', 'juju.tex', u'juju documentation',
+   u'Canonical', 'manual'),
+]
+
+# The name of an image file (relative to this directory) to place at the top of
+# the title page.
+#latex_logo = None
+
+# For "manual" documents, if this is true, then toplevel headings are parts,
+# not chapters.
+#latex_use_parts = False
+
+# If true, show page references after internal links.
+#latex_show_pagerefs = False
+
+# If true, show URL addresses after external links.
+#latex_show_urls = False
+
+# Additional stuff for the LaTeX preamble.
+#latex_preamble = ''
+
+# Documents to append as an appendix to all manuals.
+#latex_appendices = []
+
+# If false, no module index is generated.
+#latex_domain_indices = True
+
+
+# -- Options for manual page output --------------------------------------------
+
+# One entry per manual page. List of tuples
+# (source start file, name, description, authors, manual section).
+man_pages = [
+    ('index', 'juju', u'juju documentation',
+     [u'Canonical'], 1)
+]

=== added directory 'source/drafts'
=== added file 'source/drafts/charm-namespaces.rst'
--- source/drafts/charm-namespaces.rst	1970-01-01 00:00:00 +0000
+++ source/drafts/charm-namespaces.rst	2012-01-18 20:50:30 +0000
@@ -0,0 +1,72 @@
+
+Charm Namespaces
+================
+
+Introduction
+------------
+  
+juju supports deployment of charms from multiple sources.
+
+By default juju searches only the Ubuntu charm namespace to resolve
+charms. For example the following command line snippet will install wordpress
+from the ubuntu charm namespace.::  
+
+  juju deploy wordpress
+
+
+In order to support local charm development and completely offline private
+repositories, charms can also be deployed directly from a local directory.
+For example the following will resolve the wordpress charm to the
+$HOME/local_charms directory.::  
+
+  juju deploy --repository=~/local_charms wordpress
+
+With this parameter any charm dependencies from the wordpress charm will be
+looked up first in the local directory and then in the ubuntu charm
+namespace. So the command line flag '--repository' alters the charm lookup
+from the default such that it prepends the local directory to the lookup order.
+
+
+The lookup order can also be altered to utilize a 3rd party published repository
+in preference to the Ubuntu charm repository. For example the following will
+perform a charm lookup for wordpress and its dependencies from the published
+'openstack' 3rd party repository before looking up dependencies in the Ubuntu
+charm repository.:: 
+
+  juju deploy --repository=es:openstack wordpress
+
+The lookup order can also be specified just for a single charm. For example
+the following command would deploy the wordpress charm from the openstack
+namespace but would resolve dependencies (like apache and mysql) via the ubuntu
+namespace.::  
+
+  juju deploy es:openstack/wordpress
+
+The lookup order can also be explicitly specified in the client configuration
+to define a custom lookup order without the use of command line options.:: 
+
+  environments.yaml
+
+   repositories:
+   
+      - http://charms.ubuntu.com/collection/ubuntu
+      - http://charms.ubuntu.com/collection/openstack
+      - http://charms.ubuntu.com/people/miked
+      - /var/lib/charms
+      
+The repositories in the configuration file are specified as a yaml list, and the
+list order defines the lookup order for charms.
+ 
+
+Deployment
+----------
+
+After juju resolves a charm and its dependencies, it bundles them and
+deploys them to a machine provider charm cache/repository. This allows the
+same charm to be deployed to multiple machines repeatably and with minimal
+network transfers.
+
+juju stores the qualified name of the charm when saving it to the machine
+provider cache. This allows a charm to be unambigiously identified, ie.
+whether it came from the ubuntu namespace or a 3rdparty namespace, or even from
+disk.

=== added file 'source/drafts/developer-install.rst'
--- source/drafts/developer-install.rst	1970-01-01 00:00:00 +0000
+++ source/drafts/developer-install.rst	2012-01-18 20:50:30 +0000
@@ -0,0 +1,49 @@
+Developer Install
+------------------
+
+For folks who want to develop on juju itself, a source install
+from trunk or branch is recommended.
+
+To run juju from source, you will need the following dependencies
+installed:
+
+ * zookeeper
+ * txzookeeper
+ * txaws
+
+The juju team recommends install the zookeeper package from the
+juju PPA, or a source compilation as of ubuntu natty (11.04) due
+to bugs in the packaged version.
+
+On a modern Ubuntu Linux system execute::
+
+ $ sudo apt-get install python-zookeeper python-virtualenv python-yaml
+
+You will also need Python 2.6 or better.
+
+We recommend and demonstrate the use of virtualenv to install juju
+and its dependencies in a sandbox, in case you latter install a newer
+version via package.
+
+First let's setup a virtualenv::
+
+  $ virtualenv juju
+  $ cd juju
+  $ source bin/activate
+
+Next we'll fetch and install a few juju dependencies from source::
+
+  $ bzr branch lp:txaws
+  $ cd txaws && python setup.py develop && cd..
+  $ bzr branch lp:txzookeeper
+  $ cd txzookeeper && python setup.py develop && cd..
+
+Lastly, we fetch juju and install it from trunk::
+
+  $ bzr branch lp:juju
+  $ cd juju && python setup.py develop
+
+You can now configure your juju environment per the getting-started
+documentation.
+
+

=== added file 'source/drafts/expose-services.rst'
--- source/drafts/expose-services.rst	1970-01-01 00:00:00 +0000
+++ source/drafts/expose-services.rst	2012-01-18 20:50:30 +0000
@@ -0,0 +1,20 @@
+Exposing a service
+==================
+
+The following functionality will be implemented at a later date.
+
+
+``exposed`` and ``unexposed`` hooks
+-----------------------------------
+
+Upon a service being exposed, the ``exposed`` hook will be run, if it
+is present in the charm.
+
+This may be an appropriate place to run the ``open-port`` command,
+however, it is up to the charm author where it should be run, since
+it and ``close-port`` are available commands for every hook.
+
+Likewise, when a service is unexposed, the ``unexposed`` hook will be
+run, if present. Many charms likely do not need to implement this
+hook, however, it could be an opportunity to terminate unnecessary
+processes or remove other resources.

=== added file 'source/drafts/resolved.rst'
--- source/drafts/resolved.rst	1970-01-01 00:00:00 +0000
+++ source/drafts/resolved.rst	2012-01-18 20:50:30 +0000
@@ -0,0 +1,60 @@
+Resolving errors
+================
+
+juju internally tracks the state of units and their relations.
+It moves them through a simple state machine to ensure the correct
+sequencing of hooks and associated unit agent behavior. Typically
+this means that all hooks are executed as part of a workflow transition.
+
+If a hook fails, then juju notes this failure, and transitions
+either the unit or the unit relation (depending on the hook) to a
+failure state.
+
+If a hook for a unit relation fails, only that unit relation is
+considered to be in an error state, the unit and other relations of
+the unit continue to operate normally.
+
+If a hook for the unit fails (install, start, stop, etc), the unit
+is considered not running, and its unit relations will stop responding
+to changes.
+
+As a means to recover from hook errors, juju offers the
+``juju resolved`` command.
+
+This command will operate on either a unit or unit relation and
+schedules a transition from the error state back to its original
+destination state. For example given a unit mysql/0 whose start
+hook had failed, and the following command line::
+
+  $ juju resolved mysql/0
+
+After being resolved the unit would be in the started state. It
+important to note that by default ``juju resolved`` does
+not fire hooks and the ``start`` hook would not be invoked again
+as a result of the above.
+
+If a unit's relation-change/joined/departed hook had failed, then
+juju resolved can also be utilized to resolve the error on
+the unit relation::
+
+  $ juju resolved mysql/0 db
+
+This would re-enable change watching, and hook execution for the
+``db`` relation after a hook failure.
+
+It's expected that an admin will typically have a look at the system to
+determine or correct the issue before using this command line.
+``juju resolved`` is meant primarily as a mechanism to remove the
+error block after correction of the original issue.
+
+However ``juju resolved`` can optionally re-invoke the failed hook.
+This feature is particular beneficial during charm development, when
+iterating over an in development hook. Assuming a mysql unit with
+with a start hook error upon executing the following command::
+
+ $ juju resolved --retry mysql/0
+
+juju will examine the mysql/0 unit, and will re-execute its start
+hook before marking it as running. If the start hook fails again,
+then the unit will remain in the same state.
+

=== added file 'source/drafts/service-config.rst'
--- source/drafts/service-config.rst	1970-01-01 00:00:00 +0000
+++ source/drafts/service-config.rst	2012-01-18 20:50:30 +0000
@@ -0,0 +1,162 @@
+.. _"Service Configuration":
+
+Service configuration
+=====================
+
+Introduction
+------------
+
+A Charm_ often will require access to specific options or
+configuration. Charms allow for the manipulation of the various
+configuration options which the charm author has chosen to
+expose. juju provides tools to help manage these options and
+respond to changes in these options over the lifetime of the `service`
+deployment. These options apply to the entire service, as opposed to
+only a specific unit or relation. Configuration is modified by an
+administrator at deployment time or over the lifetime of the services.
+
+As an example a wordpress service may expose a 'blog-title'
+option. This option would control the title of the blog being
+published.  Changes to this option would be applied to all units
+implementing this service through the invocation of a hook on each of
+them.
+
+.. _Charm: ./charm.html
+
+
+Using configuration options
+---------------------------
+
+Configuration options are manipulated using a command line
+interface. juju provide a `set` command to aid the administrator
+in changing values.
+
+::
+  juju set <service name> option=value [option=value]
+
+This command allows changing options at runtime and takes one or more
+name/value pairs which will be set into the service
+options. Configuration options which are set together are delivered to
+the services for handling together.  E.g. if you are changing a
+username and a password, changing them individually may yield bad
+results since the username will temporarily be set with an incorrect
+password.
+
+While its possible to set multiple configuration options on the
+command line its also convenient to pass multiple configuration
+options via the --file argument which takes the name of a YAML
+file. The contents of this file will be applied as though these
+elements had been passed to `juju set`.
+
+A configuration file may be provided at deployment time using the
+--config option, as follows::
+
+      juju deploy [--config local.yaml] wordpress myblog
+
+The service name is looked up inside the YAML file to allow for
+related service configuration options to be collected into a single
+file for the purposes of deployment and passed repeated to each
+`juju deploy` invocation.
+
+Below is an example local.yaml containing options
+which would be used during deployment of a service named myblog.
+
+::
+
+  myblog:
+     blog-roll: ['http://foobar.com', 'http://testing.com']
+     blog-title: Awesome Sauce
+     password: n0nsense
+
+
+Creating charms
+---------------
+
+Charm authors create a `config.yaml` file which resides in the
+charm's top-level directory. The configuration options supported by
+a service are defined within its respective charm. juju will
+only allow the manipulation of options which were explicitly defined
+as supported.
+
+The specification of possible configuration values is intentionally
+minimal, but still evolving.  Currently the charm define a list of
+names which they react. Information includes a human readable
+description and an optional default value. Additionally `type` may be
+specified. All options have a default type of 'str' which means its
+value will only be treated as a text string. Other valid options are
+'int', 'float' and 'regex'. When 'regex' is used an addtional element
+must be provided, 'validator'. This must be a valid Python regex as
+specified at http://docs.python.org/lib/re.html
+
+The following `config.yaml` would be included in the top level
+directory of a charm and includes a list of option definitions::
+
+    options:
+        blog-roll:
+            default: null
+            description: List of URLs which will be included as the blog roll
+        blog-title:
+            default: My Blog
+            description: The title of the blog.
+        password:
+            default: changeme
+            description: Password to be used for the account specified by 'username'
+            type: regex
+            validator: '.{6,12}'
+        username:
+            default: admin
+            description: The name of the initial account (given admin permissions).
+
+
+To access these configuration options from a hook we provide the following::
+
+    config-get [option name]
+
+`config-get` returns all the configuration options for a service as
+JSON data when no option name is specified. If an option name is
+specified the value of that option is output according to the normal
+rules and obeying the `--output` and `--format` arguments. Hooks
+implicitly know the service they are executing for and config-get
+always gets values from the service of the hook.
+
+Changes to options (see previous section) trigger the charm's
+`config-changed` hook. The `config-changed` hook is guaranteed to run
+after any changes are made to the configuration, but it is possible
+that multiple changes will be observed at once. Because its possible
+to set many configuration options on a single command line invocation
+it is easily possible to ensure related options are available to the
+service at the same time.
+
+The `config-changed` hook must be written in such a way as to deal
+with changes to one or more options and deal gracefully with options
+that are required by the charm but not yet set by an
+administrator. Errors in the config-changed hook force juju to
+assume the service is no longer properly configured. If the service is
+not already in a stopped state it will be stopped and taken out of
+service. The status command will be extended in the future to report
+on workflow and unit agent status which will help reveal error
+conditions of this nature.
+
+When options are passed using `juju deploy` their values will be
+read in from a file and made available to the service prior to the
+invocation of the its `install` hook. The `install` and `start` hooks
+will have access to config-get and thus complete access to the
+configuration options during their execution. If the `install` or
+`start` hooks don't directly need to deal with options they can simply
+invoke the `config-changed` hook.
+
+
+
+Internals
+---------
+
+.. note::
+     This section explains details useful to the implementation but not of
+     interest to the casual reader.
+
+Hooks normally attempt to provide a consistent view of the shared
+state of the system and the handling of config options within hooks
+(config-changed and the relation hooks) is no different. The first
+access to the configuration data of a service will retain a cached
+copy of the service options. Cached data will be used for the
+duration of the hook invocation.

=== added file 'source/expose-services.rst'
--- source/expose-services.rst	1970-01-01 00:00:00 +0000
+++ source/expose-services.rst	2012-01-18 20:50:30 +0000
@@ -0,0 +1,43 @@
+Exposing a service
+==================
+
+In juju, making a service public -- its ports available for public
+use -- requires that it be explicitly *exposed*. Note that this
+exposing does not yet involve DNS or other directory information. For
+now, it simply makes the service public.
+
+Service exposing works by opening appropriate ports in the firewall of
+the cloud provider. Because service exposing is necessarily tied to
+the underlying provider, juju manages all aspects of
+exposing. Such management ensures that a charm can work with other
+cloud providers besides EC2, once support for them is implemented.
+
+juju provides the ``juju expose`` command to expose a service.
+For example, you might have deployed a ``my-wordpress`` service, which
+is defined by a ``wordpress`` charm. To expose this service, simply
+execute the following command::
+
+    juju expose my-wordpress
+
+To stop exposing this service, and make any corresponding firewall
+changes immediately, you can run this command::
+
+    juju unexpose my-wordpress
+
+You can see the status of your exposed ports by running the ``juju
+status`` command. If ports have been opened by the service and you
+have exposed the service, then you will see something like the
+following output for the deployed services::
+
+  services:
+    wordpress:
+      exposed: true
+      charm: local:oneiric/wordpress-42
+      relations: {db: mysql}
+      units:
+        wordpress/0:
+          machine: 2
+          open-ports: [80/tcp]
+	  relations:
+            db: {state: up}
+          state: started

=== added file 'source/faq.rst'
--- source/faq.rst	1970-01-01 00:00:00 +0000
+++ source/faq.rst	2012-01-18 20:50:30 +0000
@@ -0,0 +1,91 @@
+Frequently Asked Questions
+==========================
+
+Where does the name juju come from?
+
+  It means magic in the same african roots where the word ubuntu comes from.
+  Please see http://afgen.com/juju.html for a more detailed explanation.
+
+Why is juju useful?
+
+  juju is a next generation service deployment and orchestration
+  framework.  It has been likened to APT for the cloud. With juju,
+  different authors are able to create service charms independently, and
+  make those services coordinate their communication through a simple
+  protocol.  Users can then take the product of different authors and very
+  comfortably deploy those services in an environment.  The result is
+  multiple machines and components transparently collaborating towards
+  providing the requested service.  Read more :doc:`about`
+
+When will it be ready for production?
+
+  As of Ubuntu Natty 11.04, juju is a technology preview. It is not yet
+  ready to be used in production. However, adventurous users are encouraged to
+  evaluate it, study it, start writing charms for it or start hacking on
+  juju internals. The rough roadmap is to have juju packaged for
+  Universe by 11.10 release and perhaps in main by 12.04
+
+What language is juju developed in?
+
+  juju itself is developed using Python. However, writing charms for
+  juju can be done in any language. All juju cares about is finding a
+  set of executable files, which it will trigger appropriately
+
+Does juju start from a pre-configured AMI Image?
+
+  No, juju uses a plain Ubuntu image. All needed components are installed
+  at run-time. Then the juju charm is sent to the machine and hooks start
+  getting executed in response to events
+
+Is it possible to deploy multiple services per machine?
+
+  Currently each service unit is deployed to a separate machine (ec2 instance)
+  that can relate to other services running on different nodes. This was done
+  to get juju into a working state faster. juju will definitely support
+  multiple services per machine in the future
+
+Is it possible to pass parameters to juju charms?
+
+  Tunables are landing very soon in juju. Once ready you will be able to
+  use "juju set service key=value" and respond to that from within the
+  juju charm. This will enable dynamic features to be added to charms
+
+Does juju only deploy to the Amazon EC2 cloud?
+
+  Currently yes. However work is underway to enable deploying to LXC containers
+  such that you are able to run juju charms on a single local machine
+  Also integration work with the `Orchestra <https://launchpad.net/orchestra>`_
+  project is underway to enable deployment to hardware machines
+
+What directory are hooks executed in?
+
+  Hooks are executed in the charm directory (the parent directory to the hook
+  directory). This is primarily to encourage putting additional resources that
+  a hook may use outside of the hooks directory which is the public interface
+  of the charm.
+
+How are charms licensed?
+
+  Charms are effectively data inputs to juju, and are therefore
+  licensed/copyrighted by the author as an independent work. You are free to
+  claim copyright solely for yourself if it's an independent work, and to
+  license it as you see fit. If you as the charm author are performing the
+  work as a result of a fiduciary agreement, the terms of such agreement come
+  into play and so the licensing choice is up to the hiring entity.
+
+How can I contact the juju team?
+
+  User and charm author oriented resources
+   * Mailing list: https://lists.ubuntu.com/mailman/listinfo/Ubuntu-cloud
+   * IRC #ubuntu-cloud
+  juju development
+   * Mailing list: https://lists.ubuntu.com/mailman/listinfo/juju
+   * IRC #juju (Freenode)
+
+Where can I find out more about juju?
+
+  * Project Site: https://launchpad.net/juju
+  * Documentation: https://juju.ubuntu.com/docs/
+  * Work Items: https://juju.ubuntu.com/kanban/dublin.html
+  * Principia charms project: https://launchpad.net/principia
+  * Principia-Tools project: https://launchpad.net/principia-tools

=== added file 'source/generate_modules.py'
--- source/generate_modules.py	1970-01-01 00:00:00 +0000
+++ source/generate_modules.py	2012-01-18 20:50:30 +0000
@@ -0,0 +1,107 @@
+import os
+import sys
+
+INIT = "__init__.py"
+TESTS = "tests"
+
+
+def get_modules(names):
+    if INIT in names:
+        names.remove(INIT)
+    return [n[:-3] for n in names if n.endswith(".py")]
+
+
+def trim_dirs(root, dirs):
+    for dir_ in dirs[:]:
+        if dir_ == TESTS:
+            dirs.remove(TESTS)
+        if not os.path.exists(os.path.join(root, dir_, INIT)):
+            dirs.remove(dir_)
+    return dirs
+
+
+def module_name(base, root, name=None):
+    path = root[len(base) + 1:]
+    if name:
+        path = os.path.join(path, name)
+    return path.replace("/", ".")
+
+
+def collect_modules(src):
+    src = os.path.abspath(src)
+    base = os.path.dirname(src)
+
+    names = []
+    for root, dirs, files in os.walk(src):
+        modules = get_modules(files)
+        packages = trim_dirs(root, dirs)
+        if modules or packages:
+            names.append(module_name(base, root))
+            for name in modules:
+                names.append(module_name(base, root, name))
+    return sorted(names)
+
+
+def subpackages(names, parent):
+    return [name for name in names
+            if name.startswith(parent) and name != parent]
+
+
+def dst_file(dst, name):
+    return open(os.path.join(dst, "%s.rst" % name), "w")
+
+
+def write_title(f, name, kind):
+    f.write("%s\n%s\n\n" % (name, kind * len(name)))
+
+
+def write_packages(f, names):
+    for name in names:
+        f.write("    " * name.count("."))
+        f.write("* :mod:`%s`\n" % name)
+    f.write("\n")
+
+
+def abbreviate(name):
+    parts = name.split(".")
+    short_parts = [part[0] for part in parts[:-2]]
+    return ".".join(short_parts + parts[-2:])
+
+
+def write_module(f, name, subs):
+    write_title(f, abbreviate(name), "=")
+    f.write(".. automodule:: %s\n"
+            "    :members:\n"
+            "    :undoc-members:\n"
+            "    :show-inheritance:\n\n"
+            % name)
+    if subs:
+        write_title(f, "Subpackages", "-")
+        write_packages(f, subs)
+
+
+def write_module_list(f, names):
+    write_title(f, "juju modules", "=")
+    write_packages(f, names)
+    f.write(".. toctree::\n    :hidden:\n\n")
+    for name in names:
+        f.write("    %s\n" % name)
+
+
+def generate(src, dst):
+    names = collect_modules(src)
+
+    if not os.path.exists(dst):
+        os.makedirs(dst)
+
+    with dst_file(dst, "modules") as f:
+        write_module_list(f, names)
+
+    for name in names:
+        with dst_file(dst, name) as f:
+            write_module(f, name, subpackages(names, name))
+
+
+if __name__ == "__main__":
+    src, dst = sys.argv[1:]
+    generate(src, dst)

=== added file 'source/getting-started.rst'
--- source/getting-started.rst	1970-01-01 00:00:00 +0000
+++ source/getting-started.rst	2012-01-18 20:50:30 +0000
@@ -0,0 +1,80 @@
+.. _getting-started:
+
+Getting started
+===============
+
+Introduction
+------------
+
+This tutorial gets you started with juju. A prerequisite is the
+access credentials to a dedicated computing environment such as what
+is offered by a virtualized cloud hosting environment.
+
+juju has been designed for environments which can provide a
+new machine with an Ubuntu cloud operating system image
+on-demand. This includes services such as `Amazon EC2
+<http://aws.amazon.com/ec2/>`_ or `RackSpace
+<http://www.rackspace.com>`_.
+
+It's also required that the environment provides a permanent storage
+facility such as `Amazon S3 <https://s3.amazonaws.com/>`_.
+
+For the moment, though, the only environment supported is EC2.
+
+Running from PPA
+----------------
+
+The juju team's Personal Package Archive (PPA) installation is
+currently the preferred installation mechanism for juju. It
+includes newer upstream versions of binary dependencies like Zookeeper
+which are more recent than the latest ubuntu release (natty 11.04) and
+contain important bugfixes.
+
+To install juju from the PPA, execute the following in a shell::
+
+  sudo add-apt-repository ppa:juju/pkgs
+  sudo apt-get update && sudo apt-get install juju
+
+The juju environment can now be configured per the following.
+
+Configuring your environment
+----------------------------
+
+Run the command-line utility with no arguments to create a sample
+environment::
+
+  $ juju
+
+This will create the file ``~/.juju/environments.yaml``, which will look
+something like this::
+
+  environments:
+    sample:
+      type: ec2
+      control-bucket: juju-faefb490d69a41f0a3616a4808e0766b
+      admin-secret: 81a1e7429e6847c4941fda7591246594
+
+Which is a sample environment configured to run with EC2 machines and S3
+permanent storage.  To make this environment actually useful, you will need
+to tell juju about an AWS access key and secret key.  To do this, you
+can either set the ``AWS_ACCESS_KEY_ID`` and ``AWS_SECRET_ACCESS_KEY``
+environment variables (as usual for other EC2 tools) or you can add
+``access-key`` and ``secret-key`` options to your ``environments.yaml``.
+For example::
+
+  environments:
+    sample:
+      type: ec2
+      access-key: YOUR-ACCESS-KEY-GOES-HERE
+      secret-key: YOUR-SECRET-KEY-GOES-HERE
+      control-bucket: juju-faefb490d69a41f0a3616a4808e0766b
+      admin-secret: 81a1e7429e6847c4941fda7591246594
+
+The S3 bucket does not need to exist already.
+
+.. note::
+        If you already have an AWS account, you can determine your access key by
+        visiting http://aws.amazon.com/account, clicking "Security Credentials" and
+        then clicking "Access Credentials".  You'll be taken to a table that lists
+        your access keys and has a "show" link for each access key that will reveal
+        the associated secret key.

=== added file 'source/glossary.rst'
--- source/glossary.rst	1970-01-01 00:00:00 +0000
+++ source/glossary.rst	2012-01-18 20:50:30 +0000
@@ -0,0 +1,121 @@
+.. _glossary:
+
+Glossary
+========
+
+.. glossary::
+
+   Bootstrap
+        To boostrap an environment means initializing it so that Services may be
+        deployed on it.
+
+   Endpoint
+        The combination of a service name and a relation name.
+
+   juju
+        The whole software here documented.
+
+   Environment
+        An Environment is a configured location where Services
+        can be deployed onto.  An Environment typically has a name,
+        which can usually be omitted when there's a single Environment
+        configured, or when a default is explicitly defined.
+        Depending on the type of Environment, it may have to be
+        bootstrapped before interactions with it may take place
+        (e.g. EC2).  The local environment configuration is defined in
+        the ~/.juju/environments.yaml file.
+
+   Charm
+        A Charm provides the definition of the service, including its metadata,
+        dependencies to other services, packages necessary, as well as the logic
+        for management of the application. It is the layer that integrates an
+        external application component like Postgres or WordPress into juju.
+        An juju Service may generally be seen as the composition of its juju
+        Charm and the upstream application (traditionally made available through
+        its package).
+
+   Charm URL
+        A Charm URL is a resource locator for a charm, with the following format
+        and restrictions::
+
+            <schema>:[~<user>/]<collection>/<name>[-<revision>]
+
+        `schema` must be either "cs", for a charm from the Juju charm store, or
+        "local", for a charm from a local repository.
+
+        `user` is only valid in charm store URLs, and allows you to source
+        charms from individual users (rather than from the main charm store);
+        it must be a valid Launchpad user name.
+
+        `collection` denotes a charm's purpose and status, and is derived from
+        the Ubuntu series targeted by its contained charms: examples include
+        "natty", "oneiric", "oneiric-universe".
+
+        `name` is just the name of the charm; it must start and end with
+        lowercase (ascii) letters, and can otherwise contain any combination of
+        lowercase letters, digits, and "-"s.
+
+        `revision`, if specified, points to a specific revision of the charm
+        pointed to by the rest of the URL. It must be a non-negative integer.
+
+   Repository
+        A location where multiple charms are stored. Repositories may be as simple
+        as a directory structure on a local disk, or as complex as a rich smart
+        server supporting remote searching and so on.
+
+   Relation
+        Relations are the way in which juju enables Services to communicate
+        to each other, and the way in which the topology of Services is assembled.
+        The Charm defines which Relations a given Service may establish, and
+        what kind of interface these Relations require.  In many cases, the
+        establishment of a Relation will result into an actual TCP connection being
+        created between the Service Units, but that's not necessarily the case.
+        Relations may also be established to inform Services of configuration
+        parameters, to request monitoring information, or any other details which
+        the Charm author has chosen to make available.
+
+   Service
+        juju operates in terms of services.
+
+        A service is any application (or set of applications) that is
+        integrated into the framework as an individual component which should
+        generally be joined with other components to perform a more complex
+        goal.
+
+        As an example, WordPress could be deployed as a service and, to perform
+        its tasks properly, might communicate with a database service
+        and a load balancer service.
+
+   Service Unit
+        A running instance of a given juju Service.  Simple Services may
+        be deployed with a single Service Unit, but it is possible for an
+        individual Service to have multiple Service Units running in independent
+        machines.  All Service Units for a given Service will share the same
+        Charm, the same relations, and the same user-provided configuration.
+
+        For instance, one may deploy a single MongoDB Service, and specify that
+        it should run 3 Units, so that the replica set is resilient to failures.
+        Internally, even though the replica set shares the same user-provided
+        configuration, each Unit may be performing different roles within th
+        replica set, as defined by the Charm.
+
+   Service Configuration
+        There are many different settings in an juju deployment, but
+        the term Service Configuration refers to the settings which a user can
+        define to customize the behavior of a Service.
+
+        The behavior of a Service when its Service Configuration changes is
+        entirely defined by its Charm.
+
+   Provisioning Agent
+        Software responsible for automatically allocating and terminating
+        machines in an Environment, as necessary for the requested configuration.
+
+   Machine Agent
+        Software which runs inside each machine that is part of an Environment,
+        and is able to handle the needs of deploying and managing Service Units
+        in this machine.
+
+   Service Unit Agent
+        Software which manages all the lifecycle of a single Service Unit.
+

=== added file 'source/hook-debugging.rst'
--- source/hook-debugging.rst	1970-01-01 00:00:00 +0000
+++ source/hook-debugging.rst	2012-01-18 20:50:30 +0000
@@ -0,0 +1,108 @@
+Hook debugging
+==============
+
+Introduction
+------------
+
+An important facility in any distributed system is the ability to
+introspect the running system, and to debug it. Within juju the
+actions performed by the system are executing charm defined
+hooks. The ``debug-log`` cli provides for inspecting the total state of
+the system via capturing the logs of all agents and output of all
+hooks run by the system.
+
+To facilitate better debugging of hooks, the ``debug-hooks`` cli
+provides for interactive shell usage as a substitute for running a
+hook. This allows a charm author or system adminstrator the ability
+to interact with the system in a live environment and either develop
+or debug a hook.
+
+How it works
+------------
+
+When the juju user utilizes the hook debug command like so::
+
+  juju debug-hooks unit_name [hook_name]
+
+juju is instructed to replace the execution of the hook from the
+charm of the respective service unit, and instead to execute it in a
+shell associated to a tmux session. If no hook name is given, then all
+hooks will be debugged in this fashion. Multiple hook names can also be
+specified on the command line. Shell regular expressions can also be
+utilized to specify hook names.
+
+The ``debug-hooks`` command line invocation will immediately connect
+to the remote machine of the remote unit and start a named shell
+connected to the same tmux session there.
+
+The native capabilities of tmux can be exploited to construct a full
+debug/development environment on the remote machine.
+
+When a debugged hook is executed a new named window will pop up in the
+tmux session with the hook shell started.  The new window's title will
+match the hook name, and the shell environment will have all the
+juju environment variables in place, and all of the hook cli API
+may be utilized (relation-get, relation-set, relation-list, etc.).
+
+It's important to note that juju serializes hook execution, so
+while the shell is active, no other hooks will be executed on the 
+unit.  Once the experimentation is done, the user must stop the hook
+by exiting the shell session.  At this point the system is then
+free to execute additional hooks.
+
+It's important to note that any state changes performed while in the
+hook window via relation-set are buffered till the hook is done
+executing, in the same way performed for all the relation hooks when
+running outside of a debug session.
+
+The debug-hooks can be used to debug the same hook being invoked
+multiple times as long as the user has not closed the debug screen
+session.
+
+The user can exit debug mode by exiting the tmux session (e.g.
+exiting all shells). The unit will then resume its normal
+processing.
+
+
+Limitations
+-----------
+
+Note that right now one can only query relation information when
+debugging a running relation hook.  This means commands such as
+relation-get, relation-set, etc, will not work on a hook like
+'install' or 'upgrade'.
+
+This problem will be solved once the following bug is fixed:
+
+    https://bugs.launchpad.net/juju/+bug/767195
+
+
+Internals
+---------
+
+Internally the ``debug-hooks`` cli begins by verifying its arguments,
+namely the unit exists, and the named hook is valid for the charm.
+After that it modifies the zookeeper state of the unit node, setting
+a flag noting the hook to debug. It then establishes an ssh 
+connection to the machine and executes the tmux command.
+
+The unit-agent will establish a watch on its own debug settings, on
+changes introspecting the debug flag, and pass any named hook values 
+down to the hook executor, which will construct debug hook scripts on 
+the fly for matching hooks. These debug hook scripts are responsible
+for connecting to tmux and monitoring the execution of the hook
+therein.
+
+Special care will be taken to ensure the viability of the tmux 
+session and that debug mode is active before creating the interactive
+hook window in tmux.
+
+
+Screen vs. tmux
+---------------
+
+Initially juju used GNU screen for the debugging sessions rather
+than tmux, but tmux turned out to make it easier to avoid race
+conditions when starting the same session concurrently, as done for
+the debugging system.  This was the main motivation that prompted
+the change to tmux.  They both worked very similarly otherwise.

=== added file 'source/index.rst'
--- source/index.rst	1970-01-01 00:00:00 +0000
+++ source/index.rst	2012-01-18 20:50:30 +0000
@@ -0,0 +1,35 @@
+Documentation
+=============
+
+.. note:: juju is still in a stage of fast development, and is not yet
+        ready for prime time.  The current software is being made available as
+        an early technology preview, and while it can be experimented with, it
+        should not be used in real deployments just yet.
+
+.. toctree::
+   :maxdepth: 2
+
+   about
+   faq
+   getting-started
+   user-tutorial
+   write-charm
+   charm
+   expose-services
+   hook-debugging
+   upgrades
+   charm-upgrades
+   provider-configuration-ec2
+   provider-configuration-local
+   juju-internals
+   juju-drafts
+   glossary
+   generated/modules
+
+
+Index and Glossary
+==================
+
+* :ref:`glossary`
+* :ref:`genindex`
+* :ref:`search`

=== added directory 'source/internals'
=== added file 'source/internals/agent-presence.rst'
--- source/internals/agent-presence.rst	1970-01-01 00:00:00 +0000
+++ source/internals/agent-presence.rst	2012-01-18 20:50:30 +0000
@@ -0,0 +1,154 @@
+Agent presence and settings
+===========================
+
+Agents are a set of distributed processes within the juju
+framework tasked individually with various juju roles. Each agent
+process interacts with zookeeper state and its environment to perform
+its role.
+
+Common to all agents are the need to make their presence known, such
+that it can be monitored for availability, as well the need for storage
+so an agent can record its state.
+
+Presence
+--------
+
+The presence/aliveness of an agent process within the zookeeper state
+hierarchy is denoted by an ephemeral node. This ephemeral presence
+node is also used to store transient settings by the agent
+process. These transient values will have a scope of the agent process
+lifetime. These ephemeral presence nodes are stored under the /agents
+container in a hierarchy, according to their agents role. Agents
+fufill many different roles within the juju system. Within the
+/agents container hierarchy, each agent's ephemeral node is contained
+within an <agent-role> container.
+
+For example, unit agents are stored in the following container::
+
+  /agents/unit/
+   
+And provisioning agents in::
+
+  /agents/provisioning/
+
+The agent presence node within these role containers is further
+distinguished by the id it chooses to use within the container. Some
+agents are commonly associated to a persistent domain object, such as
+a unit or machine, in that case they will utilize the persistent domain
+object's id for their node name.
+
+For example, a unit agent for unit 11 (display name: mysql/0), would
+have a presence node at::
+
+  /agents/unit/unit-11
+
+For agents not associated to a persistent domain object, the number of
+agents is determined by configuration, and they'll utilize an ephemeral
+sequence to denote their id. For example the first provisioning agent
+process in the system would have a path::
+
+ /agents/provisioning/provisioning-0000000000
+
+and the second
+
+ /agents/provisioning/provisioning-0000000001
+
+Persistence
+-----------
+
+All agents are able to store transient settings of the agent process
+within their ephemeral presence nodes within zookeeper. If an agent
+needs persistent settings, they should be stored on an associated
+peristent domain object.
+
+
+Availability	
+------------
+
+One of the key features of the juju framework, is an absence of
+single points of failures. To enable availability across agents we'll
+run multiple instances of agents as appropriate, monitor the presence
+of agents, and restart them as nescessary. Using the role information
+and the agent id as encoded in the presence node path, we can dispatch
+appropriate error handling and recovery logic, ie. restart a unit
+agent, or provisioning agent.
+
+For agents providing cluster wide services, it will be typical to have
+multiple agents for each role (ie. provisionig, recovery).
+
+A recovery agent will need to distinguish causal factors regarding the
+disappearance of a unit presence node. In addition to error scenarios,
+the configuration state may change such that an agent is no longer
+nescessary, for example an unused machine being terminated, or a unit no
+longer being assigned to a machine. To facilitate identiying the
+cause, a recovery agent would subscribe to the topology to distinguish
+configuration change vs. a runtime change. For agents not associated
+to a persistent domain object, this identification will be based on
+examining the configured number of agent for the role, and verifying
+that it matches the runtime state.
+
+
+Startup and recovery
+-------------------- 
+
+On startup, an agent will attempt to create its presence node. For
+agents associated to persistent domain objects, this process will
+either succeed, or result in an error due to an existing agent already
+in place, as the ids used are unique to a single instance of the agent
+since the id is based on the domain object id. 
+
+For agents not attached to persistent domain objects, they should
+verify their configuration parameter for the total number of agents
+for the role. 
+
+In the case of a conflict or a satisified configuration the agent
+process should terminate with an error message.
+
+
+Agent state API
+---------------
+
+
+``IAgentAssociated``::
+
+  """An api for persistent domain objects associated to an agent."""
+ 
+  def has_agent():
+      """Return boolean whether the agent (presence node) exists."""
+
+  def get_agent_state():
+      """Retrieve the agent associated to this domain object."""
+
+  def connect_agent():
+      """Create an agent presence node.
+      
+      This serves to connect the agent process with its agent state,
+      and will create the agent presence node if doesn't exist, else
+      raise an exception.
+
+      Returns an agent state.
+      """
+
+
+``IAgentState``::
+
+  def get_transient_data():
+      """
+      Retrieve the transient data for the agent as a byte string.
+      """
+
+  def set_transient_state(data):
+      """
+      Set the transient data for the agent as a byte string.
+      """
+
+  def get_domain_object(): 
+      """ 
+      TBD if Desireable. An agent attached to a persistent domain
+      object has all the knowledge to retrieve the associated
+      persistent domain object. For a machine agent state, this would
+      retrieve the machine state. For a unit agent state this would
+      retrieve the unit. Most agent implementations will already have
+      access to the domain object, and will likley retrieve or create
+      the agent from it.  
+      """

=== added file 'source/internals/expose-services.rst'
--- source/internals/expose-services.rst	1970-01-01 00:00:00 +0000
+++ source/internals/expose-services.rst	2012-01-18 20:50:30 +0000
@@ -0,0 +1,143 @@
+Service exposing implementation details
+=======================================
+
+
+Not in scope
+------------
+
+It is not in the scope of this specification to determine mapping to a
+public DNS or other directory service.
+
+
+Implementation of ``expose`` and ``unexpose`` subcommands
+---------------------------------------------------------
+
+Two new user commands were added::
+
+    juju expose <service name>
+
+    juju unexpose <service name>
+
+These commands set and remove a flag znode, **/services/<internal
+service id>/exposed**, respectively.
+
+
+Hook command additions
+----------------------
+
+Two new hook commands were added for opening and closing ports. They
+may be executed within any charm hook::
+
+    open-port port[/protocol]
+
+    close-port port[/protocol]
+
+These commands store in the ZK tree, under **/units/<internal unit
+id>/ports**, the desired opened port information as serialized to
+JSON. For example, executing ``open-port 80`` would be serialized as
+follows::
+
+    {"open": [{"port": 80, "proto": "tcp"}, ...]}
+
+This format accommodates tracking other ancillary information for
+exposing services.
+
+These commands are executed immediately within the hook.
+
+
+New ``exposed`` and ``unexposed`` service hooks
+-----------------------------------------------
+
+The ``exposed`` service hook runs upon a service being exposed with
+the ``juju expose`` command. As part of the unit workflow, it is
+scheduled to run upon the existence of **/services/<internal service
+id>/exposed** and the service unit being in the ``started`` state.
+
+Likewise, the ``unexposed`` service hook runs upon the removal of a
+**/services/<internal service id>/exposed** flag znode.
+
+These hooks will be implemented at a future time.
+
+
+``juju status`` display of opened ports
+-------------------------------------------
+
+If a service has been exposed, then the juju status output is
+augmented. For the YAML serialization, for each exposed service, the
+``exposed`` key is added, with the value of ``true``. (It is not
+displayed otherwise.) For each service unit of an exposed service with
+opened ports, the ``open-ports`` key is added, with its value a
+sequence of ``port/proto`` strings. If no ports are opened, its value
+is an empty list.
+  
+
+Provisioning agent implementation
+---------------------------------
+
+The provisioning agent currently is the only place within juju
+that can take global actions with respect to the provider. Consequently,
+provisioning is currently responsible for the current, if simple EC2
+security group management (with the policy of open all ports, seen in
+the code `juju.providers.ec2.launch.EC2LaunchMachine`).
+
+The provisioning agent watches for the existence of
+**/services/<internal service id>/exposed**, and if so watches the
+service units settings **/units/<internal unit id>/ports** and makes
+changes in the firewall settings through the provider.
+
+For the EC2 provider, this is done through security groups (see
+below). Later we will revisit to let a machine agent do this in the
+context of iptables, so as to get out of the 500 security group limit
+for EC2, enable multiple service units per machine, be generic with
+other providers, and to provide future support for internal firewall
+config.
+
+
+EC2 provider implementation
+---------------------------
+
+Prior to the launch of a new machine instance, a unique EC2 security
+group is added. The machine instance is then assigned to this group at
+launch. Likewise, terminating the machine will result in the EC2
+provider deleting the security group for the machine. (This cleanup
+will be implemented in a future branch.)
+
+Given this model of a security group per machine, with one service
+unit per machine, exposing and unexposing ports for a service unit
+corresponds to EC2's support for authorization and revocation of ports
+per security group. In particular, EC2 supports a source address of
+``0.0.0.0/0`` that corresponds to exposing the port to the world.
+
+To make this concrete, consider the example of exposing the
+``my-wordpress`` service. Once the command ``open-port 80`` has been
+run on a given service unit of ``my-wordpress``, then for the
+corresponding machine instance, the equivalent of this EC2 command is
+run::
+
+    ec2-authorize $MACHINE_SECURITY_GROUP -P tcp -p 80 -s 0.0.0.0/0
+
+``$MACHINE_SECURITY_GROUP`` is named ``juju-ENVIRONMENT-MACHINE_ID``,
+eg. something like ``juju-prod-2``.
+
+Any additional service units of ``my-wordpress``, if they run
+``open-port 80``, will likewise invoke the equivalent of the above
+command, for the corresponding machine security groups.
+
+If ``my-wordpress`` is unexposed, a ``my-wordpress`` service unit is
+removed, the ``my-wordpress`` service is destroyed, or the
+``close-port`` command is run for a service unit, then the equivalent
+of the following EC2 command is run, for all applicable machines::
+
+    ec2-revoke $MACHINE_SECURITY_GROUP -P tcp -p 80 -s 0.0.0.0/0
+
+Although this section showed the equivalent EC2 commands for
+simplicity, txaws is used for the actual implementation.
+
+
+Implementation plan
+-------------------
+
+The following functionality needs to be added. This should divisible
+into separate, small branches:
+
+    * Implement exposed and unexposed hooks.

=== added file 'source/internals/unit-agent-hooks.rst'
--- source/internals/unit-agent-hooks.rst	1970-01-01 00:00:00 +0000
+++ source/internals/unit-agent-hooks.rst	2012-01-18 20:50:30 +0000
@@ -0,0 +1,307 @@
+Unit Agent hooks
+================
+
+Introduction
+------------
+
+The Unit Agent (**UA**) in juju is responsible for managing and
+maintaining the per-machine service units. By calling life-cycle and
+state change hooks the UA is able to allow the Service Unit to respond
+to changes in the state of the environment. This is done through the
+invocation of hooks provided by the charm author.
+
+This specification outlines the interaction between the UA, the
+running software being managed by the UA and the hooks invoked in
+response to state or process level changes in the runtime.
+
+Hooks_ are defined in another document. This specification only
+captures how they are invoked and managed, not why.
+
+.. _Hooks: ../charm.html#hooks
+
+When the Machine Agent (**MA**) spawns a UA it does so in order to
+manage the smallest managed unit of service deployment and
+management. The process managed by the UA will be called the **UAP**
+later in the documentation.
+
+The UAP does not directly communicate with the UA, that is the
+responsibility of the hooks and is handled by the provided command
+line tools. The means through which that communication occurs and the
+semantics of it are described in this document.
+
+
+Hooks access to settings
+------------------------
+
+Hooks have access to two kinds of settings. The first is the
+*"service settings"*, which cover configuration details for the
+all units of the given service.  These are usually provided
+manually by the user, are global to the service, and will not
+be written to by service units themselves.  This is the
+principal way through which an administrator configures the
+software running inside an juju service unit.
+
+The second kind is known as *"relation settings"*, and are
+made available to service units whenever they are participating in
+a relation with one or more service units.  In these cases, each
+participating unit will have its own set of settings specific to
+that relation, and will be able to query both its local settings
+and the remote settings from any of the participating units.
+That's the main mechanism used by juju to allow service units
+to communicate with each other.
+
+Using the example of a blog deployment we might include information
+such as the theme used by the blog engine and the title of the blog in
+the "service settings". The "relation settings" might contain specific
+information about the blog engines connection to a database deployed
+on its behalf, for example and IP address and port.
+
+There is a single ZK node for the "service settings" and another for
+the "relation settings". Within this node we store an dictionary
+mapping string keys to opaque blobs of information which are managed
+by the service hooks and the juju administrator.
+
+Hooks are presented with a synchronous view of the state of these
+nodes. When a request is made for a particular setting in a particular
+node the cache will present a view of that node that is consistent to
+the client for the lifetime of the hook invocation. For example,
+assume a settings node with settings 'a' and 'b'. When the hook
+requests the value of 'a' from the a relation settings node we would
+present a consistent view of those settings should they request 'a' or
+'b' from that same relation settings during the lifetime of the
+hook. If however they were to attempt to request value 'a' from a
+different relation settings node this new nodes setting would be
+cached at the time of its first interaction with the hook. Repeated
+reads of data from the same settings node will continue to yield the
+clients view of that data.
+
+When manipulating data, even if the initial interaction with the data
+is a set, the settings are first read into the UA cache and the cache
+is updated with the current value.
+
+
+Service Unit name
+-----------------
+
+A service unit name in juju is formed by including both the name
+of the service and a monotonically increasing number that uniquely
+specifies the service unit for the life time of an juju
+deployment::
+
+      <service_name>/<service_unit_number>
+
+This results in name like "wordpress/1" and "mysql/1". The numbers
+themselves are not significant but do obey the rule that they will not
+be reused during the lifetime of a service. This means that if a UA
+goes away the number that represented it is retired from the
+deployment.
+
+For additional details see juju/state/service.py.
+
+
+Client Id
+---------
+
+Because of the way in which settings state is presented through the
+command line utilities within hooks clients are provided a string
+token through a calling environmental variable,
+*JUJU_CLIENT_ID*. Using this variable all command line tools will
+connect with a shared common state when used from a single hook
+invocation.
+
+The few command line utilities, such as juju-log, which could be
+called outside the context of a hook need not pass a client id. At the
+time of this writing its expected that cli tools which don't need hook
+context either don't make an effort to present a stable view of
+settings between calls (and thus run with a completely pass-through
+cache proxy) or don't interact directly with the state.
+
+However as indicated below the *--client_id* flag can be passed
+directly to any tool indicating the caching context which should be
+used. This facilitates testing as well as allowing some flexibility in
+the future.
+
+Passing a client_id which the UA is unaware of (or which has expired
+through some other means) will result in an error and an exit code
+being returned to the client.
+
+
+Hook invocation and communication
+---------------------------------
+
+Twisted (which is used to handle networking and asynchronous
+interactions throughout the codebase) defines a key-value oriented
+binary protocol called AMP which is used to communicate between the UA
+and the hooks executed on behalf of the charm. To facilitate this
+the filename of a Unix Domain socket is provided through the process
+environment. This socket is shared among all hook invocations and can
+even be used by tools outside the context of a particular hook
+invocation. Because of this providing a 'client id'_ to calls will
+establish a connection to an internal data-cache offering a consistent
+view of settings on a per-node, per-client basis.
+
+Communication over this socket takes place using an abstraction
+provided by AMP called Commands. Hooks trigger, through the invocation
+of utility commands, these commands to the provided socket. These
+commands in turn schedule interactions with the settings available in
+ZK.
+
+Because of the policy used for scheduling changes to settings the
+actions of hooks are not applied directly to ZK (and this are not
+visible outside the particular UA invoking the hook) until the hook
+terminates with a success code.
+
+Here are the commands the initial revision will support and a bit about
+there characteristics:
+
+    * **get(client_id, unit_name, setting_name)** - This command will return the
+        value for a given key name or return a KeyError. A key error
+        can be mapped through to the cli as null with a failed exit
+        code. **unit_name** is processed using the standard `Service
+        Unit Name`_ policy.
+
+    * **set(client_id, unit_name, json_blob)** - This command will enqueue a
+        state change to ZK pending successful termination of the
+        hook. **unit_name** is processed using the standard `Service
+        Unit Name`_ policy. The json_blob is a JSON string
+        serialization of a dict which will be applied as a set of
+        updates to the keys and values stored in the existing
+        settings. Because the cache object contains the updated state
+        (but is not visiable outside the hook until successful
+        completion) subsequent reads of settings would return the
+        values provided by the set call.
+
+    * **list_relations(client_id)** - Returns a list of all relations
+        associated with a hook at the time of invocation. The values
+        of this call will typically also be exposed as a environment
+        variable, **JUJU_MEMBERS**.
+
+    * **flush(client_id)** - reserved
+
+    * **sync(client_id)** - reserved
+
+    * **wait(client_id, keyname)** - reserved
+
+
+Unit Agent internal state
+-------------------------
+
+This is a list of internal state which the UA maintains for the proper
+management of hook invocations.
+
+    * which hooks have fired (and the expected result state).
+    * the UNIX domain socket passed to hooks for AMP communication
+    * the path to the container in which the Service Unit is executing
+      (passed in environment to hooks).
+    * the cached state of relationship nodes and settings relative to
+      particular hook invocations.
+
+
+Command line interface
+----------------------
+
+While the command line utilities provided use the underlying AMP
+commands to enact their work they provide a standard set of utilities
+for passing data between files and ZK state.
+
+Hooks have access to many commands provided by juju for
+interfacing with settings. These provide a set of standard command
+line options and conventions.
+
+     * Command line tools like *relation-set* will check stdin
+       processing the provided input as a JSON dict of values that
+       should be handled as though they were command line
+       arguments. Using this convention its possible to easily set
+       many values at once without any thought to escaping values for
+       the shell.
+
+     * Similar to *curl(1)* if you start the data with the letter @,
+       the rest should be a file name to read the data from, or - if
+       you want to read the data from stdin.
+
+    * Command line tools responsible for returning data to the user,
+      such as **relation-get**, will output JSON by default when
+      returning more than a single value or **--format=json** is
+      present in the command line. Requests for a single value default
+      to returning the value without JSON serialisation unless the
+      --format=json flag is passed.
+
+    * Output from command lines tools default to stdout. If the **-o**
+      option is provided any tool will write its output to a file
+      named after that flag. ex. **relation-get -o /tmp/output.json**
+      will create or replace a file called /tmp/output.json with the
+      data existent in the relation.
+
+
+Logging
+-------
+
+Command line hooks communicate with the user/admin by means three
+primary channels.
+
+    * **Hook exit code** Zero is success, anything is regarded as hook
+      failure and will cause the hook to be run at a later time.
+
+    * **Stdout/Stderr** Messages printed, echoed or otherwise emitted
+        from the hooks on stdout or stderr are converted to log
+        messages of levels INFO and ERROR respectively. These messages
+        will then be emitted by the UA as they occur and are not
+        buffered like global state changes.
+
+    * **juju-logger** (reserved) An additional command line tool
+        provided to communicate more complex logging messages to the
+        UA and help them be made available to the user.
+
+
+Calling environment
+-------------------
+
+Hooks can expect to be invoked with a standard environment and
+context. The following be included:
+
+    * `$JUJU_SOCKET` - Path to a UNIX Domain socket which will be
+      made available to the command line tools in order to communicate
+      with the UA.
+
+    * `$JUJU_CLIENT_ID` - A unique identifier passed to a hook
+      invocation used to populate the --client_id flag to cli
+      tools. This is describe in the section, `Client Id`_.
+
+   * `$JUJU_LOCAL_UNIT` - The unit name of the unit this hook is
+     being invoked in. (ex: myblog/0)
+
+   * `$JUJU_SERVICE` - The name of the service for which this hook
+     is running. (ex: myblog)
+
+   * `$JUJU_CHARM` - The name of the charm which deployed the
+     unit the hook is running in. (ex: wordpress)
+
+
+Hooks called for relationships will have the follow additional
+environment variables available to them.
+
+    * `$JUJU_MEMBERS` - A space-delimited list of qualified
+      relationship ids uniquely specifying all the UAs participating in
+      a given relationship. (ex. "wordpress/1 worpress/2")
+
+    * `$JUJU_RELATION` - The relation name this hook is running
+      for.  It's redundant with the hook name, but is necessary for
+      the command line tools to know the current context.
+
+    * `$JUJU_REMOTE_UNIT` - The unit name of the remote unit
+      which has triggered the hook execution.
+
+
+Open issues
+-----------
+
+There are still a number of open issues with this specification. There
+is still open debate if the UA runs inside the same process
+space/container and how this will play out with security. This has
+ramifications to this specification as well as we'd take steps to make sure
+client code cannot violate the ZK juju by connection with their
+own copy of the code on a known port.
+
+There specification doesn't define 100% which command line tools will
+get which environment settings.
+

=== added file 'source/internals/unit-agent-startup.rst'
--- source/internals/unit-agent-startup.rst	1970-01-01 00:00:00 +0000
+++ source/internals/unit-agent-startup.rst	2012-01-18 20:50:30 +0000
@@ -0,0 +1,156 @@
+Unit Agent startup
+==================
+
+Introduction
+------------
+
+The unit agent manages a state machine workflow for the unit. For each
+transition the agent records the current state of the unit and stores
+that information as defined below. If the agent dies, or is restarted
+for any reason, the agent will resume the workflow from its last known
+state.
+
+The available workflow states and transitions are::
+
+    "new" -> "ready" [label="install"]
+    "new" -> "install-error" [label="error-install"]
+    "ready" -> "running" [label="start"]
+    "ready" -> "start-error" [label="error-start"]
+    "running" -> "ready" [label="stop"]
+    "running" -> "stop-error" [label="error-stop"]
+
+The agent does not have any insight into external processes that the
+unit's charm may be managing, it's sole responsibility is executing
+hooks in deterministic fashion as a consequence of state changes.
+
+Charm hook execution (excepting relation hooks), corresponds to
+invoking a transition on the unit workflow state. Any errors during a
+transition, will prevent a state change. All state changes are
+recorded persistently on the unit state. If a state change fails, it
+will be reattempted until a max number of retries, after which the
+unit workflow will be transitioned to failure state specific to the
+current state and attempted transition, and administrator intervention
+will be required to resolve.
+
+On startup the agent will, establish its presence node (as per the
+agent state spec), and read the state of the unit. If the unit is not
+running it will have its transition hooks executed to place it in the
+running state.
+
+The persistent state of the unit as per this state machine is stored
+locally on disk of the unit. This allows for the continuation of long
+running tasks in the face of transient communication failures with zk.
+For example if a long running install task is kicked off then it may
+complete and record the transition to persistent state even if the zk
+connection is not available when the install hook has completed.
+
+The persistent workflow state of the unit is also replicated to
+zookeeper for introspectability, and communication of local failures
+to the global coordination space. The zk state for this workflow is
+considered non-authoritative by the unit-agent if its operating in a
+disconnected mode.
+
+
+Startup sequence
+----------------
+
+The following outlines the set of steps a unit agent executes when
+starting up on a machine resource.
+ 
+ - Unit agent process starts, inspects its configuration and
+   environment.
+ 
+ - A zookeeper client handle is obtained.
+ 
+ - The agent retrieves its unit state, via the service state manager.
+ 
+ - The agent retrieves its service relations, via the relation state
+   manager.
+ 
+At deployment time, a service is deployed with its dependencies. Those
+dependencies are actualized in relations between the services that are
+being deployed. There are several times of relations that can be
+established. The most common is a client/server relationship, like a
+client application and a database server. Each of the services in such
+a relation performs a role within that relation. In this case the
+database performs the 'server' role, and the client application
+performs the 'client' role. When actualizing the service relations,
+the physical layout within the coordination space (zookeeper) takes
+these roles into account.
+ 
+For example in the client server relation, the service performing the
+'server' role has its units under a service-role container named
+'server' denoting the role of its units in the relation.
+
+For each service relation, the agent will
+ 
+ - Creates its ``/relations/relation-1/settings/unit-X`` relation
+   local data node, if it doesn't exist.
+ 
+ - Creates its ``/relations/relation-1/<service-role>/unit-X`` if it
+   doesn't exist. The node is not considered 'established' for the
+   purposes of hook execution on other units till this node exists.
+ 
+ - Establish watches as outlined below.
+ 
+
+Unit relation observation
+-------------------------
+
+Based on the relation type and the unit's service role, the unit agent
+will establish will retrieve and establish watches on the other units
+in the relation.
+ 
+The relation type determines which service role container the
+container will get and observe children of. In a client server
+relation there would be both::
+ 
+    /relations/relation-1/server
+    /relations/relation-1/client
+ 
+And a client unit would observe and process the unit children of the
+server node which functions as the service-role representing the
+endpoint of the relation. In a peer relation there would be a
+service-role container with the path ``/relations/relation-1/peer``
+which would be observed and processed.
+ 
+ - The unit agent will get the children and establish a watch (w-1) on
+   the service role container in the relationship.
+ 
+ - For each unit found, the relation local data node
+   ``/relations/relation-X/settings/unit-X`` will have a get watch
+   (w-2) established .
+ 
+ - the agent stores a process local variable noting which children its
+   seen (v-1)
+ 
+Finally after processing the children.
+ 
+ - if the unit agent is completing its startup, and another
+   'established' unit was found, the agent should fire the its
+   relation-changed hook (type joined).
+ 
+ 
+Watch behavior
+--------------
+ 
+ - (w-1) if the service-role child watch fires with a delete event,
+   reestablish the watch, and execute the relation-changed hook (type
+   departed), update variable (v-1)
+ 
+ - (w-1) if the service-role child watch fires with a created event,
+   reestablish the watch, and execute the relation-changed hook (type
+   joined), update variable (v-1)
+
+ - (w-1) if the service-role node child watch fires with a deleted
+   event, the agent invokes the ``relation-broken`` hook. (the service
+   role container was removed)
+ 
+ - (w-3) if a unit relation local data node watch fires with a
+   modified event, reestablish the watch, and execute the
+   relation-changed hook (type changed) if the unit is in variable
+   (v-1).
+ 
+ - (w-3) if a unit relation local data node watch fires with a delete
+   event, ignore (the agent exists watch must also have fired with a
+   delet

=== added file 'source/internals/zookeeper.rst'
--- source/internals/zookeeper.rst	1970-01-01 00:00:00 +0000
+++ source/internals/zookeeper.rst	2012-01-18 20:50:30 +0000
@@ -0,0 +1,215 @@
+ZooKeeper
+=========
+
+This document describes the reasoning behind juju's use of ZooKeeper,
+and also the structure and semantics used by juju in the ZooKeeper
+filesystem.
+
+juju & ZooKeeper
+--------------------
+
+ZooKeeper offers a virtual filesystem with so called *znodes* (we'll
+refer to them simply as *nodes* in this document).  The state stored in
+the filesystem is fully introspectable and observable, and the changes
+performed on it are atomic and globally ordered.  These features are
+used by juju to maintain its distributed runtime state in a reliable
+and fault tolerant fashion.
+
+When some part of juju wants to modify the runtime state anyhow,
+rather than enqueuing a message to a specific agent, it should instead
+perform the modification in the ZooKeeper representation of the state,
+and the agents responsible for enforcing the requested modification
+should be watching the given nodes, so that they can realize the changes
+performed.
+
+When compared to traditional message queueing, this kind of behavior
+enables easier global analysis, fault tolerance (through redundant
+agents which watch the same states), introspection, and so on.
+
+
+Filesystem Organization
+-----------------------
+
+The semantics and structures of all nodes used by juju in its
+ZooKeeper filesystem usage are described below.  Each entry here maps
+to a node, and the semantics of the given node are described right
+below it.
+
+Note that, unlike a traditional filesystem, nodes in ZooKeeper may
+hold data, while still being a parent of other nodes.  In some cases,
+information is stored as content for the node itself, in YAML format.
+These are noted in the tree below under a bulleted list and *italics*.
+In other cases, data is stored inside a child node, noted in the tree
+below as indented **/bold**.  The decision around whether to use a
+child node or content in the parent node revolves around use cases.
+
+
+.. Not for now:
+
+        .. _/files:
+
+        **/files**
+          Holds information about files stored in the machine provider.  Each
+          file stored in the machine provider's storage location must have a
+          entry here with metadata about the file.
+
+          **/<filename>:<sha256>**
+            The name of nodes here is composed by a plain filename, a colon, and
+            the file content's sha256.  As of today these nodes are empty, since
+            the node name itself is enough to locate it in the storage, and to
+            assess its validity.
+
+**/topology**
+  Describes the current topology of machines, services, and service units.  Nodes
+  under ``/machines``, ``/services``, and ``/units``, should not be considered
+  as valid unless they are described in this file.  The precise format of this
+  file is an implementation detail.
+
+**/charms**
+  Each charm used in this environment must have one entry inside this
+  node.
+
+  :Readable by: Everyone
+
+  **/<namespace>:<name>-<revision>**
+    Represents a charm available in this environment.  The node name
+    includes the charm namespace (ubuntu, ~user, etc), the charm name,
+    and the charm revision.
+
+    - *sha256*: This option contains the sha256 of a file in the file
+      storage, which contains the charm bundle itself.
+
+    - *metadata*: Contains the metadata for the charm itself.
+
+    - *schema*: The settings accepted by this charm. The precise details
+      of this are still unspecified.
+
+**/services**
+  Each charm to be deployed must be included under an entry in
+  this tree.
+
+  :Readable by: Everyone
+
+  **/service-<0..N>**
+    Node with details about the configuration for one charm, which can
+    be used to deploy one or more charm instances for this specific
+    charm.
+
+    - *charm*: The charm to be deployed.  The value of this option should
+      be the name of a child node under the ``/charms`` parent.
+
+    **/settings**
+      Options for the charm provided by the user, stored internally in
+      YAML format.
+
+      :Readable by: Charm Agent
+      :Writable by: Admin tools
+
+**/units**
+  Each node under this parent reflects an actual service agent which should
+  be running to manage a charm.
+
+  **/unit-<0..N>**
+    One running service.
+
+    :Readable by: Charm Agent
+    :Writable by: Charm Agent
+
+    **/machine**
+      Contains the internal machine id this service is assigned to.
+
+    **/charm-agent-connected**
+      Ephemeral node which exists when a charm agent is handling
+      this instance.
+
+
+**/machines**
+
+  **/machine-<0..N>**
+
+    **/provisioning-lock**
+      The Machine Provisioning Agent
+
+    **/machine-agent-connected**
+      Ephemeral node created when the Machine Agent is connected.
+
+    **/info**
+      Basic information about this machine.
+
+      - *public-dns-name*: The public DNS name of this machine.
+      - *machine-provider-id*: ie. EC2 instance id. 
+
+
+Provisioning a new machine
+--------------------------
+
+When the need for a new machine is determined, the following sequence of
+events happen inside the ZooKeeper filesystem to deploy the new machine:
+
+1. A new node is created at ``/machines/instances/<N>``.
+2. Machine Provisioning Agent has a watcher on ``/machines/instances/``, and
+   gets notified about the new node.
+3. Agent acquires a provisioning lock at
+   ``/machines/instances/<N>/provisioning-lock``
+4. Agent checks if the machine still has to be provisioned by verifying
+   if ``/machines/instances/<N>/info`` exists.
+5. If the machine has provider launch information, than the agent schedules
+   to come back to the machine after ``<MachineBootstrapMaxTime>``.
+6. If not, the agent fires the machine via the provider and stores the
+   provider launch info (ie. EC2 machine id, etc.) and schedules the
+   to come back to the machine after ``<MachineBootstrapMaxTime>``.
+7. As a result of a schedule call the machine provider verifies the
+   existence of a ``/machines/instance/<N>/machine-agent-connected`` node
+   and if it does sets a watch on it.
+8. If the agent node doesn't exist after the <MachineBootstrapMaxTime> then
+   the agent acquires the ``/machines/instances/<N>/provisioning-lock``, 
+   terminates the instance, and goes to step 6. 
+
+
+Bootstrap Notes
+~~~~~~~~~~~~~~~
+
+This verification of the connected machine agent helps us guard against any
+transient errors that may exist on a given virtual node due to provider 
+vagaries.
+
+When a machine provisioning agent comes up, it must scan the entire instance
+tree to verify all nodes are running. We need to keep some state to distinguish
+a node that has never come up from a node that has had its machine agent connection
+die so that a new provisioning agent can distinguish between a new machine bootstrap
+failure and an running machine failure.
+
+use a one time password (otp) via user data to guard the machine agent 
+permanent principal credentials.
+
+TODO... we should track a counter to keep track of how many times we've
+attempt to launch a single instance.
+
+
+Connecting a Machine
+--------------------
+
+When a machine is launched, we utilize cloud-init to install the requisite
+packages to run a machine agent (libzookeeper, twisted) and launch the 
+machine agent.
+
+The machine agent reads its one time password from ec2 user-data and connects
+to zookeeper and reads its permanent principal info and role information which
+it adds to its connection.
+
+The machine agent reads and sets a watch on 
+``/machines/instances/<N>/services/``. When a service is placed there the agent
+resolve its charm, downloads the charm, creates an lxc container, and launches
+a charm agent within the container passing the charm path.
+
+Starting a Charm
+------------------
+
+The charm agent connects to zookeeper using principal information provided
+by the machine agent. The charm agent reads the charm metadata, and 
+installs any package dependencies, and then starts invoking charm hooks.
+
+The charm agent creates the ephemeral node 
+``/services/<service name>/instances/<N>/charm-agent-connected``.
+
+The charm is running when....

=== added file 'source/juju-drafts.rst'
--- source/juju-drafts.rst	1970-01-01 00:00:00 +0000
+++ source/juju-drafts.rst	2012-01-18 20:50:30 +0000
@@ -0,0 +1,10 @@
+Drafts
+======
+
+This section contains documents which may be unreviewed, incomplete,
+incorrect, out-of-date, or all of those.
+
+.. toctree::
+   :glob:
+
+   drafts/*

=== added file 'source/juju-internals.rst'
--- source/juju-internals.rst	1970-01-01 00:00:00 +0000
+++ source/juju-internals.rst	2012-01-18 20:50:30 +0000
@@ -0,0 +1,11 @@
+Implementation details
+======================
+
+This section details topics which are generally not very useful
+for running juju, but may be interesting if you want to hack it.
+
+.. toctree::
+   :glob:
+
+   internals/*
+

=== added file 'source/provider-configuration-ec2.rst'
--- source/provider-configuration-ec2.rst	1970-01-01 00:00:00 +0000
+++ source/provider-configuration-ec2.rst	2012-01-18 20:50:30 +0000
@@ -0,0 +1,64 @@
+EC2 provider configuration
+--------------------------
+
+The EC2 provider accepts a number of configuration options, that can
+be specified in the ``environments.yaml`` file under an ec2 provider section.
+
+    access-key:
+        The AWS access key to utilize for calls to the AWS APIs.
+
+    secret-key:
+        The AWS secret key to utilize for calls to the AWS APIs.
+
+    ec2-uri:
+        The EC2 api endpoint URI, by default points to `ec2.amazonaws.com`
+
+    region:
+        The EC2 region, by default points to `us-east-1`. If 'ec2-uri' is
+        specified, it will take precedence.
+
+    s3-uri:
+        The S3 api endpoint URI, by default points to `s3.amazonaws.com`
+
+    control-bucket:
+        An S3 bucket unique to the environment, where some runtime metadata and
+        charms are stored.
+
+    juju-origin:
+        Defines where juju should be obtained for installing in
+        machines. Can be set to a "lp:..." branch url, to "ppa" for
+        getting packages from the official juju PPA, or to "distro"
+        for using packages from the official Ubuntu repositories.
+
+        If this option is not set, juju will attempt to detect the
+        correct origin based on its run location and the installed
+        juju package.
+
+    default-instance-type:
+        The instance type to be used for machines launched within the juju
+	environment. Acceptable values are based on EC2 instance type API names
+	like t1.micro or m1.xlarge.
+
+    default-image-id:
+        The default amazon machine image to utilize for machines in the
+        juju environment. If not specified the default image id varies by
+        region.
+
+    default-series:
+        The default Ubuntu series to use (`oneiric`, for instance). EC2 images
+        and charms referenced without an explicit series will both default to
+        the value of this setting.
+
+Additional configuration options, not specific to EC2:
+
+    authorized-keys-path:
+        The path to a public key to place onto launched machines. If no value
+        is provided for either this or ``authorized-keys`` then a search is
+        made for some default public keys "id_dsa.pub", "id_rsa.pub",
+        "identity.pub". If none of those exist, then a LookupError error is
+        raised when launching a machine.
+
+    authorized-keys:
+        The full content of a public key to utilize on launched machines.
+
+

=== added file 'source/provider-configuration-local.rst'
--- source/provider-configuration-local.rst	1970-01-01 00:00:00 +0000
+++ source/provider-configuration-local.rst	2012-01-18 20:50:30 +0000
@@ -0,0 +1,53 @@
+Local provider configuration
+----------------------------
+
+The local provider allows for deploying services directly against the local/host machine
+using LXC containers with the goal of experimenting with juju and developing formulas.
+
+The local provider has some additional package dependencies. Attempts to use
+this provider without these packages installed will terminate with a message
+indicating the missing packages.
+
+The following are packages are required.
+
+ - libvirt-bin
+ - lxc
+ - apt-cacher-ng
+ - zookeeper
+
+
+The local provider can be configured by specifying "provider: local" and a "data-dir":
+as an example::
+
+  local:
+    type: local
+    data-dir: /tmp/local-dev
+    control-bucket: juju-a14dfae3830142d9ac23c499395c2785999
+    admin-secret: b3a5dee4fb8c4fc9a4db04751e5936f4
+    juju-origin: distro
+    default-series: oneiric
+
+Upon running ``juju bootstrap`` a zookeeper instance will be started on the host
+along with a machine agent. The bootstrap command will prompt for sudo access
+as the machine agent needs to run as root in order to create containers on the
+local machine.
+
+The containers created are namespaced in such a way that you can create multiple
+environments on a machine. The containers also namespaced by user for multi-user
+machines.
+
+Local provider environments do not survive reboots of the host at this time, the
+environment will need to be destroyed and recreated after a reboot.
+
+
+Provider specific options
+=========================
+
+  data-dir: 
+    Directory for zookeeper state and log files. 
+   
+
+
+ 
+
+

=== added file 'source/upgrades.rst'
--- source/upgrades.rst	1970-01-01 00:00:00 +0000
+++ source/upgrades.rst	2012-01-18 20:50:30 +0000
@@ -0,0 +1,57 @@
+Upgrades
+========
+
+A core functionality of any configuration management system is
+handling the full lifecycle of service and configuration
+upgrades.
+
+Charm upgrades
+--------------
+
+A common task when doing charm development is iterating over
+charm versions via upgrading charms of a running service
+while it's live.
+
+The use case also extends to a user upgrading a deployed
+service's charm with a newer version from an upsteam charm
+repository.
+
+In some cases a new charm version will also reference newer
+software/package versions or new packages.
+
+More details in the `charm upgrades documentation`_
+
+.. _`charm upgrades documentation`: ./charm-upgrades.html
+
+
+*NOTE* At the moment this is the only upgrade form that juju
+provides.
+
+Service upgrades
+----------------
+
+There's an interesting set of upgrade use cases which embody lots of
+real world usage, which has been left for future work.
+
+One case is where an application is deployed across multiple service
+units, and the code needs to be upgraded in lock step across all of
+them (either due to software incompatability or data changes in
+related services).
+
+Additionally the practices of a rolling uprade, and cloning a service
+as an upgrade mechanism are also interesting problems, which are left
+for future work.
+
+juju upgrades
+-------------
+
+One last upgrade scenario, is upgrading of the juju software
+itself.
+
+At the moment juju is deployed from revision control, although it's
+being packaged for the future. Currently all of the juju agents
+maintain persistent connections to zookeeper, the failure of which may
+be grounds for the system to take corrective action. As a simple
+notion of performing system wide juju upgrades, the software would
+be updated on the existing systems, and then the agents restarted but
+instructed to keep their existing zookeeper session ids.

=== added file 'source/user-tutorial.rst'
--- source/user-tutorial.rst	1970-01-01 00:00:00 +0000
+++ source/user-tutorial.rst	2012-01-18 20:50:30 +0000
@@ -0,0 +1,335 @@
+.. _user-tutorial:
+
+User tutorial
+=============
+
+Introduction
+------------
+
+This tutorial demonstrates basic features of juju from a user perspective.
+An juju user would typically be a devops or a sys-admin who is interested in
+automated deployment and management of servers and services.
+
+Bootstrapping
+-------------
+
+The first step for deploying an juju system is to perform bootstrapping.
+Bootstrapping launches a utility instance that is used in all subsequent
+operations to launch and orchestrate other instances::
+
+  $ juju bootstrap
+
+Note that while the command should display a message indicating it has finished
+successfully, that does not mean the bootstrapping instance is immediately
+ready for usage. Bootstrapping an instance can require a couple of minutes. To
+check on the status of the juju deployment, we can use the status command::
+
+  $ juju status
+
+If the bootstrapping node has not yet completed bootstrapping, the status
+command may either mention the environment is not yet ready, or may display a
+connection timeout such as::
+
+  INFO Connecting to environment.
+  ERROR Connection refused
+  ProviderError: Interaction with machine provider failed:
+  ConnectionTimeoutException('could not connect before timeout after 2
+  retries',)
+  ERROR ProviderError: Interaction with machine
+  provider failed: ConnectionTimeoutException('could not connect before timeout
+  after 2 retries',)
+
+This is simply an indication the environment needs more time to complete
+initialization. It is recommended you retry every minute. Once the environment
+has properly initialized, the status command should display::
+
+  machines:
+    0: {dns-name: ec2-50-16-61-111.compute-1.amazonaws.com, instance-id: i-2a702745}
+    services: {}
+
+Note the following, machine "0" has been started. This is the bootstrapping
+node and the first node to be started. The dns-name for the node is printed.
+Also the EC2 instance-id is printed. Since no services are yet deployed to the
+juju system yet, the list of deployed services is empty
+
+Starting debug-log
+------------------
+
+While not a requirement, it is beneficial for the understanding of juju to
+start a debug-log session. juju's debug-log provides great insight into the
+execution of various hooks as they are triggered by various events. It is
+important to understand that debug-log shows events from a distributed
+environment (multiple-instances). This means that log lines will alternate
+between output from different instances. To start a debug-log session, from a
+secondary terminal issue::
+
+  $ juju debug-log
+  INFO Connecting to environment.
+  INFO Enabling distributed debug log.
+  INFO Tailing logs - Ctrl-C to stop.
+
+This will connect to the environment, and start tailing logs.
+
+Deploying service units
+-----------------------
+
+Now that we have bootstrapped the juju environment, and started the
+debug-log viewer, let's proceed by deploying a mysql service::
+
+  $ juju deploy --repository=/usr/share/doc/juju/examples local:oneiric/mysql
+  INFO Connecting to environment.
+  INFO Charm deployed as service: 'mysql'
+  INFO 'deploy' command finished successfully
+
+Checking the debug-log window, we can see the mysql service unit being
+downloaded and started::
+
+  Machine:1: juju.agents.machine DEBUG: Downloading charm
+  local:oneiric/mysql-11...
+  Machine:1: juju.agents.machine INFO: Started service unit mysql/0
+
+It is important to note the different debug levels. DEBUG is used for very
+detailed logging messages, usually you should not care about reading such
+messages unless you are trying to debug (hence the name) a specific problem.
+INFO debugging level is used for slightly more important informational
+messages. In this case, these messages are generated as the mysql charm's
+hooks are being executed. Let's check the current status::
+
+  $ juju status
+  machines:
+    0: {dns-name: ec2-50-16-61-111.compute-1.amazonaws.com, instance-id: i-2a702745}
+    1: {dns-name: ec2-50-16-117-185.compute-1.amazonaws.com, instance-id: i-227e294d}
+  services:
+    mysql:
+      charm: local:oneiric/mysql-11
+      relations: {}
+      units:
+        mysql/0:
+          machine: 1
+          relations: {}
+          state: null
+
+We can see a new EC2 instance has now been spun up for mysql. Information for
+this instance is displayed as machine number 1 and mysql is now listed under
+services. It is apparent the mysql service unit has no relations, since it has
+not been connected to wordpress yet. Since this is the first mysql service
+unit, it is being referred to as mysql/0, subsequent service units would be
+named mysql/1 and so on.
+
+.. note::
+        An important distinction to make is the difference between a service
+        and a service unit. A service is a high level concept relating to an
+        end-user visible service such as mysql. The mysql service would be
+        composed of several mysql service units referred to as mysql/0, mysql/1
+        and so on.
+
+The mysql service state is listed as null since it's not ready yet.
+Downloading, installing, configuring and starting mysql can take some time.
+However we don't have to wait for it to configure, let's proceed deploying
+wordpress::
+
+  $ juju deploy --repository=/usr/share/doc/juju/examples local:oneiric/wordpress
+
+Let's wait for a minute for all services to complete their configuration cycle and
+get properly started, then issue a status command::
+
+  $ juju status
+  machines:
+    0: {dns-name: ec2-50-16-61-111.compute-1.amazonaws.com, instance-id: i-2a702745}
+    1: {dns-name: ec2-50-16-117-185.compute-1.amazonaws.com, instance-id: i-227e294d}
+    2: {dns-name: ec2-184-72-156-54.compute-1.amazonaws.com, instance-id: i-9c7e29f3}
+  services:
+    mysql:
+      charm: local:oneiric/mysql-11
+      relations: {}
+      units:
+        mysql/0:
+          machine: 1
+          relations: {}
+          state: started
+    wordpress:
+      charm: local:oneiric/wordpress-29
+      relations: {}
+      units:
+        wordpress/0:
+          machine: 2
+          relations: {}
+          state: started
+
+mysql/0 as well as wordpress/0 are both now in the started state. Checking the
+debug-log would reveal wordpress has been started as well
+
+Adding a relation
+-----------------
+
+While mysql and wordpress service units have been started, they are still
+isolated from each other. An important concept for juju is connecting
+various service units together to create a bigger juju! Adding a relation
+between service units causes hooks to trigger, in effect causing all service
+units to collaborate and work together to reach the desired end state. Adding a
+relation is extremely simple::
+
+  $ juju add-relation wordpress mysql
+  INFO Connecting to environment.
+  INFO Added mysql relation to all service units.
+  INFO 'add_relation' command finished successfully
+
+Checking the juju status we see that the db relation now exists with state
+up::
+
+  $ juju status
+  machines:
+    0: {dns-name: ec2-50-16-61-111.compute-1.amazonaws.com, instance-id: i-2a702745}
+    1: {dns-name: ec2-50-16-117-185.compute-1.amazonaws.com, instance-id: i-227e294d}
+    2: {dns-name: ec2-184-72-156-54.compute-1.amazonaws.com, instance-id: i-9c7e29f3}
+  services:
+    mysql:
+      charm: local:oneiric/mysql-11
+      relations: {db: wordpress}
+      units:
+        mysql/0:
+          machine: 1
+          relations:
+            db: {state: up}
+          state: started
+    wordpress:
+      charm: local:oneiric/wordpress-29
+      relations: {db: mysql}
+      units:
+        wordpress/0:
+          machine: 2
+          relations:
+            db: {state: up}
+          state: started
+
+Exposing the service to the world
+---------------------------------
+
+All that remains is to expose the service to the outside world::
+
+    $ juju expose wordpress
+
+You can now point your browser at the public dns-name for instance 2 (running
+wordpress) to view the wordpress blog
+
+Tracing hook execution
+----------------------
+
+An juju user should never have to trace the execution order of hooks,
+however if you are the kind of person who enjoys looking under the hood, this
+section is for you. Understanding hook order execution, the parallel nature of
+hook execution across instances, and how relation-set in a hook can trigger the
+execution of another hook is quite interesting and provides insight into
+juju internals
+
+Here are a few important messages from the debug-log of this juju run.  The
+date field has been deliberately left in this log, in order to understand the
+parallel nature of hook execution.
+
+Things to consider while reading the log include:
+ * The time the log message was generated
+ * Which service unit is causing the log message (for example mysql/0)
+ * The message logging level. In this run DEBUG messages are generated by the
+   juju core engine, while WARNING messages are generated by calling
+   juju-log from inside charms (which you can read in the examples
+   folder)
+
+Let's view select debug-log messages which can help understand the execution
+order::
+
+  14:29:43,625 unit:mysql/0: hook.scheduler DEBUG: executing hook for wordpress/0:joined
+  14:29:43,626 unit:mysql/0: unit.relation.lifecycle DEBUG: Executing hook db-relation-joined
+  14:29:43,660 unit:wordpress/0: hook.scheduler DEBUG: executing hook for mysql/0:joined
+  14:29:43,660 unit:wordpress/0: unit.relation.lifecycle DEBUG: Executing hook db-relation-joined
+  14:29:43,661 unit:wordpress/0: unit.relation.lifecycle DEBUG: Executing hook db-relation-changed
+  14:29:43,789 unit:mysql/0: unit.hook.api WARNING: Creating new database and corresponding security settings
+  14:29:43,813 unit:wordpress/0: unit.hook.api WARNING: Retrieved hostname: ec2-184-72-156-54.compute-1.amazonaws.com
+  14:29:43,976 unit:mysql/0: unit.relation.lifecycle DEBUG: Executing hook db-relation-changed
+  14:29:43,997 unit:wordpress/0: hook.scheduler DEBUG: executing hook for mysql/0:modified
+  14:29:43,997 unit:wordpress/0: unit.relation.lifecycle DEBUG: Executing hook db-relation-changed
+  14:29:44,143 unit:wordpress/0: unit.hook.api WARNING: Retrieved hostname: ec2-184-72-156-54.compute-1.amazonaws.com
+  14:29:44,849 unit:wordpress/0: unit.hook.api WARNING: Creating appropriate upload paths and directories
+  14:29:44,992 unit:wordpress/0: unit.hook.api WARNING: Writing wordpress config file /etc/wordpress/config-ec2-184-72-156-54.compute-1.amazonaws.com.php
+  14:29:45,130 unit:wordpress/0: unit.hook.api WARNING: Writing apache config file /etc/apache2/sites-available/ec2-184-72-156-54.compute-1.amazonaws.com
+  14:29:45,301 unit:wordpress/0: unit.hook.api WARNING: Enabling apache modules: rewrite, vhost_alias
+  14:29:45,512 unit:wordpress/0: unit.hook.api WARNING: Enabling apache site: ec2-184-72-156-54.compute-1.amazonaws.com
+  14:29:45,688 unit:wordpress/0: unit.hook.api WARNING: Restarting apache2 service
+
+
+Scaling the juju
+--------------------
+
+Assuming your blog got really popular, is having high load and you decided to
+scale it up (it's a cloud deployment after all). juju makes this magically
+easy. All what is needed is::
+
+  $ juju add-unit wordpress
+  INFO Connecting to environment.
+  INFO Unit 'wordpress/1' added to service 'wordpress'
+  INFO 'add_unit' command finished successfully
+  $ juju status
+  machines:
+    0: {dns-name: ec2-50-16-61-111.compute-1.amazonaws.com, instance-id: i-2a702745}
+    1: {dns-name: ec2-50-16-117-185.compute-1.amazonaws.com, instance-id: i-227e294d}
+    2: {dns-name: ec2-184-72-156-54.compute-1.amazonaws.com, instance-id: i-9c7e29f3}
+    3: {dns-name: ec2-50-16-156-106.compute-1.amazonaws.com, instance-id: i-ba6532d5}
+  services:
+    mysql:
+      charm: local:oneiric/mysql-11
+      relations: {db: wordpress}
+      units:
+        mysql/0:
+          machine: 1
+          relations:
+            db: {state: up}
+          state: started
+    wordpress:
+      charm: local:oneiric/wordpress-29
+      relations: {db: mysql}
+      units:
+        wordpress/0:
+          machine: 2
+          relations:
+            db: {state: up}
+          state: started
+        wordpress/1:
+          machine: 3
+          relations:
+            db: {state: up}
+          state: started
+
+
+The add-unit command starts a new wordpress instance (wordpress/1), which then
+joins the relation with the already existing mysql/0 instance. mysql/0 notices
+the database required has already been created and thus decides all needed
+configuration has already been done. On the other hand wordpress/1 reads
+service settings from mysql/0 and starts configuring itself and joining the
+juju. Let's review a short version of debug-log for adding wordpress/1::
+
+  14:36:19,755 unit:mysql/0: hook.scheduler DEBUG: executing hook for wordpress/1:joined
+  14:36:19,755 unit:mysql/0: unit.relation.lifecycle DEBUG: Executing hook db-relation-joined
+  14:36:19,810 unit:wordpress/1: hook.scheduler DEBUG: executing hook for mysql/0:joined
+  14:36:19,811 unit:wordpress/1: unit.relation.lifecycle DEBUG: Executing hook db-relation-joined
+  14:36:19,811 unit:wordpress/1: unit.relation.lifecycle DEBUG: Executing hook db-relation-changed
+  14:36:19,918 unit:mysql/0: unit.hook.api WARNING: Database already exists, exiting
+  14:36:19,938 unit:mysql/0: unit.relation.lifecycle DEBUG: Executing hook db-relation-changed
+  14:36:19,990 unit:wordpress/1: unit.hook.api WARNING: Retrieved hostname: ec2-50-16-156-106.compute-1.amazonaws.com
+  14:36:20,757 unit:wordpress/1: unit.hook.api WARNING: Creating appropriate upload paths and directories
+  14:36:20,916 unit:wordpress/1: unit.hook.api WARNING: Writing wordpress config file /etc/wordpress/config-ec2-50-16-156-106.compute-1.amazonaws.com.php
+  14:36:21,088 unit:wordpress/1: unit.hook.api WARNING: Writing apache config file /etc/apache2/sites-available/ec2-50-16-156-106.compute-1.amazonaws.com
+  14:36:21,236 unit:wordpress/1: unit.hook.api WARNING: Enabling apache modules: rewrite, vhost_alias
+  14:36:21,476 unit:wordpress/1: unit.hook.api WARNING: Enabling apache site: ec2-50-16-156-106.compute-1.amazonaws.com
+  14:36:21,682 unit:wordpress/1: unit.hook.api WARNING: Restarting apache2 service
+
+Destroying the environment
+--------------------------
+
+Once you are done with an juju deployment, you need to terminate
+all running instances in order to stop paying for them. The
+destroy-environment command will terminate all running instances in an
+environment::
+
+  $ juju destroy-environment
+
+juju will ask for user confirmation before proceeding as this
+command will destroy service data in the environment as well.

=== added file 'source/write-charm.rst'
--- source/write-charm.rst	1970-01-01 00:00:00 +0000
+++ source/write-charm.rst	2012-01-18 20:50:30 +0000
@@ -0,0 +1,409 @@
+.. _write-charm:
+
+Writing a charm
+===============
+
+This tutorial demonstrates the basic workflow for writing, running and
+debugging an juju charm. Charms are a way to package and share your
+service deployment and orchestration knowledge and share them with the world.
+
+Creating the charm
+--------------------
+
+In this example we are going to write a charm to deploy the drupal CMS
+system. For the sake of simplicity, we are going to use the mysql charm that
+comes bundled with juju in the examples directory. Assuming the current
+directory is the juju trunk, let's create the directory hierarchy::
+
+  $ cd examples/oneiric
+  mkdir -p drupal/hooks
+  vim drupal/metadata.yaml
+  vim drupal/revision
+
+Note: if you don't have the juju source tree available, the `examples` repository
+is installed into `/usr/share/doc/juju`; you can copy the repository to your
+current directory, and work from there.
+
+Edit the metadata.yaml file to resemble::
+
+  name: drupal
+  summary: "Drupal CMS"
+  description: |
+      Installs the drupal CMS system, relates to the mysql charm provided in
+      examples directory. Can be scaled to multiple web servers
+  requires:
+    db:
+      interface: mysql
+
+The metadata.yaml file provides metadata around the charm. The file declares
+a charm with the name drupal. Since this is the first time to edit this
+charm, its revision number is one.  A short and long description of the
+charm are provided. The final field is `requires`, this mentions the
+interface type required by this charm. Since this drupal charm uses the
+services of a mysql database, we need to require it in the metadata. Since this
+charm does not provide a service to any other charm, there is no `provides`
+field. You might be wondering where did the interface name "mysql" come from,
+you can locate the interface information from the mysql charm's
+metadata.yaml.  Here it is for convenience::
+
+  name: mysql
+  summary: "MySQL relational database provider"
+  description: |
+      Installs and configures the MySQL package (mysqldb), then runs it.
+  
+      Upon a consuming service establishing a relation, creates a new
+      database for that service, if the database does not yet
+      exist. Publishes the following relation settings for consuming
+      services:
+  
+        database: database name
+        user: user name to access database
+        password: password to access the database
+        host: local hostname
+  provides:
+    db:
+      interface: mysql
+
+That very last line mentions that the interface that mysql provides to us is
+"mysql". Also the description mentions that four parameters are sent to the
+connecting charm (database, user, password, host) in order to enable it to
+connect to the database. We will make use of those variables once we start
+writing hooks. Such interface information is either provided in a bundled
+README file, or in the description. Of course you can also read the charm
+code to discover such information as well
+
+     Revision is a integer representing the version of the charm. The revision must always be incremented (monotonically increasing) upon changing a charm to allow for charm upgrades.
+
+ $vim revision
+   1
+
+Have a plan
+-----------
+
+When attempting to write a charm, it is beneficial to have a mental plan of
+what it takes to deploy the software. In our case, you should deploy drupal
+manually, understand where its configuration information is written, how the
+first node is deployed, and how further nodes are configured. With respect to
+this charm, this is the plan
+
+  * Install hook installs all needed components (apache, php, drush)
+  * Once the database connection information is ready, call drush on first node
+    to perform the initial setup (creates DB tables, completes setup)
+  * For scaling onto other nodes, the DB tables have already been set-up. Thus
+    we only need to append the database connection information into drupal's
+    settings.php file. We will use a template file for that
+
+.. note::
+  The hooks in a charm are executable files that can be written using any
+  scripting or programming language. In our case, we'll use bash
+
+For production charms it is always recommended that you install software
+components from the Ubuntu archive (using apt-get) in order to get security
+updates. However in this example I am installing drush (Drupal shell) using
+apt-get, then using that to download and install the latest version of drupal.
+If you were deploying your own code, you could just as easily install a
+revision control tool (bzr, git, hg...etc) and use that to checkout a code
+branch to deploy from. This demonstrates the flexibility offered by juju
+which doesn't really force you into one way of doing things.
+
+Write hooks
+-----------
+
+Let's change into the hooks directory::
+
+  $ cd drupal/hooks
+  vim install
+
+Since you should have already installed drupal, you have an idea what it takes
+to get it installed. My install script looks like::
+
+  #!/bin/bash
+  
+  set -eux # -x for verbose logging to juju debug-log
+  juju-log "Installing drush,apache2,php via apt-get"
+  apt-get -y install drush apache2 php5-gd libapache2-mod-php5 php5-cgi mysql-client-core-5.1
+  a2enmod php5
+  /etc/init.d/apache2 restart
+  juju-log "Using drush to download latest Drupal"
+  # Typo on next line, it should be www not ww
+  cd /var/ww && drush dl drupal --drupal-project-rename=juju
+
+I have introduced an artificial typo on the last line "ww not www", this is to
+simulate any error which you are bound to face sooner or later. Let's create
+other hooks::
+
+  $ vim start
+
+The start hook is empty, however it needs to be a valid executable, thus we'll
+add the first bash shebang line, here it is::
+
+  #!/bin/bash
+
+Here's the "stop" script::
+
+  #!/bin/bash
+  juju-log "Stopping apache"
+  /etc/init.d/apache2 stop
+
+The final script, which does most of the work is "db-relation-changed". This
+script gets the database connection information set by the mysql charm then
+sets up drupal for the first time, and opens port 80 for web access. Let's
+start with a simple version that only installs drupal on the first node. Here
+it is::
+
+  #!/bin/bash
+  set -eux # -x for verbose logging to juju debug-log
+  hooksdir=$PWD
+  user=`relation-get user`
+  password=`relation-get password`
+  host=`relation-get host`
+  database=`relation-get database`
+  # All values are set together, so checking on a single value is enough
+  # If $user is not set, DB is still setting itself up, we exit awaiting next run
+  [ -z "$user" ] && exit 0
+  juju-log "Setting up Drupal for the first time"
+  cd /var/www/juju && drush site-install -y standard \
+  --db-url=mysql://$user:$password@$host/$database \
+  --site-name=juju --clean-url=0
+  cd /var/www/juju && chown www-data sites/default/settings.php
+  open-port 80/tcp
+
+The script is quite simple, it reads the four variables needed to connect to
+mysql, ensures they are not null, then passes them to the drupal installer.
+Make sure all the hook scripts have executable permissions, and change
+directory above the examples directory::
+
+  $ chmod +x *
+  $ cd ../../../..
+
+Checking on the drupal charm file-structure, this is what we have::
+
+  $ find examples/oneiric/drupal
+  examples/oneiric/drupal
+  examples/oneiric/drupal/metadata.yaml
+  examples/oneiric/drupal/revision
+  examples/oneiric/drupal/hooks
+  examples/oneiric/drupal/hooks/db-relation-changed
+  examples/oneiric/drupal/hooks/stop
+  examples/oneiric/drupal/hooks/install
+  examples/oneiric/drupal/hooks/start
+
+Test run
+--------
+
+Let us deploy the drupal charm. Remember that the install hook has a problem
+and will not exit cleanly. Deploying::
+
+  $ juju bootstrap
+
+Wait a minute for the environment to bootstrap. Keep issuing the status command
+till you know the environment is ready::
+
+  $ juju status 
+  2011-06-07 14:04:06,816 INFO Connecting to environment.
+  machines: 0: {dns-name: ec2-50-19-154-237.compute-1.amazonaws.com, instance-id: i-6fb52301}
+  services: {}
+  2011-06-07 14:04:11,125 INFO 'status' command finished successfully
+
+It can be beneficial when debugging a new charm to always have the
+distributed debug-log running in a separate window::
+
+  $ juju debug-log
+
+Let's deploy the mysql and drupal charms::
+
+  $ juju deploy --repository=examples local:oneiric/mysql
+  $ juju deploy --repository=examples local:oneiric/drupal
+
+Once the machines are started (hint: check the debug-log), issue a status
+command::
+
+  $ juju status
+  machines:
+    0: {dns-name: ec2-50-19-154-237.compute-1.amazonaws.com, instance-id: i-6fb52301}
+    1: {dns-name: ec2-50-16-9-102.compute-1.amazonaws.com, instance-id: i-19b12777}
+    2: {dns-name: ec2-50-17-147-79.compute-1.amazonaws.com, instance-id: i-e7ba2c89}
+  services:
+    drupal:
+      charm: local:oneiric/drupal-1
+      relations: {}
+      units:
+        drupal/1:
+          machine: 4
+          open-ports: []
+          relations: {}
+          state: install_error
+    mysql:
+      charm: local:oneiric/mysql-12
+      relations: {}
+      units:
+        mysql/0:
+          machine: 1
+          relations: {}
+          state: started
+
+Note how mysql is listed as started, while drupal's state is install_error. This is
+because the install hook has an error, and did not exit cleanly (exit code 1).
+
+Debugging hooks
+---------------
+
+Let's debug the install hook, from a new window::
+
+  $ juju debug-hooks drupal/0
+
+This will connect you to the drupal machine, and present a shell. The way the
+debug-hooks functionality works is by starting a new terminal window instead of
+executing a hook when it is triggered. This way you get a chance of running the
+hook manually, fixing any errors and re-running it again. In order to trigger
+re-running the install hook, from another window::
+
+  $ juju resolved --retry drupal/0
+
+Switching to the debug-hooks window, you will notice a new window named
+"install" poped up. Note that "install" is the name of the hook that this
+debug-hooks session is replacing. We change directory into the hooks directory
+and rerun the hook manually::
+
+  $ cd /var/lib/juju/units/drupal-0/charm/hooks/
+  $ ./install
+  # -- snip --
+  + cd /var/ww
+  ./install: line 10: cd: /var/ww: No such file or directory
+
+Problem identified. Let's edit the script, changing ww into www. Rerunning it
+again should work successfully. This is why it is very good practice to write
+hook scripts in an idempotent manner such that rerunning them over and over
+always results in the same state. Do not forget to exit the install window by
+typing "exit", this signals that the hook has finished executing successfully.
+If you have finished debugging, you may want to exit the debug-hooks session
+completely by typing "exit" into the very first window Window0
+
+.. note::
+  While we have fixed the script, this was done on the remote machine only. You
+  need to update the local copy of the charm with your changes, increment the
+  resivion number in metadata.yaml and perform a charm upgrade to push the
+  changes, like::
+
+  $ juju upgrade-charm --repository=examples/ drupal
+
+Let's continue after having fixed the install error::
+
+  $ juju add-relation mysql drupal
+
+Watching the debug-log window, you can see debugging information to verify the
+hooks are working as they should. If you spot any error, you can launch
+debug-hooks in another window to start debugging the misbehaving hooks again.
+Note that since "add-relation" relates two charms together, you cannot really
+retrigger it by simply issuing "resolved --retry" like we did for the install
+hook. In order to retrigger the db-relation-changed hook, you need to remove
+the relation, and create it again like so::
+
+  $ juju remove-relation mysql drupal
+  $ juju add-relation mysql drupal
+
+The service should now be ready for use. The remaining step is to expose it to
+public access. While the charm signaled it needs port 80 to be open, for
+public accessibility, the port is not open until the administrator explicitly
+uses the expose command::
+
+  $ juju expose drupal
+
+Let's see a status with the ports exposed::
+
+  $ juju status
+  machines:
+    0: {dns-name: ec2-50-19-154-237.compute-1.amazonaws.com, instance-id: i-6fb52301}
+    1: {dns-name: ec2-50-16-9-102.compute-1.amazonaws.com, instance-id: i-19b12777}
+    2: {dns-name: ec2-50-17-147-79.compute-1.amazonaws.com, instance-id: i-e7ba2c89}
+  services:
+    drupal:
+      exposed: true
+      charm: local:oneiric/drupal-1
+      relations: {db: mysql}
+      units:
+        drupal/1:
+          machine: 4
+          open-ports: [80/tcp]
+          relations:
+            db: {state: up}
+          state: started
+    mysql:
+      charm: local:oneiric/mysql-12
+      relations: {db: drupal}
+      units:
+        mysql/0:
+          machine: 1
+          relations:
+            db: {state: up}
+          state: started
+
+
+Congratulations, your charm should now be working successfully! The
+db-relation-changed hook previously shown is not suitable for scaling drupal to
+more than one node, since it always drops the database and recreates a new one.
+A more complete hook would need to first check whether or not the DB tables
+exist and act accordingly. Here is how such a hook might be written::
+
+  #!/bin/bash
+  set -eux # -x for verbose logging to juju debug-log
+  hooksdir=$PWD
+  user=`relation-get user`
+  password=`relation-get password`
+  host=`relation-get host`
+  database=`relation-get database`
+  # All values are set together, so checking on a single value is enough
+  # If $user is not set, DB is still setting itself up, we exit awaiting next run
+  [ -z "$user" ] && exit 0
+  
+  if $(mysql -u $user --password=$password -h $host -e 'use drupal; show tables;' | grep -q users); then
+      juju-log "Drupal already set-up. Adding DB info to configuration"
+      cd /var/www/juju/sites/default
+      cp default.settings.php settings.php
+      sed -e "s/USER/$user/" \
+      -e "s/PASSWORD/$password/" \
+      -e "s/HOST/$host/" \
+      -e "s/DATABASE/$database/" \
+      $hooksdir/drupal-settings.template >> settings.php
+  else
+      juju-log "Setting up Drupal for the first time"
+      cd /var/www/juju && drush site-install -y standard \
+      --db-url=mysql://$user:$password@$host/$database \
+      --site-name=juju --clean-url=0
+  fi
+  cd /var/www/juju && chown www-data sites/default/settings.php
+  open-port 80/tcp
+
+.. note::
+  Any files that you store in the hooks directory are transported as is to the
+  deployment machine. You can drop in configuration files or templates that you
+  can use from your hook scripts. An example of this technique is the
+  drupal-settings.template file that is used in the previous hook. The template
+  is rendered using sed, however any other more advanced template engine can be
+  used
+
+Here is the template file used::
+
+  $databases = array (
+    'default' =>
+    array (
+      'default' =>
+      array (
+        'database' => 'DATABASE',
+        'username' => 'USER',
+        'password' => 'PASSWORD',
+        'host' => 'HOST',
+        'port' => '',
+        'driver' => 'mysql',
+        'prefix' => '',
+      ),
+    ),
+  );
+
+Learn more
+----------
+
+Read more detailed information about :doc:`charm` and hooks. For more hook
+examples, please check the examples directory in the juju source tree, or
+check out the various charms already included in `Principia
+<https://launchpad.net/principia>`_.