toaster-manual: Draft of Manual.

Fixes [YOCTO #6901]

(From yocto-docs rev: 258b46b0f3e23045b5fb8c97d03dceb69db5ce20)

Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>

documentation/template/embedded_video.xsl

@@ -0,0 +1,22 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<xsl:stylesheet version="1.0"
+   xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
+   xmlns:d="http://docbook.org/ns/docbook">
+
+   <xsl:output method="html" />
+
+   <xsl:template match="/d:chapter/d:section/d:mediaobject">
+      <xsl:for-each select=".">
+         <xsl:variable name="vid_url">
+            <xsl:value-of select="./d:videoobject/d:videodata/@fileref" />
+         </xsl:variable>
+         <div style="text-align: center; margin: auto">
+            <object type="application/x-shockwave-flash" width="640" height="420" data="{$vid_url}?color2=FBE9EC&amp;showsearch=0&amp;version=3&amp;modestbranding=1&amp;fs=1">
+               <param name="movie" value="{$vid_url}?color2=FBE9EC&amp;showsearch=0&amp;version=3&amp;modestbranding=1&amp;fs=1" />
+               <param name="allowFullScreen" value="true" />
+               <param name="allowscriptaccess" value="always" />
+            </object>
+         </div>
+      </xsl:for-each>
+  </xsl:template>
+</xsl:stylesheet>

documentation/toaster-manual/toaster-manual-customization.xsl

@@ -1,13 +1,15 @@
 <?xml version='1.0'?>
 <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns="http://www.w3.org/1999/xhtml" xmlns:fo="http://www.w3.org/1999/XSL/Format" version="1.0">
 
-  <xsl:import href="http://docbook.sourceforge.net/release/xsl/1.76.1/xhtml/docbook.xsl" />
+<!--  <xsl:import href="http://docbook.sourceforge.net/release/xsl/1.76.1/xhtml/docbook.xsl" /> -->
+  <xsl:import href="../template/1.76.1/docbook-xsl-1.76.1/xhtml/docbook.xsl" />
 
   <xsl:include href="../template/permalinks.xsl"/>
   <xsl:include href="../template/section.title.xsl"/>
   <xsl:include href="../template/component.title.xsl"/>
   <xsl:include href="../template/division.title.xsl"/>
   <xsl:include href="../template/formal.object.heading.xsl"/>
+  <xsl:include href="../template/embedded_video.xsl"/>
 
   <xsl:param name="html.stylesheet" select="'toaster-manual-style.css'" />
   <xsl:param name="chapter.autolabel" select="1" />

documentation/toaster-manual/toaster-manual-intro.xml

@@ -6,95 +6,12 @@
 <title>Introduction</title>
 
     <para>
-        Toaster is web interface to the OpenEmbedded build system, which uses
-        BitBake.
-        The interface allows you to access a datastore that retains build
-        information and report out on the information.
-    </para>
-<!--THE FOLLOWING IS DETAIL THAT I THINK BELEN WANTED OUT FOR THE MOMENT
-        The interface is based on a Representational State Transfer
-        (REST) API that queries for and returns build information using
-        <filename>GET</filename> and <filename>JSON</filename>.
-        These types of search operations retrieve sets of objects from
-        a datastore used to collect build information.
-        The results contain all the data for the objects being returned.
-        You can order the results of the search by key and the search
-        parameters are consistent for all object types.
-    </para>
--->
-
-    <para>
-        You can use Toaster in several different modes:
-        <itemizedlist>
-            <listitem><para><emphasis>Analysis Mode:</emphasis>
-                In this mode, you can record builds and statistics.
-                In Analysis Mode, you have direct access to the
-                <filename>bitbake</filename> command, which you use to build
-                images.</para>
-                <para>Analysis Mode requires you to have first started
-                Toaster and then to initiate your build using the
-                <filename>bitbake</filename> command from the shell.
-                Toaster must be started before the build or it will not
-                collect build data.
-                </para></listitem>
-            <listitem><para><emphasis>Build Mode:</emphasis>
-                In this mode, Toaster handles the build configuration GUI
-                (through project pages) and build scheduling and execution.
-                In this mode, all your interaction with the build system
-                happens through the web interface.
-                You do not have direct access to the
-                <filename>bitbake</filename> command.</para>
-                <para>Using this mode, you configure and start your builds
-                with Toaster's GUI.
-                Each configuration is a project, which requires version and
-                build system selection.
-                As shipped, Toaster supports the Yocto Project releases
-                1.8 and beyond.
-                Aside from these supported releases, you can also select
-                the "Local Yocto Project", which allows you to use your
-                local clone of the Yocto Project
-                <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>
-                (e.g. <filename>poky</filename>).</para>
-                <para>Build Mode also works two separate ways: locally and
-                remotely.
-                While you can use Build Mode locally, it is best to use
-                Toaster's Build Mode through a hosted service where it can
-                shared by multiple user.
-                </para></listitem>
-        </itemizedlist>
-    </para>
-
-    <para>
-        Using Toaster, you can do the following:
-        <note><title>REVIEWER NOTE</title>
-            Belen suggested we split this list out into things that
-            Analysis Mode and Build Mode can do.
-            Also, we can structure the lists so the Build Mode list
-            leverages off what is listed for Analysis Mode.
-            I do not know the information for the complete lists.
-            Someone needs to help me out here.
-            For now, I am leaving the list as follows and will need some
-            information.
-        </note>
-        <itemizedlist>
-            <listitem><para>
-                See information about the tasks executed
-                and reused during the build.
-                </para></listitem>
-            <listitem><para>
-                See what is built (recipes and
-                packages) and what packages were installed into the final
-                image.
-                </para></listitem>
-            <listitem><para>
-                See performance-related information such
-                as build time, CPU usage, and disk I/O.
-                </para></listitem>
-            <listitem><para>
-                Examine error, warning and trace messages
-                to aid in debugging.
-                </para></listitem>
-        </itemizedlist>
+        Toaster is a web interface to the Yocto Project's
+        <ulink url='&YOCTO_DOCS_DEV_URL;#build-system-term'>OpenEmbedded build system</ulink>.
+        The interface enables you to configure and run your builds.
+        Information about builds is collected and stored in a database.
+        You can use Toaster to configure and start builds on multiple
+        remote build servers.
     </para>
 
     <note>
@@ -116,10 +33,131 @@
         </para>
     </note>
 
-    <para>
-        The remainder of this manual describes what you need to have in
-        place to use Toaster, how to start it, use it, and stop it.
-    </para>
+    <section id='intro-modes'>
+        <title>Toaster Operational Modes</title>
+
+        <para>
+            You can use Toaster in Analysis Mode or Build Mode:
+            <itemizedlist>
+                <listitem><para><emphasis>Analysis Mode:</emphasis>
+                    In Analysis Mode, you can record builds and statistics.
+                    In this Mode, you directly access the
+                    <filename>bitbake</filename> command, which you then use to
+                    build images.</para>
+                    <para>Analysis Mode requires you to have first started
+                    Toaster and then to initiate your build using the
+                    <filename>bitbake</filename> command from the shell.
+                    Toaster must be started before the build or it will not
+                    collect build data.</para>
+                    <para>Toaster has the following capabilities in
+                    Analysis Mode:
+                    <itemizedlist>
+                        <listitem><para>
+                            See what was built (recipes and packages) and what
+                            packages were installed into your final image.
+                            </para></listitem>
+                        <listitem><para>
+                            Browse the directory structure of your image.
+                            </para></listitem>
+                        <listitem><para>
+                            See the value of all variables in your build
+                            configuration, and which files set each value.
+                            </para></listitem>
+                        <listitem><para>
+                            Examine error, warning and trace messages to aid
+                            in debugging.
+                            </para></listitem>
+                        <listitem><para>
+                            See information about the BitBake tasks executed
+                            and reused during your build, including those that
+                            used shared state.
+                            </para></listitem>
+                        <listitem><para>
+                            See dependency relationships between recipes,
+                            packages and tasks
+                            </para></listitem>
+                        <listitem><para>
+                            See performance information such as build time,
+                            task time, CPU usage, and disk I/O.
+                            </para></listitem>
+                    </itemizedlist>
+                    </para></listitem>
+                <listitem><para><emphasis>Build Mode:</emphasis>
+                    In Build Mode, Toaster handles the build configuration,
+                    scheduling and execution.
+                    In this mode, all your interaction with the build system
+                    happens through the web interface.
+                    You do not have direct access to the
+                    <filename>bitbake</filename> command.</para>
+                    <para>Using this mode, you configure and start your builds
+                    within Toaster's GUI.
+                    Each project can be configured for a specific version
+                    of the build system.
+                    As shipped, Toaster supports Yocto Project Releases 1.7 and
+                    beyond.</para>
+                    <para>Toaster has all the same capabilities in Build Mode
+                    as it does in Analysis Mode plus the following:
+                    <itemizedlist>
+                        <listitem><para>
+                            Browse layers listed in the various
+                            <link linkend='layer-source'>layer sources</link>
+                            that are available in your project (e.g. the
+                            OpenEmbedded Metadata Index at
+                            <ulink url='http://layers.openembedded.org/layerindex/'></ulink>).
+                            </para></listitem>
+                        <listitem><para>
+                            Import your own layers for building.
+                            </para></listitem>
+                        <listitem><para>
+                            Add and remove layers from your configuration.
+                            </para></listitem>
+                        <listitem><para>
+                            Set configuration variables.
+                            </para></listitem>
+                        <listitem><para>
+                            Select a target or multiple targets to build.
+                            </para></listitem>
+                        <listitem><para>
+                            Start your builds.
+                            </para></listitem>
+                    </itemizedlist>
+                    </para></listitem>
+            </itemizedlist>
+        </para>
+    </section>
+
+    <section id='toaster-installation-options'>
+        <title>Installation Options</title>
+
+        <para>
+            You can set Toaster up to run as a local instance or as a shared
+            hosted service.
+            Regardless of how you set up Toaster, both Analysis and Build
+            Modes are available.
+        </para>
+
+        <para>
+            When Toaster is set up as a local instance, all the components
+            reside on a single build host.
+            Fundamentally, a local instance of Toaster is suited for a single
+            user developing on a single build host.
+        </para>
+
+        <para>
+            <imagedata fileref="figures/simple-configuration.png" align="center" width="6in" depth="1.5in" />
+        </para>
+
+        <para>
+            Toaster as a hosted service is suited for multiple users
+            developing across several build hosts.
+            When Toaster is set up as a hosted service, its components can
+            be spread across several machines:
+        </para>
+
+        <para>
+            <imagedata fileref="figures/hosted-service.png" align="center" width="6in" depth="3.5in" />
+        </para>
+    </section>
 
 <!--THIS EXTRA INFORMATION PROBABLY WILL GO AWAY
         For additional information on installing and running Toaster, see the

documentation/toaster-manual/toaster-manual-reference.xml

@@ -0,0 +1,1069 @@
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
+[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
+
+<chapter id='toaster-manual-reference'>
+
+<title>Concepts and Reference</title>
+
+    <para>
+        In order to configure and use Toaster, you should understand some
+        concepts and have some basic command reference material available.
+        This final chapter provides conceptual information on layer sources,
+        releases, and JSON configuration files.
+        Also provided is a quick look at some useful
+        <filename>manage.py</filename> commands.
+        Information on <filename>manage.py</filename> commands does exist
+        across the Web and the information in this manual by no means
+        attempts to provide a command reference.
+        However, having relevant command useful for the Toaster context
+        is helpful.
+    </para>
+
+    <section id='layer-source'>
+        <title>Layer Source</title>
+
+        <para>
+            In general, a layer source is some source of existing layers.
+            In particular, we are concerned with layers that you can use
+            with the Yocto Project and Toaster.
+            This chapter describes a particular type of layer source called
+            a "layer index."
+        </para>
+
+        <para>
+            A layer index is a web application that contains information
+            about a set of custom layers.
+            A good example of an existing layer index is the
+            OpenEmbedded Metadata Index.
+            A public instance of this layer index exists at
+            <ulink url='http://layers.openembedded.org'></ulink>.
+            You can find the code for this layer index's web application at
+            <ulink url='http://git.yoctoproject.org/cgit/cgit.cgi/layerindex-web/'></ulink>.
+        </para>
+
+        <para>
+            When you tie a layer source into Toaster, it can query the layer
+            source through a
+            <ulink url='http://en.wikipedia.org/wiki/Representational_state_transfer'>REST</ulink>
+            API, store the information about the layers in the Toaster
+            database, and then show the information to users.
+            Users are then able to view that information and build layers
+            from Toaster itself without worrying about cloning or editing
+            the BitBake layers configuration file
+            <filename>bblayers.conf</filename>.
+        </para>
+
+        <para>
+            Tying a layer source into Toaster is convenient when you have
+            many custom layers that need to be built on a regular basis by
+            a community of developers.
+            In fact, Toaster comes pre-configured with the OpenEmbedded
+            Metadata Index.
+            <note>
+                You do not have to use a layer source to use Toaster.
+                Tying into a layer source is optional.
+            </note>
+        </para>
+
+        <section id='layer-source-using-with-toaster'>
+            <title>Setting Up and Using a Layer Source</title>
+
+            <para>
+                To use your own layer source, you need to set up the layer
+                source and then tie it into Toaster.
+                This section describes how to tie into a layer index in a manner
+                similar to the way Toaster ties into the OpenEmbedded Metadata
+                Index.
+           </para>
+
+            <section id='understanding-your-layers'>
+                <title>Understanding Your Layers</title>
+
+                <para>
+                    The obvious first step for using a layer index is to have
+                    several custom layers that developers build and access using
+                    the Yocto Project on a regular basis.
+                    This set of layers needs to exist and you need to be
+                    familiar with where they reside.
+                    You will need that information when you set up the
+                    code for the web application that "hooks" into your set of
+                    layers.
+                </para>
+
+                <para>
+                    For general information on layers, see the
+                    "<ulink url='&YOCTO_DOCS_BSP_URL;#bsp-layers'>BSP Layers</ulink>"
+                    and
+                    "<ulink url='&YOCTO_DOCS_BSP_URL;#using-the-yocto-projects-bsp-tools'>Using the Yocto Project's BSP Tools</ulink>"
+                    sections in the Yocto Project Board Support Package (BSP)
+                    Developer's Guide.
+                </para>
+            </section>
+
+            <section id='configuring-toaster-to-hook-into-your-layer-source'>
+                <title>Configuring Toaster to Hook Into Your Layer Index</title>
+
+                <para>
+                    If you want Toaster to use your layer index, you must host
+                    the web application in a server to which Toaster can
+                    connect.
+                    You also need to give Toaster the information about your
+                    layer index.
+                    In other words, you have to configure Toaster to use your
+                    layer index.
+                    This section describes two methods by which you can
+                    configure and use your layer index.
+                </para>
+
+                <para>
+                    In the previous section, the code for the OpenEmbedded
+                    Metadata Index (i.e.
+                    <ulink url='http://layers.openembedded.org'></ulink>) was
+                    referenced.
+                    You can use this code, which is at
+                    <ulink url='http://git.yoctoproject.org/cgit/cgit.cgi/layerindex-web/'></ulink>,
+                    as a base to create your own layer index.
+                </para>
+
+                <section id='use-the-administration-interface'>
+                    <title>Use the Administration Interface</title>
+
+                    <para>
+                        Access the administration interface through a
+                        browser by entering the URL of your Toaster instance and
+                        adding "<filename>/admin</filename>" to the end of the
+                        URL.
+                    </para>
+
+                    <para>
+                        The administration interface has a "Layer sources"
+                        section that includes an "Add layer source" button.
+                        Click that button and provide the required information.
+                        Make sure you select "layerindex" as the layer source type.
+                    </para>
+                </section>
+
+                <section id='select-the-toasterconf-json-file'>
+                    <title>Select the <filename>toasterconf.json</filename> File</title>
+
+                    <para>
+                        If you do not want to use the Administration
+                        Interface, you can edit the
+                        <link linkend='toaster-json-files'><filename>toasterconf.json</filename></link>
+                        file and reload it to Toaster.
+                    </para>
+
+                    <para>
+                        When you set up Toaster in Build Mode, you are prompted to
+                        select a Toaster configuration file.
+                        This configuration file is used to set up the initial
+                        configuration values within the Toaster database
+                        including the layer sources.
+                        Three versions of the configuration file exist:
+                        <itemizedlist>
+                            <listitem><para>
+                                The first version of the file is found in the
+                                <filename>conf</filename> directory of the
+                                <filename>meta-yocto</filename> layer
+                                (i.e.
+                                <filename>meta-yocto/conf/toasterconf.json</filename>).
+                                This version contains the default Yocto Project
+                                configuration for Toaster.
+                                You are prompted to select this file during the
+                                Toaster set up process if you had cloned the
+                                <filename>poky</filename> repository (i.e.
+                                <filename>git://git.yoctoproject.org/poky</filename>).
+                                </para></listitem>
+                            <listitem><para>
+                                The second version of the file is in the
+                                <filename>conf</filename> directory of the
+                                <filename>openembedded-core</filename> layer
+                                (i.e. <filename>meta/conf/toasterconf.json</filename>).
+                                This version contains the default OpenEmbedded
+                                configuration for Toaster.
+                                You are prompted to select this file during the
+                                Toaster set up process if you had cloned the
+                                <filename>openembedded-core</filename> repository
+                                (i.e.
+                                <filename>git://git.openembedded.org/openembedded-core</filename>).
+                                </para></listitem>
+                            <listitem><para>
+                                The third version is a sample configuration
+                                useful for when you want to set up a hosted
+                                service in Build Mode.
+                                You can find this version on the
+                                <ulink url='https://wiki.yoctoproject.org/wiki/File:Toasterconf.json.txt.patch'>File:Toasterconf.json.txt.patch</ulink>
+                                wiki page.
+                                </para></listitem>
+                        </itemizedlist>
+                    </para>
+                </section>
+
+                <section id='edit-the-configuration-file'>
+                    <title>Edit the Configuration File</title>
+
+                    <para>
+                        Edit the version of the
+                        <filename>toasterconf.json</filename> file you
+                        used to set up your Toaster instance.
+                        In the file, you will find a section for layer sources
+                        such as the following:
+                        <literallayout class='monospaced'>
+     "layersources": [
+         {
+             "name": "Local Yocto Project",
+             "sourcetype": "local",
+             "apiurl": "../../",
+             "branches": ["HEAD", "master", "fido", "dizzy"],
+             "layers": [
+                 {
+                     "name": "openembedded-core",
+                     "local_path": "meta",
+                     "vcs_url": "remote:origin",
+                     "dirpath": "meta"
+                 },
+                 {
+                     "name": "meta-yocto",
+                     "local_path": "meta-yocto",
+                     "vcs_url": "remote:origin",
+                     "dirpath": "meta-yocto"
+                 },
+                 {
+                     "name": "meta-yocto-bsp",
+                     "local_path": "meta-yocto-bsp",
+                     "vcs_url": "remote:origin",
+                     "dirpath": "meta-yocto-bsp"
+                 }
+
+             ]
+         },
+         {
+             "name": "OpenEmbedded",
+             "sourcetype": "layerindex",
+             "apiurl": "http://layers.openembedded.org/layerindex/api/",
+             "branches": ["master", "fido", "dizzy"]
+         },
+         {
+             "name": "Imported layers",
+             "sourcetype": "imported",
+             "apiurl": "",
+             "branches": ["master", "fido", "dizzy", "HEAD"]
+
+         }
+     ],
+                        </literallayout>
+                        You should add your own layer source to this section by
+                        following the same format used for the "OpenEmbedded"
+                        layer source shown above.
+                    </para>
+
+                    <para>
+                        Give your layer source a name, provide the URL of your
+                        layer source API, use the source type "layerindex", and
+                        indicate which branches from your layer source you want
+                        to make available through Toaster.
+                        For example, the OpenEmbedded layer source makes
+                        available only its "master", "fido", and "dizzy"
+                        branches.
+                    </para>
+
+                    <para>
+                        The branches must match the branch you
+                        set when configuring your releases.
+                        For example, if you configure one release in Toaster
+                        by setting its branch to "branch-one" and you configure
+                        another release in Toaster by setting its branch to
+                        "branch-two", the branches in your layer source should
+                        be "branch-one" and "branch-two" as well.
+                        Doing so creates a connection between the releases
+                        and the layer information from your layer source.
+                        Thus, when users create a project with a given
+                        release, they will see the appropriate layers from
+                        your layer source.
+                        This connection ensures that only layers that are
+                        compatible with the selected project release can be
+                        selected for building.
+                    </para>
+
+                    <para>
+                        Once you have added this information to the
+                        <filename>toasterconf.json</filename> file, save your
+                        changes.
+                    </para>
+
+                    <para>
+                        In a terminal window, navigate to the directory that
+                        contains the Toaster database, which by default is the
+                        root of the Yocto Project
+                        <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
+                        Once you are located in that directory, run the
+                        "<filename>loadconf</filename>" command, which takes as
+                        an argument the full path to the
+                        <filename>toasterconf.json</filename> file you just edited.
+                        For example, if you cloned the
+                        <filename>poky</filename> repository and you edited the
+                        <filename>meta-yocto/conf/toasterconf.json</filename> file,
+                        you would type something like the following:
+                        <literallayout class='monospaced'>
+     $ bitbake/lib/toaster/manage.py loadconf /home/scottrif/poky/meta-yocto/conf/toasterconf.json
+                        </literallayout>
+                        After entering this command, you need to update the
+                        information from the layer index to populate the
+                        Toaster database with the information from your layer
+                        index.
+                        To do that, you should run the
+                        "<filename>lsupdates</filename>" command from the directory
+                        that contains the Toaster database.
+                        Here is an example:
+                        <literallayout class='monospaced'>
+     $ bitbake/lib/toaster/manage.py lsupdates
+                        </literallayout>
+                        If Toaster can reach the API URL, you should see a message
+                        telling you that Toaster is updating the layer source
+                        information.
+                    </para>
+
+                    <para>
+                        Once the information has been updated, verify the new layer
+                        information is available by using the Toaster web interface.
+                        To do that, visit the "All compatible layers" page inside a
+                        Toaster project.
+                        The layers from your layer index should be listed there.
+                    </para>
+                </section>
+            </section>
+        </section>
+    </section>
+
+    <section id='toaster-releases'>
+        <title>Releases</title>
+
+        <para>
+            In the context of Toaster, the term "Release" refers to a set of
+            layers and a BitBake version the OpenEmbedded build system uses
+            to build something.
+            As shipped, Toaster is pre-configured with releases that
+            correspond to Yocto Project release branches.
+            However, you can modify, delete, and create new releases
+            according to your needs.
+            When you create a Toaster project using the web interface,
+            you are asked to choose a "Release."
+            This section provides some background information on releases.
+        </para>
+
+        <section id='toaster-releases-supported'>
+            <title>Pre-Configured Releases</title>
+
+            <para>
+                As shipped, Toaster is configured to use a specific set of
+                releases.
+                Of course, you can always configure Toaster to use any
+                release.
+                For example, you might want your project to build against a
+                specific commit of any of the "out-of-the-box" releases.
+                Or, you might want your project to build against different
+                revisions of OpenEmbedded and BitBake.
+            </para>
+
+            <para>
+                As shipped, Toaster is configured to work with the following
+                releases:
+                <itemizedlist>
+                    <listitem><para><emphasis>Yocto Project 1.7 "Dizzy" or OpenEmbedded "Dizzy":</emphasis>
+                        This release causes your Toaster projects to
+                        build against the head of the dizzy branch at
+                        <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/poky/log/?h=dizzy'></ulink>
+                        or
+                        <ulink url='http://git.openembedded.org/openembedded-core/commit/?h=dizzy'></ulink>.
+                        </para></listitem>
+                    <listitem><para><emphasis>Yocto Project 1.8 "Fido" or OpenEmbedded "Fido":</emphasis>
+                        This release causes your Toaster projects to
+                        build against the head of the fido branch at
+                        <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/poky/log/?h=fido'></ulink>
+                        or
+                        <ulink url='http://git.openembedded.org/openembedded-core/commit/?h=fido'></ulink>.
+                        </para></listitem>
+                    <listitem><para><emphasis>Yocto Project "Master" or OpenEmbedded "Master":</emphasis>
+                        This release causes your Toaster Projects to
+                        build against the head of the master branch, which is
+                        where active development takes place, at
+                        <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/poky/log/'></ulink>
+                        or
+                        <ulink url='http://git.openembedded.org/openembedded-core/log/'></ulink>.
+                        </para></listitem>
+                    <listitem><para><emphasis>Local Yocto Project or Local OpenEmbedded:</emphasis>
+                        This release causes your Toaster Projects to
+                        build against the head of the <filename>poky</filename>
+                        or <filename>openembedded-core</filename> clone you
+                        have local to the machine running Toaster.
+                        </para></listitem>
+                </itemizedlist>
+            </para>
+        </section>
+
+        <section id='toaster-releases-comprised-of'>
+            <title>What Makes Up a Release?</title>
+
+            <para>
+                A release consists of the following:
+                <itemizedlist>
+                    <listitem><para><emphasis>Name:</emphasis>
+                        The name of the release (<filename>name</filename>).
+                        This release name never appears in the the Toaster
+                        web interface.
+                        Consequently, a user never sees the release name.
+                        </para></listitem>
+                    <listitem><para><emphasis>Description:</emphasis>
+                        The textual description of the release
+                        (<filename>description</filename>).
+                        This description is what users encounter when creating
+                        projects with the Toaster web interface.
+                        When you configure your release, be sure to use
+                        a description that sufficiently describes and is
+                        understandable.
+                        If Toaster has more than one release configured, the
+                        release descriptions appear listed in a drop down menu
+                        when a user creates a new project.
+                        If Toaster has only one release configured, all
+                        projects created using the web interface take that
+                        release and the drop down menu does not display in the
+                        Toaster web interface.
+                        </para></listitem>
+                    <listitem><para><emphasis>BitBake:</emphasis>
+                        The Bitbake version (<filename>bitbake</filename>)
+                        used to build layers set in the current release.
+                        This version is described by a name, a Git URL, a
+                        branch in the Git URL, and a directory path in the
+                        Git repository.
+                        As an example, consider the following snippet from
+                        a Toaster JSON configuration file.
+                        This BitBake version uses the master branch from the
+                        OpenEmbedded repository:
+                        <literallayout class='monospaced'>
+     "bitbake" : [
+         {
+             "name": "master",
+             "giturl": "git://git.openembedded.org/bitbake",
+             "branch": "master",
+             "dirpath": ""
+         }
+     ]
+                        </literallayout>
+                        Here is more detail on each of the items that comprise
+                        the BitBake version:
+                        <itemizedlist>
+                            <listitem><para><emphasis>Name:</emphasis>
+                                A string
+                                (<filename>name</filename>) used to refer to
+                                the version of BitBake you are using with
+                                Toaster.
+                                This name is never exposed through Toaster.
+                                </para></listitem>
+                            <listitem><para><emphasis>Git URL:</emphasis>
+                                The URL <filename>giturl</filename>
+                                for the BitBake Git repository cloned
+                                for Toaster projects.
+                                </para></listitem>
+                            <listitem><para><emphasis>Branch:</emphasis>
+                                The Git branch, or revision,
+                                (<filename>branch</filename>) of the BitBake
+                                repository used with Toaster.
+                                </para></listitem>
+                            <listitem><para><emphasis>Directory Path:</emphasis>
+                                The sub-directory of the BitBake repository
+                                (<filename>dirpath</filename>).
+                                If the Git URL includes more than one
+                                repository, you need to set this directory.
+                                If the URL does not include more than a single
+                                repository, you can set
+                                <filename>dirpath</filename> to a null string
+                                (i.e. "").
+                                </para></listitem>
+                        </itemizedlist>
+                        </para></listitem>
+                    <listitem><para><emphasis>Branch:</emphasis>
+                        The branch for the layer source
+                        (<filename>branch</filename>) used with the release.
+                        For example, for the OpenEmbedded layer source, the
+                        "master", "fido", and "dizzy" branches are available.
+                        </para></listitem>
+                    <listitem><para><emphasis>Default Layers:</emphasis>
+                        The set of default layers
+                        (<filename>defaultlayers</filename>) automatically
+                        added to the project configuration when a project is
+                        created.
+                        You can download the recommended configuration
+                        for this case from
+                        <ulink url='&YOCTO_WIKI_URL;/wiki/File:Toasterconf.json.txt.patch'></ulink>.
+                        </para></listitem>
+                    <listitem><para><emphasis>Layer Source Priorities</emphasis>
+                        A specification of
+                        <link linkend='layer-source'>layer source</link>
+                        priorities (<filename>layersourcepriority</filename>).
+                        In order for Toaster to work as intended, the
+                        "Imported layers" layer source should have the highest
+                        priority, which means that layers manually imported by
+                        users with the "Import layer" functionality will
+                        always be visible and available for selection.
+                        </para></listitem>
+                    <listitem><para><emphasis>Help Text:</emphasis>
+                        Help text (<filename>helptext</filename>) that explains
+                        what the release does when selected.
+                        This help text appears below the release drop-down
+                        menu when you create a Toaster project.
+                        The help text should assist users in making the correct
+                        decision regarding the release to use for a given
+                        project.
+                        </para></listitem>
+                </itemizedlist>
+            </para>
+
+            <para>
+                To summarize what comprises a release, consider the following
+                example from a Toaster JSON file.
+                The configuration names the release "master" and sets it to
+                use the master branch of the
+                <filename>openembedded-core</filename> layer.
+                The BitBake version used would be defined as shown earlier
+                in the previous list:
+                <literallayout class='monospaced'>
+     "releases": [
+         {
+             "name": "master",
+             "description": "OpenEmbedded master",
+             "bitbake": "master",
+             "branch": "master",
+             "defaultlayers": [ "openembedded-core" ],
+             "layersourcepriority": { "Imported layers": 99, "Local OpenEmbedded" : 10, "OpenEmbedded" :  0 },
+             "helptext": "Toaster will run your builds using the OpenEmbedded master branch, where active development takes place. This is not a stable branch, so your builds might not work as expected."
+         }
+     ]
+                </literallayout>
+            </para>
+        </section>
+    </section>
+
+    <section id='toaster-json-files'>
+        <title>JSON Files</title>
+
+        <para>
+            If you are going to be using the Toaster in Build Mode, it must
+            be initially configured before use.
+            Configuration customizes layer source settings and Toaster defaults
+            for all users and is performed by the person responsible for
+            Toaster Configuration (i.e  the Toaster Administrator).
+            The Toaster Administrator performs this configuration through the
+            admin web interface.
+        </para>
+
+        <para>
+            To make it easier to initially start Toaster, you can import a
+            pre-defined configuration file using the
+            <link linkend='toaster-command-loadconf'><filename>loadconf</filename></link>
+            command.
+            <note>
+                The configuration file is a JSON-formatted text file with
+                specific fields that Toaster recognizes.
+                It is not a data dump from the database, so it cannot be
+                loaded directly in the database.
+            </note>
+        </para>
+
+        <para>
+            By convention, the supplied configuration files are named
+            <filename>toasterconf.json</filename>.
+            The Toaster Administrator can customize the file prior to loading
+            it into Toaster.
+            In the Local Toaster Build Mode, the system startup script
+            actively looks for compatible configuration files and prompts
+            you to select a file to load if it detects that the database has
+            not been configured.
+        </para>
+
+        <section id='json-file-choices'>
+            <title>Configuration File Choices</title>
+
+            <para>
+                Three versions of the configuration file exist:
+                <itemizedlist>
+                    <listitem><para>
+                        The
+                        <filename>meta-yocto/conf/toasterconf.json</filename>
+                        in the <filename>conf</filename> directory of the
+                        Yocto Project's <filename>meta-yocto</filename> layer.
+                        This version contains the default Yocto Project
+                        configuration for Toaster.
+                        You are prompted to select this file during the Toaster
+                        set up process if you cloned the
+                        <filename>poky</filename> repository (i.e.
+                        <filename>&YOCTO_GIT_URL;/poky</filename>).
+                        </para></listitem>
+                    <listitem><para>
+                        The <filename>meta/conf/toasterconf.json</filename>
+                        in the <filename>conf</filename> directory of the
+                        OpenEmbedded's <filename>openembedded-core</filename>
+                        layer.
+                        This version contains the default OpenEmbedded
+                        configuration for Toaster.
+                        You are prompted to select this file during the Toaster
+                        set up process if you had cloned the
+                        <filename>openembedded-core</filename> repository (i.e.
+                        <filename>git://git.openembedded.org/openembedded-core</filename>).
+                        </para></listitem>
+                    <listitem><para>
+                        The <filename>Toasterconf.json.txt.patch</filename>
+                        located on the
+                        <ulink url='https://wiki.yoctoproject.org/wiki/File:Toasterconf.json.txt.patch'>File:Toasterconf.json.txt.patch</ulink>
+                        wiki page.
+                        This version of the file is useful as a sample
+                        configuration for when you want to set up Toaster as a
+                        hosted service in Build Mode.
+                        </para></listitem>
+                </itemizedlist>
+            </para>
+        </section>
+
+        <section id='json-structure'>
+            <title>File Structure</title>
+
+            <para>
+                The <filename>toasterconf.json</filename> file consists of
+                easily readable areas: configuration, layer sources, BitBake,
+                default, and releases.
+            </para>
+
+            <section id='json-config-area'>
+                <title>Configuration Area</title>
+
+                <para>
+                    This area of the JSON file sets which variables are exposed
+                    to users through the Toaster web interface.
+                    Users can easily edit these variables.
+                </para>
+
+                <para>
+                    The variables you set here are displayed in the
+                    "Configuration variables" page in Toaster.
+                    Minimally, you should set the
+                    <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>
+                    variable, which appears to users as part of the project
+                    page in Toaster.
+                </para>
+
+                <para>
+                    Here is the default <filename>config</filename> area:
+                    <literallayout class='monospaced'>
+     "config": {
+         "MACHINE"      : "qemux86",
+         "DISTRO"       : "poky",
+         "IMAGE_FSTYPES": "ext3 jffs2 tar.bz2",
+         "IMAGE_INSTALL_append": "",
+         "PACKAGE_CLASSES": "package_rpm",
+         "SDKMACHINE"   : "x86_64"
+     },
+                    </literallayout>
+                </para>
+            </section>
+
+            <section id='json-layersources-area'>
+                <title>Layer Sources Area</title>
+
+                <para>
+                    This area of the JSON file defines the
+                    <link linkend='layer-source'>layer sources</link>
+                    Toaster uses.
+                    Toaster reads layer information from layer sources.
+                    Three types of layer sources exist that Toaster
+                    recognizes: Local, LayerIndex, and Imported.
+                </para>
+
+                <para>
+                    The Local layer source reads layers from Git clones
+                    available on your local drive.
+                    Using a local layer source enables you to easily test
+                    Toaster.
+                    <note>
+                        If you are setting up a hosted version of Toaster,
+                        it does not make sense to have a local layer source.
+                    </note>
+                </para>
+
+                <para>
+                    The LayerIndex layer source uses a REST API exposed by
+                    instances of the Layer Index application (e.g the public
+                    <ulink url='http://layers.openembedded.org/'></ulink>)
+                    to read layer data.
+                </para>
+
+                <para>
+                    The Imported layer source is reserved for layer data
+                    manually introduced by the user or Toaster Administrator
+                    through the GUI.
+                    This layer source lets users import their own layers
+                    and build them with Toaster.
+                    You should not remove the imported layer source.
+                </para>
+
+                <para>
+                    Here is the default <filename>layersources</filename> area:
+                    <literallayout class='monospaced'>
+     "layersources": [
+         {
+             "name": "Local Yocto Project",
+             "sourcetype": "local",
+             "apiurl": "../../",
+             "branches": ["HEAD", "master", "fido", "dizzy"],
+             "layers": [
+                 {
+                     "name": "openembedded-core",
+                     "local_path": "meta",
+                     "vcs_url": "remote:origin",
+                     "dirpath": "meta"
+                 },
+                 {
+                     "name": "meta-yocto",
+                     "local_path": "meta-yocto",
+                     "vcs_url": "remote:origin",
+                     "dirpath": "meta-yocto"
+                 },
+                 {
+                     "name": "meta-yocto-bsp",
+                     "local_path": "meta-yocto-bsp",
+                     "vcs_url": "remote:origin",
+                     "dirpath": "meta-yocto-bsp"
+                 }
+
+             ]
+         },
+         {
+             "name": "OpenEmbedded",
+             "sourcetype": "layerindex",
+             "apiurl": "http://layers.openembedded.org/layerindex/api/",
+             "branches": ["master", "fido", "dizzy"]
+         },
+         {
+             "name": "Imported layers",
+             "sourcetype": "imported",
+             "apiurl": "",
+             "branches": ["master", "fido", "dizzy", "HEAD"]
+
+         }
+     ],
+                    </literallayout>
+                </para>
+            </section>
+
+            <section id='json-bitbake-area'>
+                <title>BitBake Area</title>
+
+                <para>
+                    This area of the JSON file defines the version of
+                    BitBake Toaster uses.
+                    As shipped, Toaster is configured to recognize three
+                    versions of BitBake: master, dizzy, and HEAD.
+                </para>
+
+                <para>
+                    Here is the default <filename>bitbake</filename> area:
+                    <literallayout class='monospaced'>
+     "bitbake" : [
+         {
+             "name": "master",
+             "giturl": "remote:origin",
+             "branch": "master",
+             "dirpath": "bitbake"
+         },
+         {
+             "name": "fido",
+             "giturl": "remote:origin",
+             "branch": "fido",
+            "dirpath": "bitbake"
+        },
+        {
+             "name": "dizzy",
+             "giturl": "remote:origin",
+             "branch": "dizzy",
+             "dirpath": "bitbake"
+         },
+         {
+             "name": "HEAD",
+             "giturl": "remote:origin",
+             "branch": "HEAD",
+             "dirpath": "bitbake"
+         }
+     ],
+                    </literallayout>
+                </para>
+            </section>
+
+            <section id='json-default-area'>
+                <title>Default Area</title>
+
+                <para>
+                    This area of the JSON file establishes a default
+                    release used by Toaster.
+                    As shipped, Toaster uses the "master" release.
+                </para>
+
+                <para>
+                    Here is the statement in the JSON file that establishes
+                    the default release:
+                    <literallayout class='monospaced'>
+     "defaultrelease": "master",
+                    </literallayout>
+                </para>
+            </section>
+
+            <section id='json-releases-area'>
+                <title>Releases Area</title>
+
+                <para>
+                    This area of the JSON file defines the versions of the
+                    OpenEmbedded build system Toaster recognizes.
+                    As shipped, Toaster is configured to work with the four
+                    releases described in the
+                    "<link linkend='toaster-releases-supported'>Pre-Configured Releases</link>"
+                    section.
+                </para>
+
+                <para>
+                    Here is the default <filename>releases</filename> area:
+                    <literallayout class='monospaced'>
+     "releases": [
+         {
+             "name": "master",
+             "description": "Yocto Project master",
+             "bitbake": "master",
+             "branch": "master",
+             "defaultlayers": [ "openembedded-core", "meta-yocto", "meta-yocto-bsp"],
+             "layersourcepriority": { "Imported layers": 99, "Local Yocto Project" : 10, "OpenEmbedded" :  0 },
+             "helptext": "Toaster will run your builds using the tip of the &lt;a href=\"http://git.yoctoproject.org/cgit/cgit.cgi/poky/log/\"&gt;Yocto Project master branch&lt;/a&gt;, where active development takes place. This is not a stable branch, so your builds might not work as expected."
+         },
+         {
+             "name": "fido",
+             "description": "Yocto Project 1.8 Fido",
+             "bitbake": "fido",
+             "branch": "fido",
+             "defaultlayers": [ "openembedded-core", "meta-yocto", "meta-yocto-bsp"],
+             "layersourcepriority": { "Imported layers": 99, "Local Yocto Project" : 10, "OpenEmbedded" :  0 },
+             "helptext": "Toaster will run your builds with the tip of the &lt;a href=\"http://git.yoctoproject.org/cgit/cgit.cgi/poky/log/?h=fido\"&gt;Yocto Project 1.8 \"Fido\"&lt;/a&gt; branch."
+         },
+         {
+             "name": "dizzy",
+             "description": "Yocto Project 1.7 Dizzy",
+             "bitbake": "dizzy",
+             "branch": "dizzy",
+             "defaultlayers": [ "openembedded-core", "meta-yocto", "meta-yocto-bsp"],
+             "layersourcepriority": { "Imported layers": 99, "Local Yocto Project" : 10, "OpenEmbedded" :  0 },
+             "helptext": "Toaster will run your builds with the tip of the &lt;a href=\"http://git.yoctoproject.org/cgit/cgit.cgi/poky/log/?h=dizzy\"&gt;Yocto Project 1.7 \"Dizzy\"&lt;/a&gt; branch."
+         },
+         {
+             "name": "local",
+             "description": "Local Yocto Project",
+             "bitbake": "HEAD",
+             "branch": "HEAD",
+             "defaultlayers": [ "openembedded-core", "meta-yocto", "meta-yocto-bsp"],
+             "layersourcepriority": { "Imported layers": 99, "Local Yocto Project" : 10, "OpenEmbedded" :  0 },
+             "helptext": "Toaster will run your builds with the version of the Yocto Project you have cloned or downloaded to your computer."
+         }
+     ]
+                    </literallayout>
+                </para>
+            </section>
+        </section>
+    </section>
+
+    <section id='toaster-useful-commands'>
+        <title>Useful Commands</title>
+
+        <para>
+            In addition to the web user interface and the scripts that start
+            and stop Toaster, command-line commands exist through the
+            <filename>manage.py</filename> management script.
+            You can find general documentation on
+            <filename>manage.py</filename> at the
+            <ulink url='https://docs.djangoproject.com/en/1.7/topics/settings/'>Django</ulink>
+            site.
+            However, several <filename>manage.py</filename> commands have been
+            created that are specific to Toaster and are used to control
+            configuration and back-end tasks.
+            You can locate these commands in the
+            <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>
+            (e.g. <filename>poky</filename>) at
+            <filename>bitbake/lib/manage.py</filename>.
+            This section documents those commands.
+            <note>
+                <para>
+                    When using <filename>manage.py</filename> commands given
+                    a default configuration, you must be sure that your
+                    working directory is set to the
+                    <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
+                    Using <filename>manage.py</filename> commands from the
+                    Build Directory allows Toaster to find the
+                    <filename>toaster.sqlite</filename> file, which is located
+                    in the Build Directory.
+                </para>
+
+                <para>
+                    For non-default database configurations, it is possible
+                    that you can use <filename>manage.py</filename> commands
+                    from a directory other than the Build directory.
+                    To do so, the
+                    <filename>toastermain/settings.py</filename> file must be
+                    configured to point to the correct database backend.
+                </para>
+            </note>
+        </para>
+
+        <section id='toaster-command-buildslist'>
+            <title><filename>buildslist</filename></title>
+
+            <para>
+                The <filename>buildslist</filename> command lists all builds
+                that Toaster has recorded.
+                Access the command as follows:
+                <literallayout class='monospaced'>
+     $ bitbake/lib/toaster/manage.py buildslist
+                </literallayout>
+                The command returns a list, which includes numeric
+                identifications, of the builds that Toaster has recorded in the
+                current database.
+            </para>
+
+            <para>
+                You need to run the <filename>buildslist</filename> command
+                first to identify existing builds in the database before
+                using the
+                <link linkend='toaster-command-builddelete'><filename>builddelete</filename></link>
+                command.
+                For example, assuming default repository and build directory
+                names, the following two commands put you in the
+                <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
+                and then return a list of the current builds, which would
+                be one in this case:
+                <literallayout class='monospaced'>
+     $ cd $HOME/poky/build
+     $ python ../bitbake/lib/toaster/manage.py buildslist
+     1: qemux86 poky core-image-minimal
+                </literallayout>
+            </para>
+        </section>
+
+        <section id='toaster-command-builddelete'>
+            <title><filename>builddelete</filename></title>
+
+            <para>
+                The <filename>builddelete</filename> command deletes data
+                associated with a build.
+                Access the command as follows:
+                <literallayout class='monospaced'>
+     $ bitbake/lib/toaster/manage.py builddelete <replaceable>build_id</replaceable>
+                </literallayout>
+                The command deletes all the build data for the specified
+                <replaceable>build_id</replaceable>.
+                This command is useful for removing old and unused data from
+                the database.
+            </para>
+
+            <para>
+                Prior to running the <filename>builddelete</filename>
+                command, you need to get the ID associated with builds
+                by using the
+                <link linkend='toaster-command-buildslist'><filename>buildslist</filename></link>
+                command.
+            </para>
+        </section>
+
+        <section id='toaster-command-perf'>
+            <title><filename>perf</filename></title>
+
+            <para>
+                The <filename>perf</filename> command measures Toaster
+                performance.
+                Access the command as follows:
+                <literallayout class='monospaced'>
+     $ bitbake/lib/toaster/manage.py perf
+                </literallayout>
+                The command is a sanity check that returns page loading
+                times in order to identify performance problems.
+            </para>
+        </section>
+
+        <section id='toaster-command-checksettings'>
+            <title><filename>checksettings</filename></title>
+
+            <para>
+                The <filename>checksettings</filename> command verifies
+                existing Toaster settings.
+                Access the command as follows:
+                <literallayout class='monospaced'>
+     $ bitbake/lib/toaster/manage.py checksettings
+                </literallayout>
+                In Managed Mode, Toaster uses settings that are based on the
+                database to configure the building tasks.
+                The <filename>checksettings</filename> command verifies that
+                the database settings are valid in the sense that they have
+                the minimal information needed to start a build.
+            </para>
+
+            <para>
+                In order for the <filename>checksettings</filename> command
+                to work, the database must be correctly set up and not have
+                existing data.
+                To be sure the database is ready, you can run the following:
+                <literallayout class='monospaced'>
+     $ bitbake/lib/toaster/mana​ge.py syncdb
+     $ bitbake/lib/toaster/mana​ge.py migrate orm
+     $ bitbake/lib/toaster/mana​ge.py migrate bldcontrol
+                </literallayout>
+                After running these commands, you can run the
+                <filename>checksettings</filename> command.
+            </para>
+        </section>
+
+        <section id='toaster-command-loadconf'>
+            <title><filename>loadconf</filename></title>
+
+            <para>
+                The <filename>loadconf</filename> command loads a Toaster
+                configuration file (JSON file).
+                You must run this on a new database that does not have any
+                data.
+                Running this command on an existing database that has data
+                results in errors.
+                Access the command as follows:
+                <literallayout class='monospaced'>
+     $ bitbake/lib/toaster/manage.py loadconf <replaceable>filepath</replaceable>
+                </literallayout>
+                The <filename>loadconf</filename> command configures a database
+                based on the supplied <filename>toasterconf.json</filename>
+                file.
+                For information on the <filename>toasterconf.json</filename>,
+                see the
+                "<link linkend='toaster-json-files'>JSON Files</link>"
+                section.
+            </para>
+        </section>
+
+        <section id='toaster-command-runbuilds'>
+            <title><filename>runbuilds</filename></title>
+
+            <para>
+                The <filename>runbuilds</filename> command launched
+                scheduled builds.
+                Access the command as follows:
+                <literallayout class='monospaced'>
+     $ bitbake/lib/toaster/manage.py runbuilds
+                </literallayout>
+                The <filename>runbuilds</filename> command checks if
+                scheduled builds exist in the database and then launches them
+                per schedule.
+                The command returns after the builds start but before they
+                complete.
+                The "toasterui" build recorded updates the database when the
+                builds complete.
+            </para>
+        </section>
+    </section>
+</chapter>

documentation/toaster-manual/toaster-manual-setup-and-use.xml

@@ -6,12 +6,6 @@
 
 <title>Setting Up and Using Toaster</title>
 
-    <para>
-        You can set up Toaster as a local instance or as a hosted service.
-        Furthermore, you can use Toaster in Analysis Mode or Build Mode
-        from both set ups.
-    </para>
-
     <section id='using-toaster-in-analysis-mode'>
         <title>Using Toaster in Analysis Mode</title>
 
@@ -41,19 +35,14 @@
                         "<ulink url='&YOCTO_DOCS_QS_URL;#yp-resources'>What You Need and How You Get It</ulink>"
                         section in the Yocto Project Quick Start for information.
                         </para></listitem>
-                    <listitem><para><emphasis>Be Sure Ports are Free:</emphasis>
-                        Make sure that port 8000 and 8200 are free.
-                        In other words, make sure the ports do not have servers
-                        on them.
-                        </para></listitem>
                     <listitem><para><emphasis>Source your Build Environment Setup Script:</emphasis>
                         From your
-                        <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
+                        <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>
                         (e.g. <filename>poky/build</filename>), source the build
-                        environment setup script (i.e.
+                        environment setup script
                         <ulink url="&YOCTO_DOCS_REF_URL;#structure-core-script"><filename>&OE_INIT_FILE;</filename></ulink>
                         or
-                        <ulink url="&YOCTO_DOCS_REF_URL;#structure-memres-core-script"><filename>oe-init-build-env-memres</filename></ulink>).
+                        <ulink url="&YOCTO_DOCS_REF_URL;#structure-memres-core-script"><filename>oe-init-build-env-memres</filename></ulink>.
                         </para></listitem>
                     <listitem><para><emphasis>Start Toaster:</emphasis>
                         From the
@@ -72,13 +61,20 @@
      $ bitbake core-image-minimal
                         </literallayout>
                         </para></listitem>
+                    <listitem><para><emphasis>Open Your Browser:</emphasis>
+                        Open your browser and visit
+                        <filename>http://host:port/toastergui</filename>.
+                        For host and port values, see the output of the
+                        <filename>source toaster start</filename> command.
+                        For information on how to use Toaster, see the
+                        "<link linkend='using-the-toaster-web-interface'>Using the Toaster Web Interface</link>"
+                        section.
+                        </para></listitem>
                 </orderedlist>
             </para>
 
             <para>
-                For information on how to use Toaster, see the
-                "<link linkend='using-the-toaster-interface'>Using the Toaster Interface</link>"
-                section.
+
             </para>
         </section>
 
@@ -86,68 +82,45 @@
             <title>Setting Up a Hosted Service and Running in Analysis Mode</title>
 
             <para>
-                A hosted service resides on a server and allows
+                A hosted service resides on a shared server and allows
                 multiple users to take advantage of Toaster.
-                In a production environment, you might want to have multiple
-                local instances of Toaster, which run on various remote
-                build machines, and have those local instances access and use
-                a single hosted Toaster service.
             </para>
 
             <para>
-                Starting Toaster with the <filename>toaster</filename> command
-                (i.e. the script), causes three things to start:
+                In a production environment, you might want to have multiple
+                local instances of the Toaster Logging Interface running on
+                various remote build machines, and have those local instances
+                access and use a single web server.
+                To do this, you need to do the following:
                 <itemizedlist>
                     <listitem><para>
-                        The BitBake server.
-                        </para></listitem>
-                    <listitem><para>
-                        The Toaster User Interface, which connects to the
-                        BitBake server on one side and to the SQL
-                        database on the other side.
+                        Maintain a common SQL database.
                         </para></listitem>
                     <listitem><para>
-                        The web server, which reads the database and displays
-                        the web user interface.
+                        Set up separate instances of BitBake servers
+                        and Toaster Logging Interfaces for each of those
+                        separate BitBake servers.
                         </para></listitem>
                 </itemizedlist>
-                Rather than starting Toaster with the script, you can set up
-                and start multiple instances of Toaster by manually starting
-                as many or few of these three components across your
-                environment.
-                This is possible because it is not required that Toaster starts
-                all three of its separate components in order to run.
-                Minimally, a local instance of Toaster requires just one of the
-                components.
             </para>
 
             <para>
-                The concepts for setting up multiple local instances of
-                Toaster that share a single hosted service revolve
-                around maintaining a common SQL database and Web server that
-                shows data from that common database as well as setting up
-                separate local instances of BitBake servers and Toaster user
-                interfaces for each of those separate BitBake build
-                directories.
-            </para>
-
-            <para>
-                The common SQL database and the Web server show data from
+                The common SQL database allows the Web server to show data from
                 all the various BitBake builds.
                 Setting the SQL database outside of any
                 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
-                maintains a separation layer between the various local builds
-                and the common database.
-                The database is persistent because the logging database is set
-                up external to the BitBake database server (e.g. MySQL).
-                It is not even necessary to run the BitBake servers, the SQL
-                server, and the Web server on the same machine.
-                Each component can be run on its own machine.
+                maintains a separation between the various builds.
+                The BitBake servers, the SQL server, and the Web server or
+                servers can be run on separate machines.
             </para>
 
             <para>
                 Follow these steps to set up and run a hosted service and run
                 Toaster in Analysis Mode:
+                <note>
+                    The steps assume a Toaster installation path of
+                    <filename>/opt/bitbake/</filename>.
+                </note>
                 <orderedlist>
                     <listitem><para><emphasis>Prepare your Build System:</emphasis>
                         Be sure your system has the Toaster requirements
@@ -162,71 +135,153 @@
                         "<ulink url='&YOCTO_DOCS_QS_URL;#yp-resources'>What You Need and How You Get It</ulink>"
                         section in the Yocto Project Quick Start for information.
                         </para></listitem>
-                    <listitem><para><emphasis>Be Sure Ports are Free:</emphasis>
-                        Make sure that port 8000 and 8200 are free.
-                        In other words, make sure the ports do not have servers
-                        on them.
-                        </para></listitem>
-                    <listitem><para><emphasis>Set up the SQL Logging Server and the Web Server:</emphasis>
-                        You can use any SQL server out of the box (e.g.
-                        <filename>mysgl-server</filename> for an Ubuntu build
-                        system).
-                        <note>
-                            If you are concerned about performance, you might
-                            want to hand-tune the server.
-                        </note>
-                        You must set up proper username and password access on
-                        the shared server for everyone that will be using
-                        Toaster.
-                        You need administration rights for the
-                        <filename>mysql</filename> root account, which is not
-                        the same thing as root access on the machine.</para>
-                        <para>Clone a separate, local Git repository of the
-                        Toaster master branch to use for running the Web
-                        server.
-                        The Git repository for Toaster is part of the
-                        Yocto Project
-                        <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
-                        Consequently, you just need to set up a separate
-                        local clone of the Yocto Project Source Directory
-                        (e.g. <filename>poky</filename>):
+                    <listitem><para><emphasis>Install and Set up the Database Server:</emphasis>
+                        You can use any SQL server out of the box.
+                        It is recommended that you use
+                        <filename>mysql-server</filename> because it has
+                        the advantages of advanced SQL features along with a
+                        fast and reliable database.
+                        However, setting up <filename>mysql-server</filename>
+                        is more complex and might require a Database
+                        Administrator to tune it.</para>
+                        <para>Another supported database backend is
+                        <filename>sqlite3</filename>.
+                        With <filename>sqlite3</filename>, you have the
+                        advantage of no configuration and an easy installation.
+                        However, Toaster still requires direct access to the
+                        backend.
+                        The <filename>sqlite</filename> backend is also slower
+                        as compared to <filename>mysql-server</filename>, and
+                        has no transactional support.</para>
+                        <para>You should set up proper username and password
+                        access on the shared database for everyone that will
+                        be using Toaster.
+                        You need administrator rights for the root account,
+                        which is not the same thing as root access on the
+                        machine.
+                        Here is an example that installs
+                        <filename>mysql-server</filename> and sets up
+                        some user accounts and the database.
+                        <literallayout class='monospaced'>
+     $ apt-get install mysql-server
+     $ mysql -u root
+     mysql> CREATE USER 'newuser'@'localhost' IDENTIFIED BY 'password';
+     mysql> GRANT ALL PRIVILEGES ON * . * TO 'newuser'@'localhost';
+     mysql> GRANT ALL PRIVILEGES ON * . * TO 'newuser'@'localhost';
+     mysql> CREATE DATABASE 'toaster';
+                        </literallayout>
+                        You need a separate clone of the
+                        <ulink url='&YOCTO_DOCS_DEV_URL;#source-repositories'>Source Repositories</ulink>
+                        for the Database Server.
+                        This clone is only used for getting the latest Toaster
+                        files.
+                        You can set this up using the following Git command.
+                        Be sure to set up the directory outside of any
+                        Build Directories.
                         <literallayout class='monospaced'>
      $ git clone git://git.yoctoproject.org/poky
                         </literallayout>
-                        You do not perform builds on this tree.
-                        You need to create this local repository away from any
-                        build areas.</para>
-                        <para>In the separately cloned tree for the Web server,
+                        In the separately cloned tree for the Database Server,
                         edit the
                         <filename>bitbake/lib/toaster/toastermain/settings.py</filename>
                         file so that the <filename>DATABASES</filename> value
                         points to the previously created database server.
                         Use the username and password established
-                        earlier.</para>
-                        <para>Run the database sync scripts to create the
-                        needed tables as follows:
+                        earlier.
+                        Here is an example:
+                        <literallayout class='monospaced'>
+     $ cat /opt/bitbake/lib/toaster/toastermain/settings.py
+        ...
+     DATABASES = {
+         'default': {
+             'ENGINE': 'django.db.backends.mysql',
+             'NAME': 'toaster',
+             'USER': 'newuser',
+             'PASSWORD': 'password',
+             'HOST': '192.168.0.25',
+             'PORT': '3306',
+         }
+        ...
+                        </literallayout>
+                        </para></listitem>
+                    <listitem><para><emphasis>Install and Set Up the Web Server:</emphasis>
+                        For a production environment, it is recommended that
+                        you install and set up a front-end web server.
+                        This server allows for load balancing and
+                        multi-threading over Toaster and
+                        <filename>django</filename> WSGI.
+                        Here is an example that uses Apache web server.
+                        <literallayout class='monospaced'>
+     $ apt-get install apache2 libapache2-mod-wsgi
+     $ a2enmod wsgi
+     $ cat /etc/apache2/sites-available/000-default.conf
+
+        ...
+
+     # the WSGIPythonPath is global
+     WSGIPythonPath /opt/bitbake/lib/toaster/
+
+        ...
+
+     #snip - in VirtualHost
+     WSGIScriptAlias / /opt/bitbake/lib/toaster/toastermain/wsgi.py
+
+     &lt;Directory //opt/bitbake/lib/toaster/toastermain/&gt;
+         &lt;Files wsgi.py&gt;
+             Require all granted
+         &lt;/Files&gt;
+     &lt;/Directory&gt;
+
+        ...
+                        </literallayout>
+                        You need to collect static media from Toaster and
+                        continue configuring Apache to serve that static
+                        media:
                         <literallayout class='monospaced'>
-     $ python bitbake/lib/toaster/manage.py syncdb
-     $ python bitbake/lib/toaster/manage.py migrate orm
+     $ mkdir /var/www.html/static &amp;&amp; cd /var/www.html/static
+     $ /opt/bitbake/lib/toaster/manage.py collectstatic
+     $ cat /etc/apache2/sites-available/000-default.conf
+
+        ...
+
+     # in VirtualHost, AHEAD of the WSGIScriptAlias definition
+     Alias /static/ /var/www.html/static/
+
+     &lt;Directory /var/www.html/static/&gt;
+     Require all granted
+     &lt;/Directory&gt;
+
+        ...
+
+     WSGIScript Alias / /opt/bitbake/lib/toaster/toastermain/wsgi.py
+
+        ...
                         </literallayout>
-                        You can start the Web server in the foreground or the
-                        background using these commands, respectively:
+                        </para></listitem>
+                    <listitem><para><emphasis>Start Toaster:</emphasis>
+                        Synchronize the databases for toaster, and then start
+                        up the web server.
+                        Here is an example that continues with the assumed
+                        components from the previous steps:
                         <literallayout class='monospaced'>
-     $ python bitbake/lib/toaster/manage.py runserver
-     $ nohup python bitbake/lib/toaster/manage.py runserver 2>toaster_web.log >toaster_web.log &amp;
+     $ /opt/bitbake/lib/toaster/manage.py syncdb
+     $ /opt/bitbake/lib/toaster/manage.py migrate orm
+     $ /opt/bitbake/lib/toaster/manage.py migrate bldcontrol
+
+     $ service apache2 restart
                         </literallayout>
+                        You can find general documentation on
+                        <filename>manage.py</filename> at the
+                        <ulink url='https://docs.djangoproject.com/en/1.7/ref/django-admin/'>Django</ulink>
+                        site.
+                        For reference information on Toaster-specific
+                        <filename>manage.py</filename> commands,
+                        see the
+                        "<link linkend='toaster-useful-commands'>Useful Commands</link>"
+                        section.
                         </para></listitem>
                     <listitem><para><emphasis>Enable Build Logging to the Common SQL Server for Each Build Directory you are Using:</emphasis>
-                        For each build system that will be using Toaster and
-                        the shared SQL server, you need to edit the
-                        <filename>bitbake/lib/toaster/toastermain/settings.py</filename>
-                        file to alter the <filename>DATABASES</filename> value
-                        so that it points to the common SQL logging server.
-                        <note><title>REVIEWER NOTE</title>
-                            I don't see how to do this from the Wiki.
-                            I need more clarification.
-                        </note></para>
-                        <para>In the Build Directory, create the required
+                        In the Build Directory, create the required
                         <filename>conf/toaster.conf</filename> file as
                         described in
                         <ulink url='https://wiki.yoctoproject.org/wiki/Setting_up_a_local_instance_of_Toaster'>BitBake Extra Options</ulink>.
@@ -240,24 +295,16 @@
      INHERIT += "buildhistory"
      BUILDHISTORY_COMMIT = "1"
                         </literallayout>
-                        Start the BitBake server using the following command:
+                        You also need to point to the database.
+                        You can do this by exporting the
+                        <filename>DATABASE_URL</filename> variable as follows:
                         <literallayout class='monospaced'>
-     $ bitbake &dash;&dash;postread conf/toaster.conf &dash;&dash;server-only -t xmlrpc -B localhost:0 &amp;&amp; export BBSERVER=localhost:-1
+     export DATABASE_URL=mysql://<replaceable>newuser</replaceable>:<replaceable>password</replaceable>@192.168.0.25:3306/toaster
                         </literallayout>
-                        Start the logging user interface using the following
-                        command:
-                        <literallayout class='monospaced'>
-     $ nohup bitbake &dash;&dash;observe-only -u toasterui >toaster_ui.log &amp;
-                        </literallayout>
-                        <note>
-                            No hard-coded ports are used as there is enough code
-                            to run <filename>autodiscovery</filename>
-                            for ports to prevent collisions.
-                        </note>
                         </para></listitem>
                     <listitem><para><emphasis>Source your Build Environment Setup Script:</emphasis>
                         From your
-                        <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
+                        <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>
                         on each of the build systems,
                         (e.g. <filename>poky/build</filename>), source the
                         build environment setup script (i.e.
@@ -265,6 +312,26 @@
                         or
                         <ulink url="&YOCTO_DOCS_REF_URL;#structure-memres-core-script"><filename>oe-init-build-env-memres</filename></ulink>).
                         </para></listitem>
+                    <listitem><para><emphasis>Start the BitBake Server:</emphasis>
+                        Start the BitBake server using the following command:
+                        <literallayout class='monospaced'>
+     $ bitbake --postread conf/toaster.conf --server-only -t xmlrpc -B localhost:0 &amp;&amp; export BBSERVER=localhost:-1
+                        </literallayout>
+                        </para></listitem>
+                    <listitem><para><emphasis>Start the Logging Server:</emphasis>
+                        Start the Toaster Logging Interface using the following
+                        command:
+                        <literallayout class='monospaced'>
+     $ nohup bitbake --observe-only -u toasterui >toaster_ui.log &amp;
+                        </literallayout>
+                        <note>
+                            No hard-coded ports are used in the BitBake options
+                            as there is enough code to run
+                            <filename>autodiscovery</filename> for BitBake
+                            ports.
+                            Doing so prevents collisions.
+                        </note>
+                        </para></listitem>
                     <listitem><para><emphasis>Start Builds Using BitBake:</emphasis>
                         Use the <filename>bitbake</filename> command to start a
                         build on a build system.
@@ -284,8 +351,9 @@
             </para>
 
             <para>
-                For information on how to use Toaster, see the
-                "<link linkend='using-the-toaster-interface'>Using the Toaster Interface</link>"
+                For information on how to use the Toaster web interface,
+                see the
+                "<link linkend='using-the-toaster-web-interface'>Using the Toaster Web Interface</link>"
                 section.
             </para>
         </section>
@@ -303,65 +371,607 @@
         <section id='setting-up-locally-and-running-in-build-mode'>
             <title>Setting Up Locally and Running in Build Mode</title>
 
-            <note><title>REVIEWER NOTE</title>
-                I need the information on how to do this.
-            </note>
+            <para>
+                Follow these steps to set up a local instance of Toaster and
+                then run in Build Mode:
+                <orderedlist>
+                    <listitem><para><emphasis>Prepare your Build System:</emphasis>
+                        Be sure your system has the Toaster requirements
+                        by following the steps in the
+                        "<link linkend='toaster-establishing-toaster-system-dependencies'>Establishing Toaster System Dependencies</link>"
+                        section.
+                        </para></listitem>
+                    <listitem><para><emphasis>Get Set Up to Use the Yocto Project:</emphasis>
+                        Get the requirements set up so that you can use the
+                        Yocto Project to build images.
+                        See the
+                        "<ulink url='&YOCTO_DOCS_QS_URL;#yp-resources'>What You Need and How You Get It</ulink>"
+                        section in the Yocto Project Quick Start for information.
+                        </para></listitem>
+                    <listitem><para><emphasis>Start Toaster:</emphasis>
+                        From the root of the source directory (e.g
+                        <filename>poky/</filename>), run the following command:
+                        <literallayout class='monospaced'>
+     $ bitbake/bin/toaster
+                        </literallayout>
+                        </para></listitem>
+                    <listitem><para><emphasis>Create a Superuser:</emphasis>
+                        Django will ask you if you want to create a superuser.
+                        You can skip this step, but it is recommended that you
+                        create a superuser.
+                        You can use the superuser to access the Django
+                        administration interface and make changes to the
+                        Toaster configuration.
+                        </para></listitem>
+                    <listitem><para><emphasis>Select the Build Log Directory:</emphasis>
+                        Toaster asks you to specify the directory where you
+                        want to store the build log files.
+                        Choosing a directory for these files makes sure they
+                        are always available to you.
+                        If you do not choose a directory, the logs can
+                        disappear (e.g. deleting the Build Directory).</para>
+                        <para>When Toaster prompts you for the Build Log
+                        directory, you can select the suggested default
+                        or provide a path to a different directory.
+                        </para></listitem>
+                    <listitem><para><emphasis>Specify the Layer Checkout Directory:</emphasis>
+                        Toaster asks you to specify the directory into which
+                        layers are checked out.
+                        Toaster clones any layers needed for your builds
+                        inside this directory.</para>
+                        <para>When Toaster prompts you for the Layer
+                        checkout directory, you can select the suggested
+                        default or provide a path to a different directory.
+                        </para></listitem>
+                    <listitem><para><emphasis>Specify the Build Directory Path:</emphasis>
+                        Toaster asks you to specify the path to the
+                        Build Directory.
+                        You can select the suggested default or provide a
+                        path to a different directory.
+                        </para></listitem>
+                    <listitem><para><emphasis>Choose Whether or not to Import a Default Toaster Configuration File:</emphasis>
+                        Toaster asks you if you want to import a default
+                        Toaster configuration file.
+                        Toaster configurations are stored in
+                        JSON files called
+                        <filename>toasterconf.json</filename> and supports
+                        several types.
+                        For information on JSON files, see the
+                        "<link linkend='toaster-json-files'>JSON Files</link>"
+                        section.</para>
+                        <para>You can skip importing a configuration file
+                        by entering "0" at the prompt.
+                        However, it is recommended that you import one of the
+                        configuration files listed during this step.
+                        You can always amend the imported configuration during
+                        a later stage through the Django administration
+                        interface.</para>
+                        <para>For general information on Django, see the
+                        available
+                        <ulink url='https://docs.djangoproject.com/en/1.7/'>documentation</ulink>.
+                        You can also find information on Toaster-specific
+                        <filename>manage.py</filename> commands in the
+                        "<link linkend='toaster-useful-commands'>Useful Commands</link>"
+                        section.
+                        </para></listitem>
+                    <listitem><para><emphasis>Open the Browser:</emphasis>
+                        If no browser window appears, open your favorite
+                        browser and enter the following:
+                        <literallayout class='monospaced'>
+     http://localhost:8000/toastergui
+                        </literallayout>
+                        You can now use the Toaster web interface.
+                        </para></listitem>
+                </orderedlist>
+            </para>
         </section>
 
         <section id='setting-up-a-hosted-service-and-running-in-build-mode'>
             <title>Setting Up a Hosted Service and Running in Build Mode</title>
 
-            <note><title>REVIEWER NOTE</title>
-                Right now, the
-                <ulink url='https://wiki.yoctoproject.org/wiki/Setting_up_a_hosted_managed_mode_for_Toaster'>WIKI PAGE</ulink>
-                has some information on this but I don't understand it.
-                I need more information.
-            </note>
+            <para>
+                Follow these steps to set up a hosted service and run Toaster
+                in Build Mode:
+                <orderedlist>
+                    <listitem><para><emphasis>Prepare your Build System:</emphasis>
+                        Be sure your system has the Toaster requirements
+                        by following the steps in the
+                        "<link linkend='toaster-establishing-toaster-system-dependencies'>Establishing Toaster System Dependencies</link>"
+                        section.
+                        </para></listitem>
+                    <listitem><para><emphasis>Get Set Up to Use the Yocto Project:</emphasis>
+                        Get the requirements set up so that you can use the
+                        Yocto Project to build images.
+                        See the
+                        "<ulink url='&YOCTO_DOCS_QS_URL;#yp-resources'>What You Need and How You Get It</ulink>"
+                        section in the Yocto Project Quick Start for information.
+                        </para></listitem>
+                    <listitem><para><emphasis>Be Sure Management is Enabled:</emphasis>
+                        If you are running Toaster under Apache, you need to
+                        be sure management is enabled.
+                        To enable management, set
+                        <filename>MANAGED</filename> to "True" by adding
+                        the following to the
+                        <filename>bitbake/lib/toaster/settings.py</filename>
+                        file:
+                        <literallayout class='monospaced'>
+     MANAGED="True"
+                        </literallayout>
+                        </para></listitem>
+                    <listitem><para><emphasis>Configure the Build Environment:</emphasis>
+                        Configure the build environment by running the
+                        following:
+                        <literallayout class='monospaced'>
+     bitbake/lib/toaster/manage.py checksettings
+                        </literallayout>
+                        For reference information on Toaster-specific
+                        <filename>manage.py</filename> commands, see the
+                        "<link linkend='toaster-useful-commands'>Useful Commands</link>"
+                        section.
+                        </para></listitem>
+                    <listitem><para><emphasis>Load a Configuration File:</emphasis>
+                        Load a configuration file by running the following:
+                        <literallayout class='monospaced'>
+     bitbake/lib/toaster/manage.py loadconf <replaceable>path-to-toasterconf.json-file</replaceable>
+                        </literallayout>
+                        For reference information on Toaster-specific
+                        <filename>manage.py</filename> commands, see the
+                        "<link linkend='toaster-useful-commands'>Useful Commands</link>"
+                        section.
+                        </para></listitem>
+                    <listitem><para><emphasis>Set Up Toaster for Normal Usage:</emphasis>
+                        You need to configure each build environment, layer
+                        sources, and BitBake versions.</para>
+                        <para>Verify that your releases have been loaded correctly by
+                        using the Toaster web interface to create a new
+                        project.
+                        Check the "Releases" dropdown menu to be sure your
+                        newly specified releases exist.</para>
+                        <para>If you want to use the administration interface
+                        for this step, here is a set of example commands
+                        with some descriptions as an example:
+                        <literallayout class='monospaced'>
+     # Create the user under which the builds will run
+     $ adduser poky
+
+     # Bring up the administration interface
+     $xdg-open http://<replaceable>server-address</replaceable>/admin/
+
+     # Login with the admin user previously created
+
+     # Go to the BuildEnvironment object in Build Environments and
+     # set address to local host, sourcedir to /home/poky, and
+     # builddir to /home/pokybuild.
+     #
+     # Save your changes and exit
+
+     # Go to Home, Layer Sources and select add Layer Source
+     # Name: OpenEmbedded, Sourcetype: layerindex,
+     # Apiurl: http://layers openembedded.org/layerindex/api/
+     # Save your changes and exit
+
+     # Go to Home, Bitbake Versions, Add bitbake version;
+     # Take version information from: http://git.openembedded.org/bitbake/refs/heads,
+     # This example assumes "master" version.
+     # set Name: master, Giturl git://git.openembedded.org/bitbake
+     # branch master, dirpath /
+     # Save your changes and exit
+                        </literallayout>
+                        You also need to configure the project releases, the
+                        default variables, and update information from the
+                        layer index.
+                        Continuing with the example:
+                        <literallayout class='monospaced'>
+     # Go to Home, Releases, Add release
+     # set Name: master, Description: Current master release, select Bitbake Version,
+     # and Branch: master
+     # Save your changes and exit
+
+     # Go to Home, Toaster Settings, select the Setting for DEFAULT_RELEASE
+     # set Helptext: This selects the default release., Value: master
+     # Save your changes and exit
+
+     # Go to Home, Bitbake Versions, Add bitbake version;
+     # take version infor from : http://git.openembedded.org/bitbake/refs/heads,
+     # this manual assumes the master version
+     # set Name: master, Giturl git://git.openembedded.org/bitbake
+     # branch master, dirpath /
+     # Save your changes and exit
+
+     # Update the information
+     # bitbake/lib/toaster/manage.py lsupdates
+                        </literallayout>
+                        For reference information on Toaster-specific
+                        <filename>manage.py</filename> commands, see the
+                        "<link linkend='toaster-useful-commands'>Useful Commands</link>"
+                        section.
+                        </para></listitem>
+                    <listitem><para><emphasis>Install and Set up the Database Server:</emphasis>
+                        You can use any SQL server out of the box.
+                        It is recommended that you use
+                        <filename>mysql-server</filename> because it has
+                        the advantages of advanced SQL features along with a
+                        fast and reliable database.
+                        However, setting up <filename>mysql-server</filename>
+                        is more complex and might require a Database
+                        Administrator to tune it.</para>
+                        <para>Another supported database backend is
+                        <filename>sqlite3</filename>.
+                        With <filename>sqlite3</filename>, you have the
+                        advantage of no configuration and an easy installation.
+                        However, Toaster still requires direct access to the
+                        backend.
+                        The <filename>sqlite</filename> backend is also slower
+                        as compared to <filename>mysql-server</filename>, and
+                        has no transactional support.</para>
+                        <para>You should set up proper username and password
+                        access on the shared database for everyone that will
+                        be using Toaster.
+                        You need administrator rights for the root account,
+                        which is not the same thing as root access on the
+                        machine.
+                        Here is an example that installs
+                        <filename>mysql-server</filename> and sets up
+                        some user accounts and the database.
+                        <literallayout class='monospaced'>
+     $ apt-get install mysql-server
+     $ mysql -u root
+     mysql> CREATE USER 'newuser'@'localhost' IDENTIFIED BY 'password';
+     mysql> GRANT ALL PRIVILEGES ON * . * TO 'newuser'@'localhost';
+     mysql> GRANT ALL PRIVILEGES ON * . * TO 'newuser'@'localhost';
+     mysql> CREATE DATABASE 'toaster';
+                        </literallayout>
+                        You need a separate clone of the
+                        <ulink url='&YOCTO_DOCS_DEV_URL;#source-repositories'>Source Repositories</ulink>
+                        for the Database Server.
+                        This clone is only used for getting the latest Toaster
+                        files.
+                        You can set this up using the following Git command.
+                        Be sure to set up the directory outside of any
+                        Build Directories.
+                        <literallayout class='monospaced'>
+     $ git clone git://git.yoctoproject.org/poky
+                        </literallayout>
+                        In the separately cloned tree for the Database Server,
+                        edit the
+                        <filename>bitbake/lib/toaster/toastermain/settings.py</filename>
+                        file so that the <filename>DATABASES</filename> value
+                        points to the previously created database server.
+                        Use the username and password established
+                        earlier.
+                        Here is an example:
+                        <literallayout class='monospaced'>
+     $ cat /opt/bitbake/lib/toaster/toastermain/settings.py
+        ...
+     DATABASES = {
+         'default': {
+             'ENGINE': 'django.db.backends.mysql',
+             'NAME': 'toaster',
+             'USER': 'newuser',
+             'PASSWORD': 'password',
+             'HOST': '192.168.0.25',
+             'PORT': '3306',
+         }
+        ...
+                        </literallayout>
+                        </para></listitem>
+                    <listitem><para><emphasis>Create the Database</emphasis>
+                        Use the following commands to create the default
+                        database structure:
+                        <literallayout class='monospaced'>
+     $ bitbake/lib/toaster/manage.py syncdb
+     $ bitbake/lib/toaster/manage.py migrate orm
+     $ bitbake/lib/toaster/manage.py migrate bldcontrol
+                        </literallayout>
+                        The interface asks you if you want to create a
+                        superuser.
+                        Do not skip this step.
+                        You will use the superuser account to access the
+                        administration interface and make changes to the
+                        Toaster configuration.
+                        </para></listitem>
+                    <listitem><para><emphasis>Select Where the Build Process Takes Place:</emphasis>
+                        You need to create three directories for storing
+                        build artifacts, downloading sources, and running
+                        builds.
+                        All three directories need to be writable by
+                        the "poky" user.
+                        The build artifacts directory needs to readable by the
+                        apache user.
+                        You also need free disk space in the range of
+                        100 Gbytes.
+                        Following are three suggested directories:
+                        <literallayout class='monospaced'>
+     /home/poky/buildartifacts/
+     /home/poky/build/
+     /home/poky/sources/
+                        </literallayout>
+                        </para></listitem>
+                    <listitem><para><emphasis>Set Up the <filename>toasterconf.json</filename> File:</emphasis>
+                        Download the <filename>toasterconf.json</filename> file
+                        from the
+                        <ulink url='https://wiki.yoctoproject.org/wiki/File:Toasterconf.json.txt.patch'>File:Toasterconf.json.txt.patch</ulink>
+                        wiki page and edit it to suit your environment.
+                        For information on the relevant sections of the file,
+                        see the
+                        "<link linkend='toaster-json-files'>JSON Files</link>"
+                        section.
+                        </para></listitem>
+                    <listitem><para><emphasis>Check the Toaster Settings:</emphasis>
+                        You can check the Toaster settings by running this
+                        command:
+                        <literallayout class='monospaced'>
+     $ bitbake/lib/toaster/manage.py checksettings
+                        </literallayout>
+                        When prompted, paste in the directory paths created
+                        previously during Step 9.
+                        Alternatively, you can select the edited
+                        <filename>toasterconf.json</filename> file set up in
+                        Step 5.
+                        </para></listitem>
+                    <listitem><para><emphasis>Install and Set Up the Web Server:</emphasis>
+                        For a production environment, it is recommended that
+                        you install and set up a front-end web server.
+                        This server allows for load balancing and
+                        multi-threading over Toaster and
+                        <filename>django</filename> WSGI.
+                        Here is an example that uses Apache web server:
+                        <literallayout class='monospaced'>
+     $ apt-get install apache2 libapache2-mod-wsgi
+     $ a2enmod wsgi
+     $ cat /etc/apache2/sites-available/000-default.conf
+
+        ...
+
+     # the WSGIPythonPath is global
+     WSGIPythonPath /opt/bitbake/lib/toaster/
+
+        ...
+
+     #snip - in VirtualHost
+     WSGIScriptAlias / /opt/bitbake/lib/toaster/toastermain/wsgi.py
+
+     &lt;Directory //opt/bitbake/lib/toaster/toastermain/&gt;
+         &lt;Files wsgi.py&gt;
+             Require all granted
+         &lt;/Files&gt;
+     &lt;/Directory&gt;
+
+        ...
+                        </literallayout>
+                        You need to collect static media from Toaster and
+                        continue configuring Apache to serve that static
+                        media:
+                        <literallayout class='monospaced'>
+     $ mkdir /var/www.html/static &amp;&amp; cd /var/www.html/static
+     $ /opt bitbake/lib/toaster/manage.py collectstatic
+     $ cat /etc/apache2/sites-available/000-default.conf
+
+        ...
+
+     # in VirtualHost, AHEAD of the WSGIScriptAlias definition
+     Alias /static/ /var/www.html/static/
+
+     &lt;Directory /var/www.html/static/&gt;
+     Require all granted
+     &lt;/Directory&gt;
+
+        ...
+
+     WSGIScript Alias / /opt/bitbake/lib/toaster/toastermain/wsgi.py
+
+        ...
+                        </literallayout>
+                        </para></listitem>
+                    <listitem><para><emphasis>Start Toaster:</emphasis>
+                        Synchronize the databases for toaster, and then start
+                        up the web server.
+                        Here is an example that continues with the assumed
+                        components from the previous steps:
+                        <literallayout class='monospaced'>
+     $ /opt/bitbake/lib/toaster/manage.py syncdb
+     $ /opt/bitbake/lib/toaster/manage.py migrate orm
+     $ /opt/bitbake/lib/toaster/manage.py migrate bldcontrol
+
+     $ service apache2 restart
+                        </literallayout>
+                        For reference information on the
+                        <filename>manage.py</filename> commands used here,
+                        see the
+                        "<link linkend='toaster-useful-commands'>Useful Commands</link>"
+                        section.
+                        </para></listitem>
+                    <listitem><para><emphasis>Set up Build Control and Open the Web Interface:</emphasis>
+                        You need to run the build control manager.
+                        You can do this as shown in the following example:
+                        <literallayout class='monospaced'>
+     # as the "poky" user, start the runbuilds command in a loop (or put it in crontab!)
+     $ sudo -i -u poky
+     $ while true; do /opt/bitbake/lib/toaster/manage.py runbuilds; sleep 10; done
+
+     # open up the web interface
+     $ xdg-open http://[server-address]/toastergui/
+                        </literallayout>
+                        It is suggested that you enable build control by
+                        setting <filename>runbuilds</filename> in the
+                        <filename>crontab</filename> as follows:
+                        <literallayout class='monospaced'>
+     $ crontab -l
+     * * * * *  /opt/bitbake/lit/toaster/manage.py runbuilds
+                        </literallayout>
+                        </para></listitem>
+                    <listitem><para><emphasis>Open the Browser:</emphasis>
+                        Once the Apache server is running, connect to it with
+                        your favorite browser and verify that the Toaster
+                        interface comes up.
+                        You can track accesses and errors in the Apache
+                        service logs:
+                        <literallayout class='monospaced'>
+     http://localhost:8000/toastergui
+                        </literallayout>
+                        You can now use the Toaster web interface.
+                        </para></listitem>
+                </orderedlist>
+            </para>
         </section>
     </section>
 
-    <section id='using-the-toaster-interface'>
-        <title>Using the Toaster Interface</title>
+    <section id='using-the-toaster-web-interface'>
+        <title>Using the Toaster Web Interface</title>
 
         <para>
-            The Toaster interface allows you to examine the following:
+            The Toaster web interface allows you to do the following:
             <itemizedlist>
                 <listitem><para>
-                    Outcome of the build, errors and warnings thrown
+                    Browse all OpenEmbedded layers available for your
+                    selected version of the build system
+                    </para></listitem>
+                <listitem><para>
+                    Import your own layers for building.
                     </para></listitem>
                 <listitem><para>
-                    Packages included in an image
+                    Add and remove layers from your configuration.
                     </para></listitem>
                 <listitem><para>
-                    Image directory structure
+                    Set configuration variables.
                     </para></listitem>
                 <listitem><para>
-                    Build configuration
+                    Select a target or multiple targets to build.
                     </para></listitem>
                 <listitem><para>
-                    Recipes and packages built
+                    Start your builds.
                     </para></listitem>
                 <listitem><para>
-                    Full dependency chain for tasks, recipes and packages
+                    See what was built (recipes and packages) and what
+                    packages were installed into your final image.
                     </para></listitem>
                 <listitem><para>
-                    Tasks run by the build system
+                    Browse the directory structure of your image.
                     </para></listitem>
                 <listitem><para>
-                    Performance information such as time, CPU usage, and
-                    disk I/O per task
+                    See the value of all variables in your build configuration,
+                    and which files set each value.
+                    </para></listitem>
+                <listitem><para>
+                    Examine error, warning and trace messages to aid in
+                    debugging.
+                    </para></listitem>
+                <listitem><para>
+                    See information about the BitBake tasks executed and
+                    reused during your build, including those that used
+                    shared state.
+                    </para></listitem>
+                <listitem><para>
+                    See dependency relationships between recipes, packages
+                    and tasks.
+                    </para></listitem>
+                <listitem><para>
+                    See performance information such as build time, task time,
+                    CPU usage, and disk I/O.
                     </para></listitem>
             </itemizedlist>
-            For several useful videos that show how to effectively use the
-            Toaster interface, see the
-            <ulink url='https://www.yoctoproject.org/documentation/toaster-manual-17'>Toaster Documentation</ulink>
-            on the Yocto Project website.
-            <note><title>REVIEWER NOTE</title>
-               We have agreed to get rid of the manual page on the website,
-               contains the links to the GUI videos.
-               We have agreed to host the videos on Vimeo and to embed the
-               videos in this new Toaster manual.
-            </note>
+            Following are several videos that show how to use the Toaster GUI.
+            To get a larger replay of a video after it has started playing,
+            click in the image title area.
         </para>
+
+        <section id='toaster-gui-vids-1'>
+            <title>Toaster Homepage and Table Controls</title>
+
+            <para>
+                This video goes over the Toaster entry page, and provides
+                an overview of the data manipulation capabilities of Toaster,
+                which include search, sorting and filtering by different
+                criteria.
+                <mediaobject>
+                    <videoobject>
+                        <videodata width="640" height="480" fileref="http://www.youtube.com/v/QEARDnrR1Xw"></videodata>
+                    </videoobject>
+                </mediaobject>
+            </para>
+        </section>
+
+        <section id='toaster-gui-vids-2'>
+            <title>Build Dashboard</title>
+
+            <para>
+                This video shows you the build dashboard, a page providing an
+                overview of the information available for a selected build.
+                <mediaobject>
+                    <videoobject>
+                        <videodata width="640px" height="480px" fileref="http://www.youtube.com/v/KKqHYcnp2gE"></videodata>
+                    </videoobject>
+                </mediaobject>
+            </para>
+        </section>
+
+        <section id='toaster-gui-vids-3'>
+            <title>Image Information</title>
+
+            <para>
+                This video walks through the information Toaster provides
+                about images: packages installed and root file system.
+                <mediaobject>
+                    <videoobject>
+                        <videodata width="640px" height="480px" fileref="http://www.youtube.com/v/XqYGFsmA0Rw"></videodata>
+                    </videoobject>
+                </mediaobject>
+            </para>
+        </section>
+
+        <section id='toaster-gui-vids-4'>
+            <title>Configuration</title>
+
+            <para>
+                This video shows the information Toaster provides about build
+                configuration.
+                <mediaobject>
+                    <videoobject>
+                        <videodata width="640px" height="480px" fileref="http://www.youtube.com/v/UW-j-T2TzIg"></videodata>
+                    </videoobject>
+                </mediaobject>
+            </para>
+        </section>
+
+        <section id='toaster-gui-vids-5'>
+            <title>Tasks</title>
+
+            <para>
+                This video shows the information Toaster provides about the
+                tasks run by the build system.
+                <mediaobject>
+                    <videoobject>
+                        <videodata width="640px" height="480px" fileref="http://www.youtube.com/v/D4-9vGSxQtw"></videodata>
+                    </videoobject>
+                </mediaobject>
+            </para>
+        </section>
+
+        <section id='toaster-gui-vids-6'>
+            <title>Recipes and Packages Built</title>
+
+            <para>
+                This video shows the information Toaster provides about recipes
+                and packages built.
+                <mediaobject>
+                    <videoobject>
+                        <videodata width="640px" height="480px" fileref="http://www.youtube.com/v/x-6dx4huNnw"></videodata>
+                    </videoobject>
+                </mediaobject>
+            </para>
+        </section>
+        <section id='toaster-gui-vids-7'>
+            <title>Performance Data</title>
+
+            <para>
+                This video shows the build performance data provided by
+                Toaster.
+                <mediaobject>
+                    <videoobject>
+                        <videodata width="640px" height="480px" fileref="http://www.youtube.com/v/qWGMrJoqusQ"></videodata>
+                    </videoobject>
+                </mediaobject>
+            </para>
+        </section>
     </section>
 </chapter>

documentation/toaster-manual/toaster-manual-start.xml

@@ -9,8 +9,6 @@
     <para>
         This chapter describes how you need to prepare your system in order to
         use Toaster.
-        Toaster requires some packages that you must have installed before
-        trying to run Toaster.
     </para>
 
     <section id='toaster-setting-up-the-basic-system-requirements'>
@@ -30,54 +28,103 @@
         <title>Establishing Toaster System Dependencies</title>
 
         <para>
-            Toaster requires extra Python dependencies that Bitbake
-            does not need in order to run.
-            In order to make it easy to run Toaster, a requirements file
-            located in the root directory of
+            Toaster requires extra Python dependencies and
+            <ulink url='http://www.libslack.org/daemon/'><filename>daemon</filename></ulink>
+            in order to run.
+            A Toaster requirements file named
+            <filename>toaster-requirements.txt</filename> defines the
+            Python dependencies.
+            The requirements file is located in the
+            <filename>bitbake</filename> directory, which is located in the
+            root directory of the
             <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>
-            <filename>bitbake/</filename>
             (e.g. <filename>poky/bitbake/toaster-requirements.txt</filename>).
             The dependencies appear in a <filename>pip</filename>,
-            install-compatible format:
-            <literallayout class='monospaced'>
-     Django==1.6
-     South==0.8.4
-     argparse==1.2.1
-     wsgiref==0.1.2
-            </literallayout>
-            Follow these steps to get set up:
-            <orderedlist>
-                <listitem><para><emphasis>Install <filename>virtualenv</filename>:</emphasis>
-                    <filename>virtualenv</filename> is a tool to create
-                    isolated Python environments by creating folders that
-                    contain all the necessary executables to use the packages
-                    that Python projects need.
-                    You can use <filename>pip</filename> to install
-                    <filename>virtualenv</filename>:
-                    <literallayout class='monospaced'>
-     $ pip install virtualenv
-                    </literallayout>
-                    </para></listitem>
-                <listitem><para><emphasis>Create and activate a virtual environment:</emphasis>
-                    <literallayout class='monospaced'>
+            install-compatible format.
+        </para>
+
+        <section id='toaster-optional-virtual-environment'>
+            <title>Optionally Setting Up a Python Virtual Environment</title>
+
+            <para>
+                It is highly recommended that you use a Python virtual
+                environment that allows you to maintain a dedicated Python
+                executable and its own set of installed modules.
+                Doing so separates the executable from the Python and modules
+                provided by the operating system and therefore avoids any
+                version conflicts.
+            </para>
+
+            <para>
+                Follow these steps to set up your virtual environment.
+                These steps assume a Ubuntu distribution:
+                <orderedlist>
+                    <listitem><para><emphasis>Install <filename>virtualenv</filename>:</emphasis>
+                        Install the supported
+                        <filename>python-virtualenv</filename> package from your
+                        distribution rather than using <filename>pip</filename>.
+                        <literallayout class='monospaced'>
+     $ sudo apt-get install python-virtualenv
+                        </literallayout>
+                        </para></listitem>
+                    <listitem><para><emphasis>Create and Activate a Virtual Environment:</emphasis>
+                        <literallayout class='monospaced'>
      $ virtualenv venv
      $ source venv/bin/activate
-                    </literallayout>
-                    </para></listitem>
-                <listitem><para><emphasis>Use <filename>pip</filename> to install needed packages:</emphasis>
-                    <literallayout class='monospaced'>
+                        </literallayout>
+                        </para></listitem>
+                </orderedlist>
+            </para>
+        </section>
+
+        <section id='toaster-load-packages'>
+            <title>Install Toaster Packages</title>
+
+            <para>
+                You need to install the packages that Toaster requires.
+                Use this command:
+                <literallayout class='monospaced'>
      $ pip install -r bitbake/toaster-requirements.txt
-                    </literallayout>
-                    </para></listitem>
-            </orderedlist>
-            Once you complete these steps, you execute in a lightweight
-            "virtual environment” with its own site directories that are
-            optionally isolated from system site directories.
-            The virtual environment has its own Python binary
-            (allowing creation of environments with various Python versions)
-            and can have its own independent set of installed Python packages
-            in its site directories.
-        </para>
-    </section>
+                </literallayout>
+            </para>
+        </section>
 
+        <section id='toaster-install-daemon'>
+            <title>Install <filename>daemon</filename></title>
+
+            <para>
+                Toaster depends on
+                <ulink url='http://www.libslack.org/daemon/'><filename>daemon</filename></ulink>.
+                Depending on your distribution, how you install
+                <filename>daemon</filename> differs:
+                <itemizedlist>
+                    <listitem><para><emphasis>Debian-Based Systems:</emphasis>
+                        If you are running a Debian-based distribution,
+                        install <filename>daemon</filename> using the
+                        following command:
+                        <literallayout class='monospaced'>
+     $ sudo apt-get install daemon​
+                        </literallayout>
+                        </para></listitem>
+                    <listitem><para><emphasis>Non-Debian-Based Systems:</emphasis>
+                        If you are not running a Debian-based distribution
+                        (Redhat-based distribution such as Fedora),
+                        you need to download ​the file relevant to the
+                        architecture and then install
+                        <filename>daemon</filename> manually.
+                        Following are the commands for 64-bit distributions:
+                        <literallayout class='monospaced'>
+     $ wget http://libslack.org/daemon/download/daemon-0.6.4-1.x86_64.rpm
+     $ sudo rpm -i daemon-0.6.4-1.x86_64.rpm
+                        </literallayout>
+                        Here are the commands for a 32-bit distribution:
+                        <literallayout class='monospaced'>
+     $ wget http://libslack.org/daemon/download/daemon-0.6.4-1.i686.rpm
+     $ sudo rpm -i ​daemon-0.6.4-1.i686.rpm​
+                        </literallayout>
+                        </para></listitem>
+                </itemizedlist>
+            </para>
+        </section>
+    </section>
 </chapter>

documentation/toaster-manual/toaster-manual.xml

@@ -65,6 +65,8 @@
 
     <xi:include href="toaster-manual-setup-and-use.xml"/>
 
+    <xi:include href="toaster-manual-reference.xml"/>
+
 </book>
 <!--
 vim: expandtab tw=80 ts=4