diff --git a/documentation/toaster-manual/toaster-manual-setup-and-use.xml b/documentation/toaster-manual/toaster-manual-setup-and-use.xml
new file mode 100644
index 0000000000..ac9e9313ff
--- /dev/null
+++ b/documentation/toaster-manual/toaster-manual-setup-and-use.xml
@@ -0,0 +1,326 @@
+ %poky; ] >
+
+
+
+Setting Up and Using Toaster
+
+
+ You can set up local and production instances of Toaster.
+ This chapter describes how to set up both these types of instances.
+
+
+
+ Setting Up a Local Instance
+
+
+ Follow these steps to set up and run a local instance of Toaster:
+
+ Prepare your build system:
+ Be sure your system has the Toaster requirements
+ by following the steps in the
+ "Establishing Toaster System Dependencies"
+ section.
+
+ Get Set Up to Use the Yocto Project:
+ Get the requirements set up so that you can use the
+ Yocto Project to build images.
+ See the
+ "What You Need and How You Get It"
+ section in the Yocto Project Quick Start for information.
+
+ Be sure Ports are free:
+ Make sure that port 8000 and 8200 are free.
+ In other words, make sure the ports do not have servers
+ on them.
+
+ Source your Build Environment Setup Script:
+ From your
+ Build Directory
+ (e.g. poky/build), source the build
+ environment setup script (i.e.
+ &OE_INIT_FILE;
+ or
+ oe-init-build-env-memres).
+
+ Start Toaster:
+ From the
+ Build Directory,
+ start Toaster:
+
+ $ source toaster start
+
+
+ Start Your Build using BitBake:
+ Use the bitbake command to start your
+ build.
+ Here is an example that builds the
+ core-image-minimal image:
+
+ $ bitbake core-image-minimal
+
+
+
+
+
+
+ For information on how to use Toaster, see the
+ "Using the Toaster Interface"
+ section.
+
+
+
+
+ Setting Up a Production Instance
+
+
+ A production instance of Toaster resides on a server and allows
+ multiple users to take advantage of Toaster.
+ In a production environment, you might want to have multiple
+ instances of Toaster running on various remote build machines.
+ You can create this situation by basically modifying how Toaster
+ starts.
+
+
+
+ Starting Toaster with the toaster command
+ (i.e. the script), causes three things to start:
+
+
+ The BitBake server.
+
+
+ the Toaster User Interface, which connects to the
+ BitBake server on one side and to the SQL
+ database on the other side.
+
+
+ The web server, which reads the database and displays the
+ web user interface.
+
+
+ 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, an instance of Toaster requires just one of the
+ components.
+
+
+
+ The concepts for setting up multiple instances of Toaster revolve
+ around maintaining a common SQL database and Web server that
+ show data from that common database as well as setting up
+ separate instances of BitBake servers and Toaster user interfaces
+ for each separate BitBake build directory.
+ The common SQL database and the Web server show data from all the
+ various BitBake builds.
+ Setting the SQL database outside of any
+ Build Directory
+ maintains a separation layer between the various builds.
+ The database is persistent because the logging database is set
+ up external to the 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.
+
+
+
+ Follow these steps to set up and run a production instance of
+ Toaster:
+
+ Prepare your build system:
+ Be sure your system has the Toaster requirements
+ by following the steps in the
+ "Establishing Toaster System Dependencies"
+ section.
+
+ Get Set Up to Use the Yocto Project:
+ Get the requirements set up so that you can use the
+ Yocto Project to build images.
+ See the
+ "What You Need and How You Get It"
+ section in the Yocto Project Quick Start for information.
+
+ Be sure Ports are free:
+ Make sure that port 8000 and 8200 are free.
+ In other words, make sure the ports do not have servers
+ on them.
+
+ Set up the SQL Logging Server and the Web Server:
+ You can use any SQL server out of the box (e.g.
+ mysgl-server for an Ubuntu build
+ system).
+
+ If you are concerned about performance, you might want
+ to hand-tune the server.
+
+ You must set up proper username and password access for
+ the server for everyone that will be using Toaster.
+ You need administration rights for the
+ mysql root account, which is not the
+ same thing as root access on the machine.
+
+ Clone a separate, local Git repository of the
+ Toaster master branch to use for running the Web server:
+
+ $ git clone (NEED THE GIT REPO URL HERE)
+
+ You do not perform builds on this tree.
+ You need to create this local repository away from any
+ build areas.
+
+ In the separately cloned tree for the Web server,
+ edit the
+ bitbake/lib/toaster/toastermain/settings.py
+ file so that the DATABASES value
+ points to the previously created database server.
+ Use the username and password established earlier.
+
+ Run the database sync scripts to create the needed
+ tables as follows:
+
+ $ python bitbake/lib/toaster/manage.py syncdb
+ $ python bitbake/lib/toaster/manage.py migrate orm
+
+ You can start the web server in the foreground or the
+ background using these commands, respectively:
+
+ $ python bitbake/lib/toaster/manage.py runserver
+ $ nohup python bitbake/lib/toaster/manage.py runserver 2>toaster_web.log >toaster_web.log &
+
+
+ Enable Build Logging to the Common SQL Server for Each Build Directory you are Using
+ For each build system that will be using Toaster and the
+ SQL server, you need to edit the
+ bitbake/lib/toaster/toastermain/settings.py
+ to alter the DATABASES value to point
+ to the common SQL logging server.
+ (I DON'T SEE HOW TO DO THIS FROM THE WIKI - I NEED MORE
+ CLARIFICATION).
+
+ In the Build Directory, create the required
+ conf/toaster.conf file as described in
+ BitBake Extra Options.
+ Briefly, for each Build Directory, you need to inherit the
+ toaster
+ class by setting the following in your
+ local.conf configuration file:
+
+ INHERIT += "toaster"
+ INHERIT += "buildhistory"
+ BUILDHISTORY_COMMIT = "1"
+
+ Start the BitBake server using the following command:
+
+ $ bitbake --postread conf/toaster.conf --server-only -t xmlrpc -B localhost:0 && export BBSERVER=localhost:-1
+
+ Start the logging user interface using the following
+ command:
+
+ $ nohup bitbake --observe-only -u toasterui >toaster_ui.log &
+
+
+ No hard-coded ports are used as there is enough code
+ to run autodiscovery
+ for ports to prevent collisions.
+
+
+ Source your Build Environment Setup Script:
+ From your
+ Build Directory
+ on each of the build systems,
+ (e.g. poky/build), source the build
+ environment setup script (i.e.
+ &OE_INIT_FILE;
+ or
+ oe-init-build-env-memres).
+
+ Start Builds Using BitBake:
+ Use the bitbake command to start a
+ build on a build system.
+ Here is an example that builds the
+ core-image-minimal image:
+
+ $ bitbake core-image-minimal
+
+ When you are finished with a build in a given
+ Build Directory, be sure to kill
+ the BitBake server for that build area:
+
+ $ bitbake -m
+
+
+
+
+
+
+ For information on how to use Toaster, see the
+ "Using the Toaster Interface"
+ section.
+
+
+
+
+ Setting Up a Hosted Managed Mode for Toaster
+
+
+ (RIGHT NOW, THE
+ WIKI PAGE
+ HAS SOME INFORMATION ON THIS.
+ I DON'T GET IT THOUGH.
+ I NEED SOME MORE INFORMATION IN ORDER TO UNDERSTAND THIS AND
+ CREATE A SECTION.
+
+
+
+
+ Using the Toaster Interface
+
+
+ The Toaster interface allows you to examine the following:
+
+
+ Outcome of the build, errors and warnings thrown
+
+
+ Packages included in an image
+
+
+ Image directory structure
+
+
+ Build configuration
+
+
+ Recipes and packages built
+
+
+ Full dependency chain for tasks, recipes and packages
+
+
+ Tasks run by the build system
+
+
+ Performance information such as time, CPU usage, and
+ disk I/O per task
+
+
+ For several useful videos that show how to effectively use the
+ Toaster interface, see the
+ Toaster Documentation
+ on the Yocto Project website.
+ (SO WE NEED TO DECIDE IF THESE VIDS ARE GOING TO ROLL OVER INTO
+ 1.8 AND REMAIN ON A "TOASTER MANUAL" PAGE AS THEY DO IN 1.7.
+ OR, IF WE ARE GOING TO GET THE LINKS TO THE VIDS HERE IN THIS
+ MANUAL.)
+
+
+
+
+
+
diff --git a/documentation/toaster-manual/toaster-manual-start.xml b/documentation/toaster-manual/toaster-manual-start.xml
new file mode 100644
index 0000000000..93f48c7b26
--- /dev/null
+++ b/documentation/toaster-manual/toaster-manual-start.xml
@@ -0,0 +1,75 @@
+ %poky; ] >
+
+
+
+Preparing to Use Toaster
+
+
+ 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.
+
+
+
+ Setting Up the Basic System Requirements
+
+
+ You first need to be sure your build system is set up to run
+ the Yocto Project.
+ See the
+ "What You Need and How You Get It"
+ section in the Yocto Project Quick Start for information on how
+ to set up your system for the Yocto Project.
+
+
+
+
+ Establishing Toaster System Dependencies
+
+
+ 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
+ Source Directory
+ bitbake/
+ (e.g. poky/bitbake/toaster-requirements.txt).
+ The dependencies appear in a pip,
+ install-compatible format:
+
+ Django==1.6
+ South==0.8.4
+ argparse==1.2.1
+ wsgiref==0.1.2
+
+ Follow these steps to get set up:
+
+ Create and activate a virtual environment:
+
+ $ virtualenv venv
+ $ source venv/bin/activate
+
+
+ Use pip to install needed packages:
+
+ $ pip install -r bitbake/toaster-requirements.txt
+
+
+
+ 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.
+
+
+
+
+