Toaster User Manual

Install virtualenv: Install the supported python-virtualenv package from your distribution rather than using pip.

     $ sudo apt-get install python-virtualenv
                        

Create and Activate a Virtual Environment:

     $ virtualenv venv
     $ source venv/bin/activate
                        

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 "Setting Up to Use the Yocto Project" section in the Yocto Project Quick Start for information.

Source your Build Environment Setup Script: From your Source Directory (e.g. poky/build), source the build environment setup script oe-init-build-env 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
                        

Open Your Browser: Open your browser and visit http://host:port/toastergui. For host and port values, see the output of the source toaster start command. For information on how to use Toaster, see the "Using the Toaster Web Interface" section.

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 "Setting Up to Use the Yocto Project" section in the Yocto Project Quick Start for information.

Install and Set up the Database Server: You can use any SQL server out of the box. It is recommended that you use mysql-server because it has the advantages of advanced SQL features along with a fast and reliable database. However, setting up mysql-server is more complex and might require a Database Administrator to tune it.

Another supported database backend is sqlite3. With sqlite3, you have the advantage of no configuration and an easy installation. However, Toaster still requires direct access to the backend. The sqlite backend is also slower as compared to mysql-server, and has no transactional support.

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 mysql-server and sets up some user accounts and the database.

     $ 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';
                        

You need a separate clone of the Source Repositories 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.

     $ git clone git://git.yoctoproject.org/poky
                        

In the separately cloned tree for the Database 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. Here is an example:

     $ 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',
         }
        ...
                        

Install and Set Up the Web Server: 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 django WSGI. Here is an example that uses Apache web server.

     $ 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>

        ...
                        

You need to collect static media from Toaster and continue configuring Apache to serve that static media:

     $ 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

        ...
                        

Start Toaster: 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:

     $ /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
                        

You can find general documentation on manage.py at the Django site. For reference information on Toaster-specific manage.py commands, see the "Useful Commands" section.

Enable Build Logging to the Common SQL Server for Each Build Directory you are Using: You need to make sure that the toaster class and build history are enabled. This is done in a toaster.conf file that is created automatically by the toaster start command, and that lives inside the Build Directory in /conf/toaster.conf.

That file should include the following line:

     INHERIT += "toaster buildhistory"
                        

For information on build history, see the "Maintaining Build Output Quality" section in the Yocto Project Development Manual.

You also need to point to the database that you set up in step 3. You can do this by exporting the DATABASE_URL variable as follows:

     export DATABASE_URL=mysql://newuser:password@192.168.0.25:3306/toaster
                        

This example assumes that you are using mysql-server. The IP address should be the IP address of your database server.

Source your Build Environment Setup Script: From your Source Directory on each of the build systems, (e.g. poky/build), source the build environment setup script (i.e. oe-init-build-env or oe-init-build-env-memres).

Start the BitBake Server: 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 Server: Start the Toaster Logging Interface using the following command:

     $ nohup bitbake --observe-only -u toasterui >toaster_ui.log &
                        

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
                        

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 "Setting Up to Use the Yocto Project" section in the Yocto Project Quick Start for information.

Start Toaster: From the root of the source directory (e.g poky/), run the following command:

     $ bitbake/bin/toaster
                        

Create a Superuser: 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.

Select the Build Log Directory: 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).

When Toaster prompts you for the Build Log directory, you can select the suggested default or provide a path to a different directory.

Specify the Layer Checkout Directory: Toaster asks you to specify the directory into which layers are checked out. Toaster clones any layers needed for your builds inside this directory.

When Toaster prompts you for the Layer checkout directory, you can select the suggested default or provide a path to a different directory.

Specify the Build Directory Path: 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.

Choose Whether or not to Import a Default Toaster Configuration File: Toaster asks you if you want to import a default Toaster configuration file. Toaster configurations are stored in JSON files called toasterconf.json. For information on JSON files, see the "JSON Files" section.

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.

For general information on Django, see the available documentation. You can also find information on Toaster-specific manage.py commands in the "Useful Commands" section.

Open the Browser: If no browser window appears, open your favorite browser and enter the following:

     http://localhost:8000/toastergui
                        

You can now use the Toaster web interface.

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 "Setting Up to Use the Yocto Project" section in the Yocto Project Quick Start for information.

Be Sure Management is Enabled: If you are running Toaster under Apache, you need to be sure management is enabled. To enable management, set MANAGED to "True" by adding the following to the bitbake/lib/toaster/settings.py file:

     MANAGED="True"
                        

Set Up Toaster for Normal Usage: You need to configure each build environment, layer sources, and BitBake versions.

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.

If you want to use the administration interface for this step, here is a set of example commands with some descriptions as an example:

     # Create the user under which the builds will run
     $ adduser poky

     # Bring up the administration interface
     $xdg-open http://server-address/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
                        

You also need to configure the project releases, the default variables, and update information from the layer index. Continuing with the example:

     # 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
                        

For reference information on Toaster-specific manage.py commands, see the "Useful Commands" section.

Install and Set up the Database Server: You can use any SQL server out of the box. It is recommended that you use mysql-server because it has the advantages of advanced SQL features along with a fast and reliable database. However, setting up mysql-server is more complex and might require a Database Administrator to tune it.

Another supported database backend is sqlite3. With sqlite3, you have the advantage of no configuration and an easy installation. However, Toaster still requires direct access to the backend. The sqlite backend is also slower as compared to mysql-server, and has no transactional support.

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 mysql-server and sets up some user accounts and the database.

     $ 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';
                        

You need a separate clone of the Source Repositories 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.

     $ git clone git://git.yoctoproject.org/poky
                        

In the separately cloned tree for the Database 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. Here is an example:

     $ 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',
         }
        ...
                        

Create the Database Use the following commands to create the default database structure:

     $ bitbake/lib/toaster/manage.py syncdb
     $ bitbake/lib/toaster/manage.py migrate orm
     $ bitbake/lib/toaster/manage.py migrate bldcontrol
                        

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.

Select Where the Build Process Takes Place: 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:

     /home/poky/buildartifacts/
     /home/poky/build/
     /home/poky/sources/
                        

Set Up the toasterconf.json File: Download the hosted toasterconf.json file from the Yocto Project wiki and edit it to suit your environment. For information on the relevant sections of the file, see the "JSON Files" section.

After editing the file, load it by running the following:

     $ bitbake/lib/toaster/manage.py loadconf path-to-toasterconf.json-file
                        

For reference information on Toaster-specific manage.py, see the "Useful Commands" section.

Check the Toaster Settings: Configure the build environment by running the following:

     $ bitbake/lib/toaster/manage.py checksettings
                        

When prompted, paste in the directory paths created previously during Step 7. For reference information on Toaster-specific manage.py, see the "Useful Commands" section.

Install and Set Up the Web Server: 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 django WSGI. Here is an example that uses Apache web server:

     $ 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>

        ...
                        

You need to collect static media from Toaster and continue configuring Apache to serve that static media:

     $ 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

        ...
                        

Start Toaster: 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:

     $ /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
                        

For reference information on the manage.py commands used here, see the "Useful Commands" section.

Set up Build Control and Open the Web Interface: You need to run the build control manager. You can do this as shown in the following example:

     # 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/
                        

It is suggested that you enable build control by setting runbuilds in the crontab as follows:

     $ crontab -l
     * * * * *  /opt/bitbake/lit/toaster/manage.py runbuilds
                        

Open the Browser: Once the Apache server is running, connect to it with your favorite browser and verify that the Toaster interface comes up:

     http://localhost:8000/toastergui
                        

You can track accesses and errors in the Apache service logs.