Merge lp:~frankban/juju-quickstart/enable-env-management into lp:juju-quickstart

[Francesco Banconi]

Integrate the env management functionality.

This branch enables the environment management
Urwid interactive session feature in quickstart,
but also includes some other improvements, described
below.

Exposed a way to let the user quickly
create and bootstrap a local env if no environments
are already configured. This is implemented
adding a closure (create_and_start_local_env) to the
env_index view: this could have been implemented
as a separate function as well (more easily testable,
less surprising), but I decided to stick with the
pattern used by the other views for now.

Changed the env_edit view so that the first created
environment is automatically set as default.

Renamed manage._validate_env to manage._setup_env:
the function now does a lot more than validation, e.g.
it lunches the interactive session, handles the
case when the Juju home is not yet configured, etc.
This function also sets up a save_callable to be used
by views. I could have used partial to create such a
function, but I decided to implement a HO
_create_save_callable that can be easily be extended
later in order to enable the backup functionality.

Bumped version up.

The diff is very long, my apologies, but you can safely
ignore deleted code:
- the demo application, no longer required;
- the ensure_environments function + its tests;
- envs.parse_env_file + its tests (
  replaced by envs.load + envs.validate).
Moreover, the env_type_db definition in
quickstart.models.envs is just a copy/paste replacement
of the original one: the only difference is that
an ordered dict is used in place of the usual dict.
This change has been introduced so that views
can list the supported environment types in the order
they are defined.

Tests: `make check`.

QA: if you have time, given the amount of code
enabled by this branch, and given the differences
in each one Juju configuration, I'd appreciate both
reviewers to QA the interactive session.
The instructions follow, thank you very much!

- Run `make`.

- Backup your Juju home:
  `mv ~/.juju ~/juju-home-backup`
  This way we can simulate Juju is not configured at all.

- Run `.venv/bin/python juju-quickstart`.
  Quickstart should welcome you and propose, among
  other things, to automatically create and bootstrap
  a local environment. Do that, provide your sudo
  password if requested, wait until the process completes
  and the GUI opens in your default browser as usual.
  This can take several minutes based on the sanity of your
  LXC configuration. Before opening the browser, you should
  see instructions on re-running quickstart to reopen
  and log in to the GUI later or restarting the interactive
  session. Also note that an admin password has been
  automatically generated and printed to stdout.

- Run `.venv/bin/python juju-quickstart`.
  This time no interactive session is started, the application
  recognizes the environment is already bootstrapped and
  quickly reopens the browser and logs in to the GUI.

- Run `cat ~/.juju/environments.yaml`.
  Check the generated environment file looks sane.

- Destroy the local environment:
  `sudo juju destroy-environment -e local -y`

- Run `.venv/bin/python juju-quickstart -i`.
  The interactive session should start and this time
  it should list your existing environment.
  Let's customize the local one: click on it, then
  on the "edit" button, and then use the form
  to change its name (e.g. replace "local" with "lxc").
  Hit page-down and click "save" an then "back" to
  return to the index view.
  Now let's create an ec2 environment by selecting
  "new ec2 environment". Call it "aws", auto-generate
  the admin-secret and the control-bucket, fill in your
  ec2 credentials and save the new environment.
  Also make it the default one, either by using the
  checkbox in the form or by clicking "set default"
  from the env details view. From the envs detail view,
  let's go ahead and bootstrap the "aws" env by clicking "use".
  As above, wait for the ec2 environment to be bootstrapped
  and the GUI opened. In the meanwhile, you can run
  `cat ~/.juju/environments.yaml` in another terminal to
  ensure the env file looks good. Note that at this time
  no backup files are created: this is the goal of my next card.

- Run `juju switch` to check that the default environment
  is now "aws".

- Check that command line options validation still work: all the
  following command should exit with pertinent errors:

  .venv/bin/python juju-quickstart --gui-charm-url invalid

  .venv/bin/python juju-quickstart --gui-charm-url http:~juju-gui/precise/juju-gui-80

  .venv/bin/python juju-quickstart --gui-charm-url cs:precise/juju-gui-1 bundle:~jorge/mediawiki-simple/4/mediawiki-simple

  .venv/bin/python juju-quickstart --gui-charm-url cs:saucy/juju-gui-80

  .venv/bin/python juju-quickstart -e no-such

  .venv/bin/python juju-quickstart /no-such-bundle

  .venv/bin/python juju-quickstart bundle:~jorge/mediawiki-simple/4/no-such

- Let's also try to deploy a bundle:
  run `juju unexpose juju-gui` and then
  `.venv/bin/python juju-quickstart bundle:~jorge/mediawiki-simple/4/mediawiki-simple`.
  The service should be re-exposed by quickstart and the bundle
  deployment should start as usual.

- Destroy the ec2 environment: `juju destroy-environment -e aws -y`.

- Restore your existing juju home:
  `rm -rf ~/.juju && mv ~/juju-home-backup .juju`.

- Create a backup copy of your environments file:
  `cp ~/.juju/environments.yaml ~/environments.yaml.bak`.

- Not it's time to be creative. Run quickstart in interactive
  mode (`.venv/bin/python juju-quickstart -i`): you should
  see your environments listed.
  Start changing/removing/creating/bootstrapping your
  environments. Remove required fields, exit without editing
  to check your environments file is not saved by quickstart
  if not necessary, try to create two envs with the same name.
  In a sentence: try hard to break the application in any
  way you can imagine.

- Once done, restore your original environments file:
  `mv ~/environments.yaml.bak ~/.juju/environments.yaml`.

- Remember to destroy all the environments you
  bootstrapped.

Done! Many thanks for going through all these QA steps.

https://codereview.appspot.com/50430043/

[Francesco Banconi (frankban)]

Reviewers: mp+201163_code.launchpad.net,

Message:
Please take a look.

Description:
Integrate the env management functionality.

This branch enables the environment management
Urwid interactive session feature in quickstart,
but also includes some other improvements, described
below.

Exposed a way to let the user quickly
create and bootstrap a local env if no environments
are already configured. This is implemented
adding a closure (create_and_start_local_env) to the
env_index view: this could have been implemented
as a separate function as well (more easily testable,
less surprising), but I decided to stick with the
pattern used by the other views for now.

Changed the env_edit view so that the first created
environment is automatically set as default.

Renamed manage._validate_env to manage._setup_env:
the function now does a lot more than validation, e.g.
it lunches the interactive session, handles the
case when the Juju home is not yet configured, etc.
This function also sets up a save_callable to be used
by views. I could have used partial to create such a
function, but I decided to implement a HO
_create_save_callable that can be easily be extended
later in order to enable the backup functionality.

Bumped version up.

The diff is very long, my apologies, but you can safely
ignore deleted code:
- the demo application, no longer required;
- the ensure_environments function + its tests;
- envs.parse_env_file + its tests (
   replaced by envs.load + envs.validate).
Moreover, the env_type_db definition in
quickstart.models.envs is just a copy/paste replacement
of the original one: the only difference is that
an ordered dict is used in place of the usual dict.
This change has been introduced so that views
can list the supported environment types in the order
they are defined.

Tests: `make check`.

QA: if you have time, given the amount of code
enabled by this branch, and given the differences
in each one Juju configuration, I'd appreciate both
reviewers to QA the interactive session.
The instructions follow, thank you very much!

- Run `make`.

- Backup your Juju home:
   `mv ~/.juju ~/juju-home-backup`
   This way we can simulate Juju is not configured at all.

- Run `.venv/bin/python juju-quickstart`.
   Quickstart should welcome you and propose, among
   other things, to automatically create and bootstrap
   a local environment. Do that, provide your sudo
   password if requested, wait until the process completes
   and the GUI opens in your default browser as usual.
   This can take several minutes based on the sanity of your
   LXC configuration. Before opening the browser, you should
   see instructions on re-running quickstart to reopen
   and log in to the GUI later or restarting the interactive
   session. Also note that an admin password has been
   automatically generated and printed to stdout.

- Run `.venv/bin/python juju-quickstart`.
   This time no interactive session is started, the application
   recognizes the environment is already bootstrapped and
   quickly reopens the browser and logs in to the GUI.

- Run `cat ~/.juju/environments.yaml`.
   Check the generated environment file looks sane.

- Destroy the local enviro...

[Benji York (benji)]

LGTM with one tiny suggestion.

https://codereview.appspot.com/50430043/diff/1/quickstart/manage.py
File quickstart/manage.py (right):

https://codereview.appspot.com/50430043/diff/1/quickstart/manage.py#newcode211
quickstart/manage.py:211: options.interactive = interactive
This function has gotten a bit big. I wonder if a nice refactoring
would be one that made this function contain no conditionals but instead
called four or five subfunctions.

https://codereview.appspot.com/50430043/

[Richard Harding (rharding)]

code looks good, will start QA.

https://codereview.appspot.com/50430043/

[Richard Harding (rharding)]

QA ok, LGTM

It was cool to use it in interactive mode against my original
environments.yaml file. The only issue from a user POV was I was looking
for some command to save/write the changes made. When I ended up just
quitting I saw the output

changes to the environments file have been saved

but it'd be nice to have some sort of feedback or specific 'save'
command in the UI.

https://codereview.appspot.com/50430043/

[lp:~frankban/juju-quickstart/enable-env-management]

57. By Francesco Banconi on 2014-01-13

Changes as per review.

[Francesco Banconi (frankban)]

*** Submitted:

Integrate the env management functionality.

This branch enables the environment management
Urwid interactive session feature in quickstart,
but also includes some other improvements, described
below.

Exposed a way to let the user quickly
create and bootstrap a local env if no environments
are already configured. This is implemented
adding a closure (create_and_start_local_env) to the
env_index view: this could have been implemented
as a separate function as well (more easily testable,
less surprising), but I decided to stick with the
pattern used by the other views for now.

Changed the env_edit view so that the first created
environment is automatically set as default.

Renamed manage._validate_env to manage._setup_env:
the function now does a lot more than validation, e.g.
it lunches the interactive session, handles the
case when the Juju home is not yet configured, etc.
This function also sets up a save_callable to be used
by views. I could have used partial to create such a
function, but I decided to implement a HO
_create_save_callable that can be easily be extended
later in order to enable the backup functionality.

Bumped version up.

The diff is very long, my apologies, but you can safely
ignore deleted code:
- the demo application, no longer required;
- the ensure_environments function + its tests;
- envs.parse_env_file + its tests (
   replaced by envs.load + envs.validate).
Moreover, the env_type_db definition in
quickstart.models.envs is just a copy/paste replacement
of the original one: the only difference is that
an ordered dict is used in place of the usual dict.
This change has been introduced so that views
can list the supported environment types in the order
they are defined.

Tests: `make check`.

QA: if you have time, given the amount of code
enabled by this branch, and given the differences
in each one Juju configuration, I'd appreciate both
reviewers to QA the interactive session.
The instructions follow, thank you very much!

- Run `make`.

- Backup your Juju home:
   `mv ~/.juju ~/juju-home-backup`
   This way we can simulate Juju is not configured at all.

- Run `.venv/bin/python juju-quickstart`.
   Quickstart should welcome you and propose, among
   other things, to automatically create and bootstrap
   a local environment. Do that, provide your sudo
   password if requested, wait until the process completes
   and the GUI opens in your default browser as usual.
   This can take several minutes based on the sanity of your
   LXC configuration. Before opening the browser, you should
   see instructions on re-running quickstart to reopen
   and log in to the GUI later or restarting the interactive
   session. Also note that an admin password has been
   automatically generated and printed to stdout.

- Run `.venv/bin/python juju-quickstart`.
   This time no interactive session is started, the application
   recognizes the environment is already bootstrapped and
   quickly reopens the browser and logs in to the GUI.

- Run `cat ~/.juju/environments.yaml`.
   Check the generated environment file looks sane.

- Destroy the local environment:
   `sudo juju destroy-environment -e local -y`

- Run `.venv/b...

[Francesco Banconi (frankban)]

On 2014/01/10 18:05:45, benji1 wrote:
> LGTM with one tiny suggestion.

> https://codereview.appspot.com/50430043/diff/1/quickstart/manage.py
> File quickstart/manage.py (right):

https://codereview.appspot.com/50430043/diff/1/quickstart/manage.py#newcode211
> quickstart/manage.py:211: options.interactive = interactive
> This function has gotten a bit big. I wonder if a nice refactoring
would be one
> that made this function contain no conditionals but instead called
four or five
> subfunctions.

Done. Thank you both!

https://codereview.appspot.com/50430043/

=== removed file 'cli-app-demo.py'
--- cli-app-demo.py	2013-12-19 10:04:19 +0000
+++ cli-app-demo.py	1970-01-01 00:00:00 +0000
@@ -1,57 +0,0 @@
-#!.venv/bin/python
-
-# This file is part of the Juju Quickstart Plugin, which lets users set up a
-# Juju environment in very few steps (https://launchpad.net/juju-quickstart).
-# Copyright (C) 2013 Canonical Ltd.
-#
-# This program is free software: you can redistribute it and/or modify it under
-# the terms of the GNU Affero General Public License version 3, as published by
-# the Free Software Foundation.
-#
-# This program is distributed in the hope that it will be useful, but WITHOUT
-# ANY WARRANTY; without even the implied warranties of MERCHANTABILITY,
-# SATISFACTORY QUALITY, or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
-# Affero General Public License for more details.
-#
-# You should have received a copy of the GNU Affero General Public License
-# along with this program.  If not, see <http://www.gnu.org/licenses/>.
-
-"""Juju Quickstart CLI application demo."""
-
-# XXX frankban (2013-12-16): this file is only for demonstration/QA purposes.
-# Remove this file when the environment management integration is completed.
-# Run "make" before running this file.
-
-from __future__ import (
-    print_function,
-    unicode_literals,
-)
-
-import pprint
-
-from quickstart.cli import views
-from quickstart.models import envs
-from quickstart.tests import helpers
-
-
-def main():
-    """Start the Quickstart environments list view."""
-    env_type_db = envs.get_env_type_db()
-    # This simulates an env database as returned by envs.load().
-    env_db = helpers.make_env_db(default='lxc')
-    save_callable = lambda db: None
-    # Show the view.
-    new_env_db, env_data = views.show(
-        views.env_index, env_type_db, env_db, save_callable)
-    if new_env_db != env_db:
-        print('saved a new env db')
-        pprint.pprint(new_env_db)
-    print('default: {}'.format(new_env_db.get('default')))
-    if env_data is None:
-        print('no environment selected')
-    else:
-        print('selected: {}'.format(env_data['name']))
-
-
-if __name__ == '__main__':
-    main()

=== modified file 'quickstart/__init__.py'
--- quickstart/__init__.py	2013-12-06 10:07:40 +0000
+++ quickstart/__init__.py	2014-01-13 15:31:13 +0000
@@ -22,7 +22,7 @@
 from __future__ import unicode_literals
 
 
-VERSION = (0, 5, 0)
+VERSION = (0, 6, 0)
 
 
 def get_version():

=== modified file 'quickstart/app.py'
--- quickstart/app.py	2014-01-03 11:38:43 +0000
+++ quickstart/app.py	2014-01-13 15:31:13 +0000
@@ -208,25 +208,6 @@
     print('a new ssh key was generated in {}'.format(key_file))
 
 
-def ensure_environments():
-    """Ensure that the environments file exists.
-
-    Return the env_name argument unchanged if the environment file exists;
-    however, since the other environment types require additional work to
-    set up, return 'local' if juju init is run.
-    """
-    print('environments file not found; running juju init')
-    retcode, _, error = utils.call('juju', 'init')
-    if retcode:
-        raise ProgramExit(error)
-    print('defaulting to local environment for a new environments file')
-    env_name = 'local'
-    retcode, _, error = utils.call('juju', 'switch', env_name)
-    if retcode:
-        raise ProgramExit(error)
-    return env_name
-
-
 def bootstrap(env_name, is_local=False, debug=False):
     """Bootstrap the Juju environment with the given name.
 

=== modified file 'quickstart/cli/views.py'
--- quickstart/cli/views.py	2014-01-07 15:53:57 +0000
+++ quickstart/cli/views.py	2014-01-13 15:31:13 +0000
@@ -156,13 +156,50 @@
         envs.get_env_data(env_db, env_name)
         for env_name in env_db['environments']
     ], key=operator.itemgetter('name'))
+
+    def create_and_start_local_env():
+        # Automatically create and use a local environment named "local".
+        # This closure can only be called when there are no environments in the
+        # database. For this reason, the new environment is set as default.
+        # Exit the interactive session selecting the newly created environment.
+        env_data = envs.create_local_env_data(
+            env_type_db, 'local', is_default=True)
+        # Add the new environment to the environments database.
+        envs.set_env_data(env_db, None, env_data)
+        save_callable(env_db)
+        # Use the newly created environment.
+        raise ui.AppExit((env_db, env_data))
+
     if environments:
         title = 'Select an existing Juju environment or create a new one'
+        widgets = []
     else:
         title = 'No Juju environments already set up: please create one'
+        widgets = [
+            urwid.Text([
+                ('highlight', 'Welcome to Juju Quickstart!'),
+                '\nYou can use this interactive session to manage your Juju '
+                'environments.\nInteractive mode has been automatically '
+                'started because no environments have been found. After '
+                'creating your first environment you can start Juju '
+                'Quickstart in interactive mode again by passing the -i flag, '
+                'e.g.:\n',
+                ('highlight', '$ juju quickstart -i'),
+                '\n\nAt the bottom of the page you can find links to manually '
+                'create new environments. If you instead prefer to quickly '
+                'start your Juju experience in a local environment (LXC), '
+                'just click the link below:'
+            ]),
+            ui.MenuButton(
+                '\N{BULLET} automatically create and bootstrap a local '
+                'environment', ui.thunk(create_and_start_local_env)),
+        ]
     app.set_title(title)
     # Start creating the page contents: a list of selectable environments.
-    widgets = []
+    # Wouldn't it be nice if we were able to highlight in some way the
+    # currently running environments? Unfortunately this requires calling
+    # "juju status" for each environment in the list, which is expensive and
+    # time consuming.
     focus_position = None
     errors_found = default_found = False
     for position, env_data in enumerate(environments):
@@ -376,6 +413,9 @@
         # Without errors, normalize the new values, update the env_db and save
         # the resulting environments database.
         env_data = envs.normalize(env_metadata, new_env_data)
+        # If this is the only environment in the db, set it as the default one.
+        if not env_db['environments']:
+            env_data['is-default'] = True
         envs.set_env_data(env_db, initial_name, env_data)
         save_callable(env_db)
         verb = 'modified' if exists else 'created'

=== modified file 'quickstart/manage.py'
--- quickstart/manage.py	2014-01-03 11:38:43 +0000
+++ quickstart/manage.py	2014-01-13 15:31:13 +0000
@@ -34,6 +34,7 @@
     settings,
     utils,
 )
+from quickstart.cli import views
 from quickstart.models import (
     charms,
     envs,
@@ -134,35 +135,124 @@
             'revision: {}'.format(charm))
 
 
-def _validate_env(options, parser):
-    """Validate and process the provided environment related options.
+def _retrieve_env_db(parser, env_file=None):
+    """Retrieve the environment database (or create an in-memory empty one)."""
+    if env_file is None:
+        return envs.create_empty_env_db()
+    try:
+        return envs.load(env_file)
+    except ValueError as err:
+        return parser.error(bytes(err))
+
+
+def _create_save_callable(parser, env_file):
+    """Return a function that can be used to save an env_db to the env_file.
+
+    The returned function is used as save_callable by the environments
+    management views.
+
+    The resulting function uses the given parser instance to exit the
+    application with an error if an OSError exception is raised while saving
+    the environments database.
+    """
+    def save_callable(env_db):
+        try:
+            envs.save(env_file, env_db)
+        except OSError as err:
+            return parser.error(bytes(err))
+
+    return save_callable
+
+
+def _start_interactive_session(parser, env_type_db, env_db, env_file):
+    """Start the Urwid interactive session.
+
+    Return the env_data corresponding to the user selected environment.
+    Exit the application if the user exits the interactive session without
+    selecting an environment to start.
+    """
+    save_callable = _create_save_callable(parser, env_file)
+    new_env_db, env_data = views.show(
+        views.env_index, env_type_db, env_db, save_callable)
+    if new_env_db != env_db:
+        print('changes to the environments file have been saved')
+    if env_data is None:
+        # The user exited the interactive session without selecting an
+        # environment to start: this means this was just an environment
+        # editing session and we can just quit now.
+        return sys.exit('quitting')
+    return env_data
+
+
+def _retrieve_env_data(parser, env_type_db, env_db, env_name):
+    """Retrieve and return the env_data corresponding to the given env_name.
+
+    Invoke a parser error if the environment does not exist or is not valid.
+    """
+    try:
+        env_data = envs.get_env_data(env_db, env_name)
+    except ValueError as err:
+        # The specified environment does not exist.
+        return parser.error(bytes(err))
+    env_metadata = envs.get_env_metadata(env_type_db, env_data)
+    errors = envs.validate(env_metadata, env_data)
+    if errors:
+        msg = 'cannot use the {} environment:\n{}'.format(
+            env_name, '\n'.join(errors.values()))
+        return parser.error(msg.encode('utf-8'))
+    return env_data
+
+
+def _setup_env(options, parser):
+    """Set up, validate and process the provided environment related options.
+
+    Also start the environments management interactive session if required.
 
     Exit with an error if options are not valid.
     """
-    logging.debug('ensuring juju environments available')
+    logging.debug('setting up juju environments')
+    env_name = options.env_name
     env_file = os.path.abspath(os.path.expanduser(options.env_file))
+    interactive = options.interactive
+    env_file_exists = os.path.exists(env_file)
+    if not env_file_exists:
+        # If the Juju home is not set up, force the interactive mode and ignore
+        # the user provided env name.
+        interactive = True
+        env_name = None
     # Validate the environment name.
-    env_name = options.env_name
-    if env_name is None:
+    if env_name is None and not interactive:
+        # The user forced non-interactive mode but a default env name cannot
+        # be retrieved. In this case, just exit with an error.
         return parser.error(
             'unable to find an environment name to use\n'
-            'It is possible to specify the environment name by either:\n'
+            'It is possible to specify the environment to use by either:\n'
+            '  - selecting one from the quickstart interactive session,\n'
+            '    i.e. juju quickstart -i;\n'
             '  - passing the -e or --environment argument;\n'
             '  - setting the JUJU_ENV environment variable;\n'
             '  - using "juju switch" to select the default environment;\n'
             '  - setting the default environment in {}.'.format(env_file)
         )
-    # Validate the environment file.
-    try:
-        env_type, admin_secret, default_series = (
-            envs.parse_env_file(env_file, env_name))
-    except ValueError as err:
-        return parser.error(bytes(err))
+    # Retrieve the environment database (or create an in-memory empty one).
+    env_db = _retrieve_env_db(parser, env_file if env_file_exists else None)
+    # Validate the environment.
+    env_type_db = envs.get_env_type_db()
+    if interactive:
+        # Start the interactive session.
+        env_data = _start_interactive_session(
+            parser, env_type_db, env_db, env_file)
+    else:
+        # This is a non-interactive session and we need to validate the
+        # selected environment before proceeding.
+        env_data = _retrieve_env_data(parser, env_type_db, env_db, env_name)
     # Update the options namespace with the new values.
-    options.admin_secret = admin_secret
+    options.admin_secret = env_data['admin-secret']
     options.env_file = env_file
-    options.env_type = env_type
-    options.default_series = default_series
+    options.env_name = env_data['name']
+    options.env_type = env_data['type']
+    options.default_series = env_data.get('default-series')
+    options.interactive = interactive
 
 
 def _configure_logging(level):
@@ -204,6 +294,7 @@
         - env_file: the absolute path of the Juju environments.yaml file;
         - env_name: the name of the Juju environment to use;
         - env_type: the provider type of the selected Juju environment;
+        - interactive: whether to start the interactive session;
         - open_browser: whether the GUI browser must be opened.
 
     The following attributes will also be included in the namespace if a bundle
@@ -219,11 +310,6 @@
     default_env_name = envs.get_default_env_name()
     # Define the help message for the --environment option.
     env_help = 'The name of the Juju environment to use'
-    # XXX 2013-12-02 makyo:
-        # ensure_environments will be removed with more robust environment
-        # management code in the next few weeks.
-    if default_env_name is None:
-        default_env_name = app.ensure_environments()
     if default_env_name is not None:
         env_help = '{} (%(default)s)'.format(env_help)
     # Create and set up the arguments parser.
@@ -245,6 +331,9 @@
              'required if the bundle YAML/JSON only contains one bundle. This '
              'option is ignored if the bundle file is not specified')
     parser.add_argument(
+        '-i', '--interactive', action='store_true', dest='interactive',
+        help='Start the environments management interactive session')
+    parser.add_argument(
         '--environments-file', dest='env_file',
         default=os.path.join(settings.JUJU_HOME, 'environments.yaml'),
         help='The path to the Juju environments YAML file (%(default)s)')
@@ -274,7 +363,7 @@
     # Convert the provided string arguments to unicode.
     _convert_options_to_unicode(options)
     # Validate and process the provided arguments.
-    _validate_env(options, parser)
+    _setup_env(options, parser)
     if options.bundle is not None:
         _validate_bundle(options, parser)
     if options.charm_url is not None:
@@ -336,4 +425,11 @@
             url += '/?authtoken={}'.format(token)
         webbrowser.open(url)
     gui_env.close()
-    print('done!')
+    print(
+        'done!\n\n'
+        'Run "juju quickstart -e {}" again if you want\n'
+        'to reopen and log in to the GUI browser later.\n'
+        'Run "juju quickstart -i" if you want to manage\n'
+        'or bootstrap your Juju environments using the\n'
+        'interactive session.'.format(options.env_name)
+    )

=== modified file 'quickstart/models/envs.py'
--- quickstart/models/envs.py	2014-01-07 15:41:55 +0000
+++ quickstart/models/envs.py	2014-01-13 15:31:13 +0000
@@ -74,9 +74,6 @@
 The set_env_data function, as seen above, needs to be passed the original name
 of the environment being modified. If None is passed, that means we are adding
 a new environment.
-
-XXX frankban 13-12-08: remove the parse_env_file function: this can be done
-    when activating models code in manage.py.
 """
 
 from __future__ import unicode_literals
@@ -129,6 +126,11 @@
         return match.groups()[0]
 
 
+def create_empty_env_db():
+    """Create and return an empty environments database."""
+    return {'environments': {}}
+
+
 def load(env_file):
     """Load and parse the provided Juju environments.yaml file.
 
@@ -164,6 +166,8 @@
     except Exception as err:
         msg = b'unable to parse environments file {}: {}'
         raise ValueError(msg.format(env_file.encode('utf-8'), err))
+    if contents is None:
+        return create_empty_env_db()
     # Retrieve the environment list.
     try:
         env_contents = contents.get('environments', {}).items()
@@ -181,7 +185,7 @@
     default = contents.get('default')
     if default in environments:
         env_db['default'] = default
-    else:
+    elif default is not None:
         logging.warn('excluding invalid default {}'.format(default))
     return env_db
 
@@ -198,6 +202,7 @@
     # and destination files are on different file systems, use for the
     # temporary file the same directory where the env_file is stored.
     dirname = os.path.dirname(env_file)
+    utils.mkdir(dirname)
     banner = utils.get_quickstart_banner()
     try:
         temp_file = tempfile.NamedTemporaryFile(
@@ -245,7 +250,8 @@
     try:
         info = env_db['environments'][env_name]
     except KeyError:
-        raise ValueError(b'environment {!r} not found'.format(env_name))
+        msg = 'environment {} not found'.format(env_name)
+        raise ValueError(msg.encode('utf-8'))
     # Why not just use env_data.copy()? Because this way internal mutable data
     # structures are preserved, even if they are unlikely to be found.
     env_data = copy.deepcopy(info)
@@ -296,6 +302,25 @@
         del env_db['default']
 
 
+def create_local_env_data(env_type_db, name, is_default=False):
+    """Create and return an local (LXC) env_data.
+
+    Local environments' fields (except for name and type) are assumed to be
+    either optional or suitable for automatic generation of their values. For
+    this reason local environments can be safely created given just their name.
+    """
+    env_data = {'type': 'local', 'name': name, 'is-default': is_default}
+    env_metadata = get_env_metadata(env_type_db, env_data)
+    # Retrieve a list of missing required fields.
+    missing_fields = [
+        field for field in env_metadata['fields']
+        if field.required and field.name not in env_data
+    ]
+    # Assume all missing fields can be automatically generated.
+    env_data.update((field.name, field.generate()) for field in missing_fields)
+    return env_data
+
+
 def remove_env(env_db, env_name):
     """Remove the environment named env_name from the environments database.
 
@@ -347,80 +372,9 @@
     )
     # Define the env_type_db dictionary: this is done inside this function in
     # order to avoid instantiating fields at import time.
-    env_type_db = {
-        'ec2': {
-            'description': (
-                'The ec2 provider enable you to run Juju on the EC2 cloud. '
-                'This process requires you to have an Amazon Web Services '
-                '(AWS) account. If you have not signed up for one yet, it '
-                'can obtained at http://aws.amazon.com. '
-                'See https://juju.ubuntu.com/docs/config-aws.html for more '
-                'details on the ec2 provider configuration.'
-            ),
-            'fields': (
-                provider_field,
-                name_field,
-                admin_secret_field,
-                default_series_field,
-                fields.PasswordField(
-                    'access-key', label='access key', required=True,
-                    help='The access key to use to authenticate to AWS. '
-                         'You can retrieve these values easily from your AWS '
-                         'Management Console (http://console.aws.amazon.com). '
-                         'Click on your name in the top-right and then the '
-                         '"Security Credentials" link from the drop down '
-                         'menu. Under the "Access Keys" heading click the '
-                         '"Create New Root Key" button. You will be prompted '
-                         'to "Download Key File" which by default is named '
-                         'rootkey.csv. Open this file to get the access-key '
-                         'and secret-key for the environments.yaml '
-                         'configuration file.'),
-                fields.PasswordField(
-                    'secret-key', label='secret key', required=True,
-                    help='The secret key to use to authenticate to AWS. '
-                         'See the access key help above.'),
-                fields.AutoGeneratedStringField(
-                    'control-bucket', label='control bucket', required=True,
-                    help='the globally unique S3 bucket name'),
-                fields.ChoiceField(
-                    'region', choices=ec2_regions, default='us-east-1',
-                    label='region', required=False,
-                    help='the ec2 region to use'),
-                is_default_field,
-            ),
-        },
-        'local': {
-            'description': (
-                'The LXC local provider enables you to run Juju on a single '
-                'system like your local computer or a single server. '
-                'See https://juju.ubuntu.com/docs/config-LXC.html for more '
-                'details on the local provider configuration.'
-            ),
-            'fields': (
-                provider_field,
-                name_field,
-                admin_secret_field,
-                default_series_field,
-                fields.StringField(
-                    'root-dir', label='root dir', required=False,
-                    default='~/.juju/local',
-                    help='the directory that is used for the storage files'),
-                fields.IntField(
-                    'storage-port', min_value=1, max_value=65535,
-                    label='storage port', required=False, default=8040,
-                    help='override if you have multiple local providers, '
-                         'or if the default port is used by another program'),
-                fields.IntField(
-                    'shared-storage-port', min_value=1, max_value=65535,
-                    label='shared storage port', required=False, default=8041,
-                    help='override if you have multiple local providers, '
-                         'or if the default port is used by another program'),
-                fields.StringField(
-                    'network-bridge', label='network bridge', required=False,
-                    default='lxcbr0', help='the LXC bridge interface to use'),
-                is_default_field,
-            ),
-        },
+    # This is an ordered dict so that views can expose options to create new
+    # environments in the order we like.
+    env_type_db = collections.OrderedDict({
         '__fallback__': {
             'description': (
                 'This provider type is not supported by quickstart. '
@@ -434,7 +388,78 @@
                 default_series_field,
                 is_default_field,
             ),
-        }
+        },
+    })
+    env_type_db['ec2'] = {
+        'description': (
+            'The ec2 provider enable you to run Juju on the EC2 cloud. '
+            'This process requires you to have an Amazon Web Services (AWS) '
+            'account. If you have not signed up for one yet, it can obtained '
+            'at http://aws.amazon.com. '
+            'See https://juju.ubuntu.com/docs/config-aws.html for more '
+            'details on the ec2 provider configuration.'
+        ),
+        'fields': (
+            provider_field,
+            name_field,
+            admin_secret_field,
+            default_series_field,
+            fields.PasswordField(
+                'access-key', label='access key', required=True,
+                help='The access key to use to authenticate to AWS. '
+                     'You can retrieve these values easily from your AWS '
+                     'Management Console (http://console.aws.amazon.com). '
+                     'Click on your name in the top-right and then the '
+                     '"Security Credentials" link from the drop down menu. '
+                     'Under the "Access Keys" heading click the '
+                     '"Create New Root Key" button. You will be prompted to '
+                     '"Download Key File" which by default is named '
+                     'rootkey.csv. Open this file to get the access-key and '
+                     'secret-key for the environments.yaml config file.'),
+            fields.PasswordField(
+                'secret-key', label='secret key', required=True,
+                help='The secret key to use to authenticate to AWS. '
+                     'See the access key help above.'),
+            fields.AutoGeneratedStringField(
+                'control-bucket', label='control bucket', required=True,
+                help='the globally unique S3 bucket name'),
+            fields.ChoiceField(
+                'region', choices=ec2_regions, default='us-east-1',
+                label='region', required=False, help='the ec2 region to use'),
+            is_default_field,
+        ),
+    }
+    env_type_db['local'] = {
+        'description': (
+            'The LXC local provider enables you to run Juju on a single '
+            'system like your local computer or a single server. '
+            'See https://juju.ubuntu.com/docs/config-LXC.html for more '
+            'details on the local provider configuration.'
+        ),
+        'fields': (
+            provider_field,
+            name_field,
+            admin_secret_field,
+            default_series_field,
+            fields.StringField(
+                'root-dir', label='root dir', required=False,
+                default='~/.juju/local',
+                help='the directory that is used for the storage files'),
+            fields.IntField(
+                'storage-port', min_value=1, max_value=65535,
+                label='storage port', required=False, default=8040,
+                help='override if you have multiple local providers, '
+                     'or if the default port is used by another program'),
+            fields.IntField(
+                'shared-storage-port', min_value=1, max_value=65535,
+                label='shared storage port', required=False, default=8041,
+                help='override if you have multiple local providers, '
+                     'or if the default port is used by another program'),
+            fields.StringField(
+                'network-bridge', label='network bridge', required=False,
+                default='lxcbr0', help='the LXC bridge interface to use'),
+            is_default_field,
+        ),
     }
     return env_type_db
 
@@ -534,54 +559,3 @@
     if info_parts:
         info = ' ({})'.format(', '.join(info_parts))
     return env_data['name'] + info
-
-
-def parse_env_file(env_file, env_name):
-    """Parse the provided Juju environments.yaml file.
-
-    Return a tuple containing:
-      - provider type
-      - admin secret
-      - default series (None if not set)
-
-    Raise a ValueError if:
-      - the environment file is not found;
-      - the environment file contents are not parsable by YAML;
-      - the YAML contents are not properly structured;
-      - the environment named envname is not found;
-      - the environment does not include the "type" field;
-      - the environment does not include the "admin_secret" field.
-    """
-    # Load the Juju environments file.
-    try:
-        environments_file = open(env_file.encode('utf-8'))
-    except IOError as err:
-        msg = b'unable to open environments file: {}'.format(err)
-        raise ValueError(msg)
-    # Parse the Juju environments file.
-    try:
-        environments = serializers.yaml_load(environments_file)
-    except Exception as err:
-        msg = b'unable to parse environments file {}: {}'
-        raise ValueError(msg.format(env_file.encode('utf-8'), err))
-    # Retrieve the information about the current environment.
-    try:
-        environment = environments.get('environments', {}).get(env_name)
-    except AttributeError as err:
-        msg = 'invalid YAML contents in {}: {}'.format(env_file, environments)
-        raise ValueError(msg.encode('utf-8'))
-    if environment is None:
-        msg = 'environment {} not found in {}'.format(env_name, env_file)
-        raise ValueError(msg.encode('utf-8'))
-    # Retrieve the provider type and the admin secret.
-    env_type = environment.get('type')
-    if env_type is None:
-        msg = '{} provider type not found in {}'.format(env_name, env_file)
-        raise ValueError(msg.encode('utf-8'))
-    admin_secret = environment.get('admin-secret')
-    if admin_secret is None:
-        msg = '{} admin secret not found in {}'.format(env_name, env_file)
-        raise ValueError(msg.encode('utf-8'))
-    # The default-series is not required to be set so None is ok.
-    default_series = environment.get('default-series')
-    return env_type, admin_secret, default_series

=== modified file 'quickstart/tests/cli/test_views.py'
--- quickstart/tests/cli/test_views.py	2014-01-07 15:53:57 +0000
+++ quickstart/tests/cli/test_views.py	2014-01-13 15:31:13 +0000
@@ -216,6 +216,28 @@
             # loop cycle.
             mock_env_edit.reset_mock()
 
+    def test_create_and_bootstrap_local_environment_clicked(self):
+        # When there are no environments in the env_db the view exposes an
+        # option to automatically create and bootstrap a new local environment.
+        # If that option is clicked, the view quits the application returning
+        # the newly created env_data.
+        env_db = envs.create_empty_env_db()
+        views.env_index(self.app, self.env_type_db, env_db, self.save_callable)
+        buttons = self.get_widgets_in_contents(
+            filter_function=self.is_a(ui.MenuButton))
+        # The "create and bootstrap" button is the first one in the contents.
+        create_button = buttons[0]
+        self.assertEqual(
+            '\N{BULLET} automatically create and bootstrap a local '
+            'environment', cli_helpers.get_button_caption(create_button))
+        # An AppExit is raised clicking the button.
+        with self.assertRaises(ui.AppExit) as context_manager:
+            cli_helpers.emit(create_button)
+        new_env_db, env_data = context_manager.exception.return_value
+        # The environments database is no longer empty.
+        self.assertIn('local', new_env_db['environments'])
+        self.assertEqual(envs.get_env_data(new_env_db, 'local'), env_data)
+
     def test_selected_environment(self):
         # The default environment is already selected in the list.
         env_db = helpers.make_env_db(default='lxc')
@@ -604,6 +626,26 @@
             self.app, self.env_type_db, self.env_db, self.save_callable,
             new_env_data)
 
+    @mock.patch('quickstart.cli.views.env_detail')
+    def test_save_empty_db(self, mock_env_detail):
+        # If the env_db is empty, the new environment is set as default.
+        self.env_db = envs.create_empty_env_db()
+        changes = {
+            'name': 'lxc',
+            'admin-secret': 'Secret!',
+            'is-default': False,
+        }
+        with self.patch_create_form(changes=changes):
+            self.call_view(env_type='local')
+        save_button = self.get_control_buttons()[0]
+        cli_helpers.emit(save_button)
+        expected_new_env_data = changes.copy()
+        expected_new_env_data.update({'type': 'local', 'is-default': True})
+        envs.set_env_data(self.env_db, None, expected_new_env_data)
+        mock_env_detail.assert_called_once_with(
+            self.app, self.env_type_db, self.env_db, self.save_callable,
+            expected_new_env_data)
+
     def test_save_invalid_form_data(self):
         # Errors are displayed if the user tries to save invalid data.
         changes = {'admin-secret': ''}

=== modified file 'quickstart/tests/helpers.py'
--- quickstart/tests/helpers.py	2013-12-19 08:52:34 +0000
+++ quickstart/tests/helpers.py	2014-01-13 15:31:13 +0000
@@ -109,7 +109,10 @@
             'aws': {
                 'admin-secret': 'Secret!',
                 'type': 'ec2',
-                'default-series': 'edgy',
+                'default-series': 'saucy',
+                'access-key': 'AccessKey',
+                'secret-key': 'SeceretKey',
+                'control-bucket': 'ControlBucket',
             },
         },
     })

=== modified file 'quickstart/tests/models/test_envs.py'
--- quickstart/tests/models/test_envs.py	2013-12-20 14:47:35 +0000
+++ quickstart/tests/models/test_envs.py	2014-01-13 15:31:13 +0000
@@ -83,6 +83,14 @@
         mock_call.assert_called_once_with('juju', 'switch')
 
 
+class TestCreateEmptyEnvDb(unittest.TestCase):
+
+    def test_resulting_env_db(self):
+        # The function surprisingly returns an empty environments database.
+        env_db = envs.create_empty_env_db()
+        self.assertEqual({'environments': {}}, env_db)
+
+
 class TestLoad(
         helpers.EnvFileTestsMixin, helpers.ValueErrorTestsMixin,
         unittest.TestCase):
@@ -104,6 +112,12 @@
         expected = 'unable to parse environments file {}'.format(env_file)
         self.assertIn(expected, bytes(context_manager.exception))
 
+    def test_empty_file(self):
+        # An empty environments database is returned if the file is empty.
+        env_file = self.make_env_file('')
+        env_db = envs.load(env_file)
+        self.assertEqual({'environments': {}}, env_db)
+
     def test_invalid_yaml_contents(self):
         # A ValueError is raised if the environments file is not well formed.
         env_file = self.make_env_file('a-string')
@@ -258,7 +272,7 @@
     def test_env_not_found(self):
         # A ValueError is raised if an environment with the given name is not
         # found in the environments dictionary.
-        with self.assert_value_error("environment u'no-such' not found"):
+        with self.assert_value_error("environment no-such not found"):
             envs.get_env_data(self.env_db, 'no-such')
 
     def test_resulting_env_data(self):
@@ -481,6 +495,35 @@
         self.assertNotIn('default', self.env_db)
 
 
+class TestCreateLocalEnvData(unittest.TestCase):
+
+    def setUp(self):
+        # Store the env_type_db.
+        self.env_type_db = envs.get_env_type_db()
+
+    def test_not_default(self):
+        # The resulting env_data is correctly structured for non default envs.
+        env_data = envs.create_local_env_data(
+            self.env_type_db, 'my-lxc', is_default=False)
+        # The function is not pure: auto-generated values change each time the
+        # function is called. For local environments, the only auto-generated
+        # value should be the admin-secret.
+        admin_secret = env_data.pop('admin-secret', '')
+        self.assertNotEqual(0, len(admin_secret))
+        expected = {'type': 'local', 'name': 'my-lxc', 'is-default': False}
+        self.assertEqual(expected, env_data)
+
+    def test_default(self):
+        # The resulting env_data is correctly structured for default envs.
+        env_data = envs.create_local_env_data(
+            self.env_type_db, 'my-default', is_default=True)
+        # See the comment about auto-generated fields in the test method above.
+        admin_secret = env_data.pop('admin-secret', '')
+        self.assertNotEqual(0, len(admin_secret))
+        expected = {'type': 'local', 'name': 'my-default', 'is-default': True}
+        self.assertEqual(expected, env_data)
+
+
 class TestRemoveEnv(
         EnvDataTestsMixin, helpers.ValueErrorTestsMixin, unittest.TestCase):
 
@@ -913,81 +956,3 @@
         env_data = {'name': 'lxc', 'type': None, 'is-default': True}
         description = envs.get_env_short_description(env_data)
         self.assertEqual('lxc (default)', description)
-
-
-class TestParseEnvFile(
-        helpers.EnvFileTestsMixin, helpers.ValueErrorTestsMixin,
-        unittest.TestCase):
-
-    def test_no_file(self):
-        # A ValueError is raised if the environments file is not found.
-        expected = (
-            'unable to open environments file: '
-            "[Errno 2] No such file or directory: '/no/such/file.yaml'"
-        )
-        with self.assert_value_error(expected):
-            envs.parse_env_file('/no/such/file.yaml', 'ec2')
-
-    def test_invalid_yaml(self):
-        # A ValueError is raised if the environments file is not a valid YAML.
-        env_file = self.make_env_file(':')
-        with self.assertRaises(ValueError) as context_manager:
-            envs.parse_env_file(env_file, 'ec2')
-        expected = 'unable to parse environments file {}'.format(env_file)
-        self.assertIn(expected, bytes(context_manager.exception))
-
-    def test_invalid_yaml_contents(self):
-        # A ValueError is raised if the environments file is not well formed.
-        env_file = self.make_env_file('a-string')
-        expected = 'invalid YAML contents in {}: a-string'.format(env_file)
-        with self.assert_value_error(expected):
-            envs.parse_env_file(env_file, 'ec2')
-
-    def test_no_env(self):
-        # A ValueError is raised if the environment is not found in the YAML.
-        contents = yaml.safe_dump({'environments': {'local': {}}})
-        env_file = self.make_env_file(contents)
-        expected = 'environment ec2 not found in {}'.format(env_file)
-        with self.assert_value_error(expected):
-            envs.parse_env_file(env_file, 'ec2')
-
-    def test_no_provider_type(self):
-        # A ValueError is raised if the provider type is not included in the
-        # environment info.
-        contents = yaml.safe_dump({'environments': {'aws': {}}})
-        env_file = self.make_env_file(contents)
-        expected = 'aws provider type not found in {}'.format(env_file)
-        with self.assert_value_error(expected):
-            envs.parse_env_file(env_file, 'aws')
-
-    def test_no_admin_secret(self):
-        # A ValueError is raised if the admin secret is not included in the
-        # environment info.
-        contents = yaml.safe_dump({'environments': {'aws': {'type': 'ec2'}}})
-        env_file = self.make_env_file(contents)
-        expected = 'aws admin secret not found in {}'.format(env_file)
-        with self.assert_value_error(expected):
-            envs.parse_env_file(env_file, 'aws')
-
-    def test_success_no_default_series(self):
-        # The environment provider type and admin secret are returned.
-        # Default series is None.
-        contents = yaml.safe_dump({
-            'environments': {'aws': {'admin-secret': 'Secret!', 'type': 'ec2'}}
-        })
-        env_file = self.make_env_file(contents)
-        env_type, admin_secret, default_series = (
-            envs.parse_env_file(env_file, 'aws'))
-        self.assertEqual('ec2', env_type)
-        self.assertEqual('Secret!', admin_secret)
-        self.assertIsNone(default_series)
-
-    def test_success_with_default_series(self):
-        # The environment provider type and admin secret are returned.
-        # Default series is also returned.
-        env_file = self.make_env_file()
-        env_type, admin_secret, default_series = (
-            envs.parse_env_file(env_file, 'aws'))
-        self.assertEqual('ec2', env_type)
-        self.assertEqual('Secret!', admin_secret)
-        self.assertEqual('edgy', default_series)

=== modified file 'quickstart/tests/test_app.py'
--- quickstart/tests/test_app.py	2013-12-19 03:29:39 +0000
+++ quickstart/tests/test_app.py	2014-01-13 15:31:13 +0000
@@ -377,40 +377,6 @@
 
 
 @helpers.mock_print
-class TestEnsureEnvironments(
-        helpers.CallTestsMixin, ProgramExitTestsMixin, unittest.TestCase):
-
-    def test_inits(self, mock_print):
-        side_effects = (
-            (0, '', ''),
-            (0, '', ''),
-        )
-        with self.patch_multiple_calls(side_effects):
-            self.assertEqual(app.ensure_environments(), 'local')
-            mock_print.assert_has_calls([
-                mock.call('environments file not found; running juju init'),
-                mock.call('defaulting to local environment for a new '
-                          'environments file')
-            ])
-
-    def test_failure(self, mock_print):
-        side_effects = (
-            (1, '', 'Error!'),  # Fail on init.
-            (0, '', ''),
-        )
-        with self.assert_program_exit('Error!'):
-            with self.patch_multiple_calls(side_effects):
-                app.ensure_environments()
-        side_effects = (
-            (0, '', ''),
-            (1, '', 'Error!'),  # Fail on switch.
-        )
-        with self.assert_program_exit('Error!'):
-            with self.patch_multiple_calls(side_effects):
-                app.ensure_environments()
-
-
[e-mail]_print
 class TestBootstrap(
         helpers.CallTestsMixin, ProgramExitTestsMixin, unittest.TestCase):
 

=== modified file 'quickstart/tests/test_manage.py'
--- quickstart/tests/test_manage.py	2013-12-06 18:16:02 +0000
+++ quickstart/tests/test_manage.py	2014-01-13 15:31:13 +0000
@@ -19,6 +19,7 @@
 from __future__ import unicode_literals
 
 import argparse
+from contextlib import contextmanager
 import logging
 import os
 import shutil
@@ -34,6 +35,8 @@
     manage,
     settings,
 )
+from quickstart.cli import views
+from quickstart.models import envs
 from quickstart.tests import helpers
 
 
@@ -244,24 +247,182 @@
             self.assertFalse(self.parser.error.called, charm_url)
 
 
-class TestValidateEnv(helpers.EnvFileTestsMixin, unittest.TestCase):
-
-    def setUp(self):
-        self.parser = mock.Mock()
-
-    def make_options(self, env_file, env_name=None):
+class TestRetrieveEnvDb(helpers.EnvFileTestsMixin, unittest.TestCase):
+
+    def setUp(self):
+        self.parser = mock.Mock()
+
+    def test_existing_env_file(self):
+        # The env_db is correctly retrieved from an existing environments file.
+        env_file = self.make_env_file()
+        env_db = manage._retrieve_env_db(self.parser, env_file=env_file)
+        self.assertEqual(yaml.safe_load(self.valid_contents), env_db)
+
+    def test_error_parsing_env_file(self):
+        # A parser error is invoked if an error occurs parsing the env file.
+        env_file = self.make_env_file('so-bad')
+        manage._retrieve_env_db(self.parser, env_file=env_file)
+        self.parser.error.assert_called_once_with(
+            'invalid YAML contents in {}: so-bad'.format(env_file))
+
+    def test_missing_env_file(self):
+        # An empty env_db is returned if the environments file does not exist.
+        env_db = manage._retrieve_env_db(self.parser, env_file=None)
+        self.assertEqual(envs.create_empty_env_db(), env_db)
+
+
[e-mail]('quickstart.manage.envs.save')
+class TestCreateSaveCallable(unittest.TestCase):
+
+    def setUp(self):
+        self.parser = mock.Mock()
+        self.env_file = '/tmp/envfile.yaml'
+        self.env_db = helpers.make_env_db()
+        self.save_callable = manage._create_save_callable(
+            self.parser, self.env_file)
+
+    def test_saved(self, mock_save):
+        # The returned function correctly saves the new environments database.
+        self.save_callable(self.env_db)
+        mock_save.assert_called_once_with(self.env_file, self.env_db)
+        self.assertFalse(self.parser.error.called)
+
+    def test_error(self, mock_save):
+        # The returned function uses the parser to exit the program if an error
+        # occurs while saving the new environments database.
+        mock_save.side_effect = OSError(b'bad wolf')
+        self.save_callable(self.env_db)
+        mock_save.assert_called_once_with(self.env_file, self.env_db)
+        self.parser.error.assert_called_once_with('bad wolf')
+
+
+class TestStartInteractiveSession(
+        helpers.EnvFileTestsMixin, unittest.TestCase):
+
+    def setUp(self):
+        # Set up a parser, the environments metadata, an environments file and
+        # a testing env_db.
+        self.parser = mock.Mock()
+        self.env_type_db = envs.get_env_type_db()
+        self.env_file = self.make_env_file()
+        self.env_db = envs.load(self.env_file)
+
+    @contextmanager
+    def patch_interactive_mode(self, env_db, return_value):
+        """Patch the quickstart.cli.views.show function.
+
+        Ensure the interactive mode is started by the code in the context block
+        passing the given env_db. Make the view return the given return_value.
+        """
+        create_save_callable_path = 'quickstart.manage._create_save_callable'
+        mock_show = mock.Mock(return_value=return_value)
+        with mock.patch(create_save_callable_path) as mock_save_callable:
+            with mock.patch('quickstart.manage.views.show', mock_show):
+                yield
+        mock_save_callable.assert_called_once_with(self.parser, self.env_file)
+        mock_show.assert_called_once_with(
+            views.env_index, self.env_type_db, env_db,
+            mock_save_callable())
+
+    def test_resulting_env_data(self):
+        # The interactive session can be used to select an environment, in
+        # which case the function returns the corresponding env_data.
+        env_data = envs.get_env_data(self.env_db, 'aws')
+        with self.patch_interactive_mode(self.env_db, [self.env_db, env_data]):
+            obtained_env_data = manage._start_interactive_session(
+                self.parser, self.env_type_db, self.env_db, self.env_file)
+        self.assertEqual(env_data, obtained_env_data)
+
+    @helpers.mock_print
+    def test_modified_environments(self, mock_print):
+        # The function informs the user that environments have been modified
+        # during the interactive session.
+        env_data = envs.get_env_data(self.env_db, 'aws')
+        new_env_db = helpers.make_env_db()
+        with self.patch_interactive_mode(self.env_db, [new_env_db, env_data]):
+            manage._start_interactive_session(
+                self.parser, self.env_type_db, self.env_db, self.env_file)
+        mock_print.assert_called_once_with(
+            'changes to the environments file have been saved')
+
+    @mock.patch('sys.exit')
+    def test_interactive_mode_quit(self, mock_exit):
+        # If the user explicitly quits the interactive mode, the program exits
+        # without proceeding with the environment bootstrapping.
+        with self.patch_interactive_mode(self.env_db, [self.env_db, None]):
+            manage._start_interactive_session(
+                self.parser, self.env_type_db, self.env_db, self.env_file)
+        mock_exit.assert_called_once_with('quitting')
+
+
+class TestRetrieveEnvData(unittest.TestCase):
+
+    def setUp(self):
+        # Set up a parser, the environments metadata and a testing env_db.
+        self.parser = mock.Mock()
+        self.env_type_db = envs.get_env_type_db()
+        self.env_db = helpers.make_env_db()
+
+    def test_resulting_env_data(self):
+        # The env_data is correctly validated and returned.
+        expected_env_data = envs.get_env_data(self.env_db, 'lxc')
+        env_data = manage._retrieve_env_data(
+            self.parser, self.env_type_db, self.env_db, 'lxc')
+        self.assertEqual(expected_env_data, env_data)
+
+    def test_error_environment_not_found(self):
+        # A parser error is invoked if the provided environment is not included
+        # in the environments database.
+        manage._retrieve_env_data(
+            self.parser, self.env_type_db, self.env_db, 'no-such')
+        self.parser.error.assert_called_once_with(
+            'environment no-such not found')
+
+    def test_error_environment_not_valid(self):
+        # A parser error is invoked if the selected environment is not valid.
+        manage._retrieve_env_data(
+            self.parser, self.env_type_db, self.env_db, 'local-with-errors')
+        self.parser.error.assert_called_once_with(
+            'cannot use the local-with-errors environment:\n'
+            'the storage port field requires an integer value\n'
+            'a value is required for the admin secret field')
+
+
+class TestSetupEnv(helpers.EnvFileTestsMixin, unittest.TestCase):
+
+    def setUp(self):
+        self.parser = mock.Mock()
+
+    def make_options(self, env_file, env_name=None, interactive=False):
         """Return a mock options object which includes the passed arguments."""
-        return mock.Mock(env_file=env_file, env_name=env_name)
+        return mock.Mock(
+            env_file=env_file,
+            env_name=env_name,
+            interactive=interactive,
+        )
+
+    def patch_interactive_mode(self, return_value):
+        """Patch the quickstart.manage._start_interactive_session function.
+
+        Make the mocked function return the given return_value.
+        """
+        mock_start_interactive_session = mock.Mock(return_value=return_value)
+        return mock.patch(
+            'quickstart.manage._start_interactive_session',
+            mock_start_interactive_session)
 
     def test_resulting_options(self):
         # The options object is correctly set up.
         env_file = self.make_env_file()
-        options = self.make_options(env_file, env_name='aws')
-        manage._validate_env(options, self.parser)
+        options = self.make_options(
+            env_file, env_name='aws', interactive=False)
+        manage._setup_env(options, self.parser)
         self.assertEqual('Secret!', options.admin_secret)
         self.assertEqual(env_file, options.env_file)
         self.assertEqual('aws', options.env_name)
         self.assertEqual('ec2', options.env_type)
+        self.assertEqual('saucy', options.default_series)
+        self.assertFalse(options.interactive)
 
     def test_expand_user(self):
         # The ~ construct is correctly expanded in the validation process.
@@ -274,40 +435,74 @@
         path = '~/{}'.format(filename)
         options = self.make_options(env_file=path, env_name='aws')
         with mock.patch('os.environ', {'HOME': base_path}):
-            manage._validate_env(options, self.parser)
+            manage._setup_env(options, self.parser)
         self.assertEqual(env_file, options.env_file)
 
     def test_no_env_name(self):
-        # A parser error is invoked if the environment name is missing.
-        options = self.make_options(self.make_env_file())
-        manage._validate_env(options, self.parser)
+        # A parser error is invoked if the environment name is missing and
+        # interactive mode is disabled.
+        options = self.make_options(self.make_env_file(), interactive=False)
+        manage._setup_env(options, self.parser)
         self.assertTrue(self.parser.error.called)
         message = self.parser.error.call_args[0][0]
         self.assertIn('unable to find an environment name to use', message)
 
-    def test_error_parsing_env_file(self):
-        # A parser error is invoked if an error occurs parsing the env file.
-        env_file = self.make_env_file()
-        options = self.make_options(env_file, env_name='no-such')
-        manage._validate_env(options, self.parser)
-        expected = 'environment no-such not found in {}'.format(env_file)
-        self.parser.error.assert_called_once_with(expected)
-
     def test_local_provider(self):
-        # The parser exits with an error if the provided environment name
-        # refers to a local provider type.
+        # Local environments are correctly handled.
         contents = yaml.safe_dump({
             'environments': {
                 'lxc': {'admin-secret': 'Secret!', 'type': 'local'},
             },
         })
         env_file = self.make_env_file(contents)
-        options = self.make_options(env_file, env_name='lxc')
-        manage._validate_env(options, self.parser)
+        options = self.make_options(
+            env_file, env_name='lxc', interactive=False)
+        manage._setup_env(options, self.parser)
         self.assertEqual('Secret!', options.admin_secret)
         self.assertEqual(env_file, options.env_file)
         self.assertEqual('lxc', options.env_name)
         self.assertEqual('local', options.env_type)
+        self.assertIsNone(options.default_series)
+        self.assertFalse(options.interactive)
+
+    def test_interactive_mode(self):
+        # The interactive mode is started properly if the corresponding option
+        # flag is set.
+        env_file = self.make_env_file()
+        options = self.make_options(env_file, interactive=True)
+        # Simulate the user did not make any changes to the env_db from the
+        # interactive session.
+        env_db = yaml.load(self.valid_contents)
+        # Simulate the aws environment has been selected and started from the
+        # interactive session.
+        env_data = envs.get_env_data(env_db, 'aws')
+        get_env_type_db_path = 'quickstart.models.envs.get_env_type_db'
+        with mock.patch(get_env_type_db_path) as mock_get_env_type_db:
+            with self.patch_interactive_mode(env_data) as mock_interactive:
+                manage._setup_env(options, self.parser)
+        mock_interactive.assert_called_once_with(
+            self.parser, mock_get_env_type_db(), env_db, env_file)
+        # The options is updated with data from the selected environment.
+        self.assertEqual('Secret!', options.admin_secret)
+        self.assertEqual(env_file, options.env_file)
+        self.assertEqual('aws', options.env_name)
+        self.assertEqual('ec2', options.env_type)
+        self.assertEqual('saucy', options.default_series)
+        self.assertTrue(options.interactive)
+
+    @helpers.mock_print
+    def test_missing_env_file(self, mock_print):
+        # If the environments file does not exist, an empty env_db is created
+        # in memory and interactive mode is forced.
+        new_env_db = helpers.make_env_db()
+        env_data = envs.get_env_data(new_env_db, 'lxc')
+        options = self.make_options('__no_such_env_file__', interactive=False)
+        # In this case, we expect the interactive mode to be started and the
+        # env_db passed to the view to be an empty one.
+        with self.patch_interactive_mode(env_data) as mock_interactive:
+            manage._setup_env(options, self.parser)
+        self.assertTrue(mock_interactive.called)
+        self.assertTrue(options.interactive)
 
 
 class TestConvertOptionsToUnicode(unittest.TestCase):
@@ -334,7 +529,7 @@
         self.assertIsNone(options.opt2)
 
 
[e-mail]('quickstart.manage._validate_env', mock.Mock())
[e-mail]('quickstart.manage._setup_env', mock.Mock())
 class TestSetup(unittest.TestCase):
 
     def patch_get_default_env_name(self, env_name=None):
@@ -388,13 +583,6 @@
         output = stdout_write.call_args[0][0]
         self.assertIn('The name of the Juju environment to use (hp)\n', output)
 
-    def test_init_environment(self):
-        # The program calls ensure_environments if env_name is None.
-        with mock.patch('quickstart.app.ensure_environments',
-                        return_value='local') as ensure_environments:
-            self.call_setup([], env_name=None, exit_called=False)
-        self.assertTrue(ensure_environments.called)
-
     def test_description(self):
         # The program description is properly printed out as required by juju.
         with helpers.mock_print as mock_print:

=== modified file 'quickstart/tests/test_utils.py'
--- quickstart/tests/test_utils.py	2013-12-19 08:47:57 +0000
+++ quickstart/tests/test_utils.py	2014-01-13 15:31:13 +0000
@@ -21,7 +21,10 @@
 import datetime
 import httplib
 import json
+import os
+import shutil
 import socket
+import tempfile
 import unittest
 import urllib2
 
@@ -378,6 +381,55 @@
         mock_call.assert_called_once_with('lsb_release', '-cs')
 
 
+class TestMkdir(unittest.TestCase):
+
+    def setUp(self):
+        # Set up a playground directory.
+        self.playground = tempfile.mkdtemp()
+        self.addCleanup(shutil.rmtree, self.playground)
+
+    def test_create_dir(self):
+        # A directory is correctly created.
+        path = os.path.join(self.playground, 'foo')
+        utils.mkdir(path)
+        self.assertTrue(os.path.isdir(path))
+
+    def test_intermediate_dirs(self):
+        # All intermediate directories are created.
+        path = os.path.join(self.playground, 'foo', 'bar', 'leaf')
+        utils.mkdir(path)
+        self.assertTrue(os.path.isdir(path))
+
+    def test_expand_user(self):
+        # The ~ construction is expanded.
+        with mock.patch('os.environ', {'HOME': self.playground}):
+            utils.mkdir('~/in/my/home')
+        path = os.path.join(self.playground, 'in', 'my', 'home')
+        self.assertTrue(os.path.isdir(path))
+
+    def test_existing_dir(self):
+        # The function exits without errors if the target directory exists.
+        path = os.path.join(self.playground, 'foo')
+        os.mkdir(path)
+        utils.mkdir(path)
+
+    def test_existing_file(self):
+        # An OSError is raised if a file already exists in the target path.
+        path = os.path.join(self.playground, 'foo')
+        with open(path, 'w'):
+            with self.assertRaises(OSError):
+                utils.mkdir(path)
+
+    def test_failure(self):
+        # Errors are correctly re-raised.
+        path = os.path.join(self.playground, 'foo')
+        os.chmod(self.playground, 0000)
+        self.addCleanup(os.chmod, self.playground, 0700)
+        with self.assertRaises(OSError):
+            utils.mkdir(os.path.join(path))
+        self.assertFalse(os.path.exists(path))
+
+
 class TestParseBundle(
         helpers.BundleFileTestsMixin, helpers.ValueErrorTestsMixin,
         unittest.TestCase):

=== modified file 'quickstart/utils.py'
--- quickstart/utils.py	2013-12-19 08:47:57 +0000
+++ quickstart/utils.py	2014-01-13 15:31:13 +0000
@@ -23,6 +23,7 @@
 
 import collections
 import datetime
+import errno
 import httplib
 import json
 import logging
@@ -204,6 +205,21 @@
     return output.strip()
 
 
+def mkdir(path):
+    """Create a leaf directory and all intermediate ones.
+
+    Also expand ~ and ~user constructions.
+    If path exists and it's a directory, return without errors.
+    """
+    path = os.path.expanduser(path)
+    try:
+        os.makedirs(path)
+    except OSError as err:
+        # Re-raise the error if the target path exists but it is not a dir.
+        if (err.errno != errno.EEXIST) or (not os.path.isdir(path)):
+            raise
+
+
 def parse_bundle(bundle_yaml, bundle_name=None):
     """Parse the provided bundle YAML encoded contents.