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>

1 files changed, 765 insertions, 155 deletions

diff --git a/documentation/toaster-manual/toaster-manual-setup-and-use.xml b/documentation/toaster-manual/toaster-manual-setup-and-use.xml
index f56d67ed37..b148d4f405 100644
--- a/documentation/toaster-manual/toaster-manual-setup-and-use.xml
+++ b/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>