diff options
Diffstat (limited to 'documentation/toaster-manual/toaster-manual-setup-and-use.xml')
| -rw-r--r-- | documentation/toaster-manual/toaster-manual-setup-and-use.xml | 1024 |
1 files changed, 1024 insertions, 0 deletions
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..a1546858d9 --- /dev/null +++ b/documentation/toaster-manual/toaster-manual-setup-and-use.xml @@ -0,0 +1,1024 @@ +<!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-setup-and-use'> + +<title>Setting Up and Using Toaster</title> + + <section id='using-toaster-in-analysis-mode'> + <title>Using Toaster in Analysis Mode</title> + + <para> + This section describes how to use Toaster in Analysis Mode + after setting Toaster up as a local instance or as a hosted + service. + </para> + + <section id='setting-up-locally-and-running-in-analysis-mode'> + <title>Setting Up Locally and Running in Analysis Mode</title> + + <para> + Follow these steps to set up a local instance of Toaster and + then run in Analysis 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>Source your Build Environment Setup Script:</emphasis> + From your + <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink> + (e.g. <filename>poky/build</filename>), source the build + 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>. + </para></listitem> + <listitem><para><emphasis>Start Toaster:</emphasis> + From the + <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>, + start Toaster: + <literallayout class='monospaced'> + $ source toaster start + </literallayout> + </para></listitem> + <listitem><para><emphasis>Start Your Build Using BitBake:</emphasis> + Use the <filename>bitbake</filename> command to start your + build. + Here is an example that builds the + <filename>core-image-minimal</filename> image: + <literallayout class='monospaced'> + $ 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> + + </para> + </section> + + <section id='setting-up-a-hosted-service-and-running-in-analysis-mode'> + <title>Setting Up a Hosted Service and Running in Analysis Mode</title> + + <para> + A hosted service resides on a shared server and allows + multiple users to take advantage of Toaster. + </para> + + <para> + 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> + Maintain a common SQL database. + </para></listitem> + <listitem><para> + Set up separate instances of BitBake servers + and Toaster Logging Interfaces for each of those + separate BitBake servers. + </para></listitem> + </itemizedlist> + </para> + + <para> + 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 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 + 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>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>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 + <ulink url='https://docs.djangoproject.com/en/1.7/howto/deployment/wsgi/'><filename>django</filename> WSGI</ulink>. + 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 + + <Directory //opt/bitbake/lib/toaster/toastermain/> + <Files wsgi.py> + Require all granted + </Files> + </Directory> + + ... + </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 && 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/ + + <Directory /var/www.html/static/> + Require all granted + </Directory> + + ... + + 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> + 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> + You need to make sure that the + <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-toaster'><filename>toaster</filename></ulink> + class and build history are enabled. + This is done in a + <filename>toaster.conf</filename> file that is + created automatically by the toaster + <filename>start</filename> command, + and that lives inside the + <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink> + in <filename>/conf/toaster.conf</filename>.</para> + <para>That file should include the following line: + <literallayout class='monospaced'> + INHERIT += "toaster buildhistory" + </literallayout> + For information on build history, see the + "<ulink url='&YOCTO_DOCS_REF_URL;#maintaining-build-output-quality'>Maintaining Build Output Quality</ulink>" + section in the Yocto Project Development + Manual.</para> + <para>You also need to point to the database that you set + up in step 3. + You can do this by exporting the <filename>DATABASE_URL</filename> + variable as follows: + <literallayout class='monospaced'> + export DATABASE_URL=mysql://newuser:password@192.168.0.25:3306/toaster + </literallayout> + This example assumes that you are using + <filename>mysql-server</filename>. + The IP address should be the IP address of your + database server. + </para></listitem> + <listitem><para><emphasis>Source your Build Environment Setup Script:</emphasis> + From your + <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. + <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>). + </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 && 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 & + </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. + Here is an example that builds the + <filename>core-image-minimal</filename> image: + <literallayout class='monospaced'> + $ bitbake core-image-minimal + </literallayout> + When you are finished with a build in a given + Build Directory, be sure to <filename>kill</filename> + the BitBake server for that build area: + <literallayout class='monospaced'> + $ bitbake -m + </literallayout> + </para></listitem> + </orderedlist> + </para> + + <para> + 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> + </section> + + <section id='using-toaster-in-build-mode'> + <title>Using Toaster in Build Mode</title> + + <para> + This section describes how to use Toaster in Build Mode + after setting Toaster up as a local instance or as a hosted + service. + </para> + + <section id='setting-up-locally-and-running-in-build-mode'> + <title>Setting Up Locally and Running in Build Mode</title> + + <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>. + 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> + + <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>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 information 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 user, which is "poky" in this example. + 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> + <ulink url='https://wiki.yoctoproject.org/wiki/File:Toasterconf.json.txt.patch'>Download the hosted <filename>toasterconf.json</filename> file</ulink> + from the Yocto Project wiki 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> + <para>After editing the file, load it by running + the following: + <literallayout class='monospaced'> + $ bitbake/lib/toaster/manage.py loadconf path-to-toasterconf.json-file + </literallayout> + For reference information on Toaster-specific + <filename>manage.py</filename>, see the + "<link linkend='toaster-useful-commands'>Useful Commands</link>" + section. + </para></listitem> + <listitem><para><emphasis>Check the Toaster Settings:</emphasis> + Configure the build environment by running the + following: + <literallayout class='monospaced'> + $ bitbake/lib/toaster/manage.py checksettings + </literallayout> + When prompted, paste in the directory paths created + previously during Step 7. + For reference information on Toaster-specific + <filename>manage.py</filename>, see the + "<link linkend='toaster-useful-commands'>Useful Commands</link>" + section. + </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 + <ulink url='https://docs.djangoproject.com/en/1.7/howto/deployment/wsgi/'><filename>django</filename> WSGI</ulink>. + 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 + + <Directory //opt/bitbake/lib/toaster/toastermain/> + <Files wsgi.py> + Require all granted + </Files> + </Directory> + + ... + </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 && 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/ + + <Directory /var/www.html/static/> + Require all granted + </Directory> + + ... + + 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: + <literallayout class='monospaced'> + http://localhost:8000/toastergui + </literallayout> + You can track accesses and errors in the Apache + service logs. + </para></listitem> + </orderedlist> + </para> + </section> + </section> + + <section id='using-the-toaster-web-interface'> + <title>Using the Toaster Web Interface</title> + + <para> + The Toaster web interface allows you to do the following: + <itemizedlist> + <listitem><para> + Browse published layers in the + <ulink url='http://layers.openembedded.org'>OpenEmbedded Metadata Index</ulink> + that are available for your selected version of the build + system. + </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> + <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> + Following are several videos that show how to use the Toaster GUI: + <itemizedlist> + <listitem><para><emphasis>Build Configuration:</emphasis> + This + <ulink url='https://www.youtube.com/watch?v=qYgDZ8YzV6w'>video</ulink> + overviews and demonstrates build configuration for Toaster. + </para></listitem> + <listitem><para><emphasis>Toaster Homepage and Table Controls:</emphasis> + This + <ulink url='https://www.youtube.com/watch?v=QEARDnrR1Xw'>video</ulink> + 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. + </para></listitem> + <listitem><para><emphasis>Build Dashboard:</emphasis> + This + <ulink url='https://www.youtube.com/watch?v=KKqHYcnp2gE'>video</ulink> + shows you the build dashboard, a page providing an + overview of the information available for a selected build. + </para></listitem> + <listitem><para><emphasis>Image Information:</emphasis> + This + <ulink url='https://www.youtube.com/watch?v=XqYGFsmA0Rw'>video</ulink> + walks through the information Toaster provides + about images: packages installed and root file system. + </para></listitem> + <listitem><para><emphasis>Configuration:</emphasis> + This + <ulink url='https://www.youtube.com/watch?v=UW-j-T2TzIg'>video</ulink> + provides Toaster build configuration information. + </para></listitem> + <listitem><para><emphasis>Tasks:</emphasis> + This + <ulink url='https://www.youtube.com/watch?v=D4-9vGSxQtw'>video</ulink> + shows the information Toaster provides about the + tasks run by the build system. + </para></listitem> + <listitem><para><emphasis>Recipes and Packages Built:</emphasis> + This + <ulink url='https://www.youtube.com/watch?v=x-6dx4huNnw'>video</ulink> + shows the information Toaster provides about recipes + and packages built. + </para></listitem> + <listitem><para><emphasis>Performance Data:</emphasis> + This + <ulink url='https://www.youtube.com/watch?v=qWGMrJoqusQ'>video</ulink> + shows the build performance data provided by + Toaster. + </para></listitem> + </itemizedlist> + </para> + </section> + +<!-- + <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>qYgDZ8YzV6w + </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> +--> +</chapter> |