summaryrefslogtreecommitdiffstats
path: root/documentation
diff options
context:
space:
mode:
authorEd Bartosh <ed.bartosh@linux.intel.com>2016-01-05 16:29:48 -0600
committerRichard Purdie <richard.purdie@linuxfoundation.org>2016-01-07 12:13:46 +0000
commit0baadc8a98daa14090b04e728fb5a44af3f545c8 (patch)
tree9e29c1ea7fe76fda8c568245b78502b4b9209a2c /documentation
parent908bbff8797e47a55d302979aecf45888ee23427 (diff)
downloadpoky-0baadc8a98daa14090b04e728fb5a44af3f545c8.tar.gz
toaster-manual: Updates to toaster use chapter.
* Removed obsolete bits that were already commented out of the XML file. * Added more detail to running Toaster and accessing the information. (From yocto-docs rev: d2b964e395273bde4f75ba3cd8e26a9e7d00b569) Signed-off-by: Scott Rifenbark <srifenbark@gmail.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'documentation')
-rw-r--r--documentation/toaster-manual/toaster-manual-setup-and-use.xml919
1 files changed, 5 insertions, 914 deletions
diff --git a/documentation/toaster-manual/toaster-manual-setup-and-use.xml b/documentation/toaster-manual/toaster-manual-setup-and-use.xml
index 74c00c498c..8c7ff7bd0a 100644
--- a/documentation/toaster-manual/toaster-manual-setup-and-use.xml
+++ b/documentation/toaster-manual/toaster-manual-setup-and-use.xml
@@ -53,12 +53,14 @@
53 <literallayout class='monospaced'> 53 <literallayout class='monospaced'>
54 $ source ../bitbake/bin/toaster 54 $ source ../bitbake/bin/toaster
55 </literallayout> 55 </literallayout>
56 You can now run builds normally. 56 You can now run your builds from the command line, or with
57 Toaster as explained in section
58 "<link linkend='using-the-toaster-web-interface'>Using the Toaster Web Interface</link>".
57 </para> 59 </para>
58 60
59 <para> 61 <para>
60 To see the build information provided by Toaster, open your 62 To access the Toaster web interface, open your favorite
61 favorite browser and enter the following: 63 browser and enter the following:
62 <literallayout class='monospaced'> 64 <literallayout class='monospaced'>
63 http://127.0.0.1:8000 65 http://127.0.0.1:8000
64 </literallayout> 66 </literallayout>
@@ -473,816 +475,6 @@
473 </section> 475 </section>
474 </section> 476 </section>
475 477
476
477
478
479<!-- <section id='using-toaster-in-analysis-mode'>
480 <title>Using Toaster in Analysis Mode</title>
481
482
483 <para>
484 This section describes how to use Toaster in Analysis Mode
485 after setting Toaster up as a local instance or as a hosted
486 service.
487 </para>
488
489 <section id='setting-up-locally-and-running-in-analysis-mode'>
490 <title>Setting Up Locally and Running in Analysis Mode</title>
491
492 <para>
493 Follow these steps to set up a local instance of Toaster and
494 then run in Analysis Mode:
495 <orderedlist>
496 <listitem><para><emphasis>Prepare your Build System:</emphasis>
497 Be sure your system has the Toaster requirements
498 by following the steps in the
499 "<link linkend='toaster-establishing-toaster-system-dependencies'>Establishing Toaster System Dependencies</link>"
500 section.
501 </para></listitem>
502 <listitem><para><emphasis>Get Set Up to Use the Yocto Project:</emphasis>
503 Get the requirements set up so that you can use the
504 Yocto Project to build images.
505 See the
506 "<ulink url='&YOCTO_DOCS_QS_URL;#yp-resources'>Setting Up to Use the Yocto Project</ulink>"
507 section in the Yocto Project Quick Start for information.
508 </para></listitem>
509 <listitem><para><emphasis>Source your Build Environment Setup Script:</emphasis>
510 From your
511 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>
512 (e.g. <filename>poky/build</filename>), source the build
513 environment setup script
514 <ulink url="&YOCTO_DOCS_REF_URL;#structure-core-script"><filename>&OE_INIT_FILE;</filename></ulink>
515 or
516 <ulink url="&YOCTO_DOCS_REF_URL;#structure-memres-core-script"><filename>oe-init-build-env-memres</filename></ulink>.
517 </para></listitem>
518 <listitem><para><emphasis>Start Toaster:</emphasis>
519 From the
520 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>,
521 start Toaster:
522 <literallayout class='monospaced'>
523 $ source toaster start
524 </literallayout>
525 </para></listitem>
526 <listitem><para><emphasis>Start Your Build Using BitBake:</emphasis>
527 Use the <filename>bitbake</filename> command to start your
528 build.
529 Here is an example that builds the
530 <filename>core-image-minimal</filename> image:
531 <literallayout class='monospaced'>
532 $ bitbake core-image-minimal
533 </literallayout>
534 </para></listitem>
535 <listitem><para><emphasis>Open Your Browser:</emphasis>
536 Open your browser and visit
537 <filename>http://host:port/toastergui</filename>.
538 For host and port values, see the output of the
539 <filename>source toaster start</filename> command.
540 For information on how to use Toaster, see the
541 "<link linkend='using-the-toaster-web-interface'>Using the Toaster Web Interface</link>"
542 section.
543 </para></listitem>
544 </orderedlist>
545 </para>
546
547 <para>
548
549 </para>
550 </section>
551
552 <section id='setting-up-a-hosted-service-and-running-in-analysis-mode'>
553 <title>Setting Up a Hosted Service and Running in Analysis Mode</title>
554
555 <para>
556 A hosted service resides on a shared server and allows
557 multiple users to take advantage of Toaster.
558 </para>
559
560 <para>
561 In a production environment, you might want to have multiple
562 local instances of the Toaster Logging Interface running on
563 various remote build machines, and have those local instances
564 access and use a single web server.
565 To do this, you need to do the following:
566 <itemizedlist>
567 <listitem><para>
568 Maintain a common SQL database.
569 </para></listitem>
570 <listitem><para>
571 Set up separate instances of BitBake servers
572 and Toaster Logging Interfaces for each of those
573 separate BitBake servers.
574 </para></listitem>
575 </itemizedlist>
576 </para>
577
578 <para>
579 The common SQL database allows the Web server to show data from
580 all the various BitBake builds.
581 Setting the SQL database outside of any
582 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
583 maintains a separation between the various builds.
584 The BitBake servers, the SQL server, and the Web server or
585 servers can be run on separate machines.
586 </para>
587
588 <para>
589 Follow these steps to set up and run a hosted service and run
590 Toaster in Analysis Mode:
591 <note>
592 The steps assume a Toaster installation path of
593 <filename>/opt/bitbake/</filename>.
594 </note>
595 <orderedlist>
596 <listitem><para><emphasis>Prepare your Build System:</emphasis>
597 Be sure your system has the Toaster requirements
598 by following the steps in the
599 "<link linkend='toaster-establishing-toaster-system-dependencies'>Establishing Toaster System Dependencies</link>"
600 section.
601 </para></listitem>
602 <listitem><para><emphasis>Get Set Up to Use the Yocto Project:</emphasis>
603 Get the requirements set up so that you can use the
604 Yocto Project to build images.
605 See the
606 "<ulink url='&YOCTO_DOCS_QS_URL;#yp-resources'>Setting Up to Use the Yocto Project</ulink>"
607 section in the Yocto Project Quick Start for information.
608 </para></listitem>
609 <listitem><para><emphasis>Install and Set up the Database Server:</emphasis>
610 You can use any SQL server out of the box.
611 It is recommended that you use
612 <filename>mysql-server</filename> because it has
613 the advantages of advanced SQL features along with a
614 fast and reliable database.
615 However, setting up <filename>mysql-server</filename>
616 is more complex and might require a Database
617 Administrator to tune it.</para>
618 <para>Another supported database backend is
619 <filename>sqlite3</filename>.
620 With <filename>sqlite3</filename>, you have the
621 advantage of no configuration and an easy installation.
622 However, Toaster still requires direct access to the
623 backend.
624 The <filename>sqlite</filename> backend is also slower
625 as compared to <filename>mysql-server</filename>, and
626 has no transactional support.</para>
627 <para>You should set up proper username and password
628 access on the shared database for everyone that will
629 be using Toaster.
630 You need administrator rights for the root account,
631 which is not the same thing as root access on the
632 machine.
633 Here is an example that installs
634 <filename>mysql-server</filename> and sets up
635 some user accounts and the database.
636 <literallayout class='monospaced'>
637 $ apt-get install mysql-server
638 $ mysql -u root
639 mysql> CREATE USER 'newuser'@'localhost' IDENTIFIED BY 'password';
640 mysql> GRANT ALL PRIVILEGES ON * . * TO 'newuser'@'localhost';
641 mysql> GRANT ALL PRIVILEGES ON * . * TO 'newuser'@'localhost';
642 mysql> CREATE DATABASE 'toaster';
643 </literallayout>
644 You need a separate clone of the
645 <ulink url='&YOCTO_DOCS_DEV_URL;#source-repositories'>Source Repositories</ulink>
646 for the Database Server.
647 This clone is only used for getting the latest Toaster
648 files.
649 You can set this up using the following Git command.
650 Be sure to set up the directory outside of any
651 Build Directories.
652 <literallayout class='monospaced'>
653 $ git clone git://git.yoctoproject.org/poky
654 </literallayout>
655 In the separately cloned tree for the Database Server,
656 edit the
657 <filename>bitbake/lib/toaster/toastermain/settings.py</filename>
658 file so that the <filename>DATABASES</filename> value
659 points to the previously created database server.
660 Use the username and password established
661 earlier.
662 Here is an example:
663 <literallayout class='monospaced'>
664 $ cat /opt/bitbake/lib/toaster/toastermain/settings.py
665 ...
666 DATABASES = {
667 'default': {
668 'ENGINE': 'django.db.backends.mysql',
669 'NAME': 'toaster',
670 'USER': 'newuser',
671 'PASSWORD': 'password',
672 'HOST': '192.168.0.25',
673 'PORT': '3306',
674 }
675 ...
676 </literallayout>
677 </para></listitem>
678 <listitem><para><emphasis>Install and Set Up the Web Server:</emphasis>
679 For a production environment, it is recommended that
680 you install and set up a front-end web server.
681 This server allows for load balancing and
682 multi-threading over Toaster and
683 <ulink url='https://docs.djangoproject.com/en/1.7/howto/deployment/wsgi/'><filename>django</filename> WSGI</ulink>.
684 Here is an example that uses Apache web server.
685 <literallayout class='monospaced'>
686 $ apt-get install apache2 libapache2-mod-wsgi
687 $ a2enmod wsgi
688 $ cat /etc/apache2/sites-available/000-default.conf
689
690 ...
691
692 # the WSGIPythonPath is global
693 WSGIPythonPath /opt/bitbake/lib/toaster/
694
695 ...
696
697 #snip - in VirtualHost
698 WSGIScriptAlias / /opt/bitbake/lib/toaster/toastermain/wsgi.py
699
700 &lt;Directory //opt/bitbake/lib/toaster/toastermain/&gt;
701 &lt;Files wsgi.py&gt;
702 Require all granted
703 &lt;/Files&gt;
704 &lt;/Directory&gt;
705
706 ...
707 </literallayout>
708 You need to collect static media from Toaster and
709 continue configuring Apache to serve that static
710 media:
711 <literallayout class='monospaced'>
712 $ mkdir /var/www.html/static &amp;&amp; cd /var/www.html/static
713 $ /opt/bitbake/lib/toaster/manage.py collectstatic
714 $ cat /etc/apache2/sites-available/000-default.conf
715
716 ...
717
718 # in VirtualHost, AHEAD of the WSGIScriptAlias definition
719 Alias /static/ /var/www.html/static/
720
721 &lt;Directory /var/www.html/static/&gt;
722 Require all granted
723 &lt;/Directory&gt;
724
725 ...
726
727 WSGIScript Alias / /opt/bitbake/lib/toaster/toastermain/wsgi.py
728
729 ...
730 </literallayout>
731 </para></listitem>
732 <listitem><para><emphasis>Start Toaster:</emphasis>
733 Synchronize the databases for toaster, and then start
734 up the web server.
735 Here is an example that continues with the assumed
736 components from the previous steps:
737 <literallayout class='monospaced'>
738 $ /opt/bitbake/lib/toaster/manage.py syncdb
739 $ /opt/bitbake/lib/toaster/manage.py migrate orm
740 $ /opt/bitbake/lib/toaster/manage.py migrate bldcontrol
741
742 $ service apache2 restart
743 </literallayout>
744 You can find general documentation on
745 <filename>manage.py</filename> at the
746 <ulink url='https://docs.djangoproject.com/en/1.7/ref/django-admin/'>Django</ulink>
747 site.
748 For reference information on Toaster-specific
749 <filename>manage.py</filename> commands,
750 see the
751 "<link linkend='toaster-useful-commands'>Useful Commands</link>"
752 section.
753 </para></listitem>
754 <listitem><para><emphasis>Enable Build Logging to the Common SQL Server for Each Build Directory you are Using:</emphasis>
755 You need to make sure that the
756 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-toaster'><filename>toaster</filename></ulink>
757 class and build history are enabled.
758 This is done in a
759 <filename>toaster.conf</filename> file that is
760 created automatically by the toaster
761 <filename>start</filename> command,
762 and that lives inside the
763 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
764 in <filename>/conf/toaster.conf</filename>.</para>
765 <para>That file should include the following line:
766 <literallayout class='monospaced'>
767 INHERIT += "toaster buildhistory"
768 </literallayout>
769 For information on build history, see the
770 "<ulink url='&YOCTO_DOCS_REF_URL;#maintaining-build-output-quality'>Maintaining Build Output Quality</ulink>"
771 section in the Yocto Project Development
772 Manual.</para>
773 <para>You also need to point to the database that you set
774 up in step 3.
775 You can do this by exporting the <filename>DATABASE_URL</filename>
776 variable as follows:
777 <literallayout class='monospaced'>
778 export DATABASE_URL=mysql://newuser:password@192.168.0.25:3306/toaster
779 </literallayout>
780 This example assumes that you are using
781 <filename>mysql-server</filename>.
782 The IP address should be the IP address of your
783 database server.
784 </para></listitem>
785 <listitem><para><emphasis>Source your Build Environment Setup Script:</emphasis>
786 From your
787 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>
788 on each of the build systems,
789 (e.g. <filename>poky/build</filename>), source the
790 build environment setup script (i.e.
791 <ulink url="&YOCTO_DOCS_REF_URL;#structure-core-script"><filename>&OE_INIT_FILE;</filename></ulink>
792 or
793 <ulink url="&YOCTO_DOCS_REF_URL;#structure-memres-core-script"><filename>oe-init-build-env-memres</filename></ulink>).
794 </para></listitem>
795 <listitem><para><emphasis>Start the BitBake Server:</emphasis>
796 Start the BitBake server using the following command:
797 <literallayout class='monospaced'>
798 $ bitbake &dash;&dash;postread conf/toaster.conf &dash;&dash;server-only -t xmlrpc -B localhost:0 &amp;&amp; export BBSERVER=localhost:-1
799 </literallayout>
800 </para></listitem>
801 <listitem><para><emphasis>Start the Logging Server:</emphasis>
802 Start the Toaster Logging Interface using the following
803 command:
804 <literallayout class='monospaced'>
805 $ nohup bitbake &dash;&dash;observe-only -u toasterui >toaster_ui.log &amp;
806 </literallayout>
807 <note>
808 No hard-coded ports are used in the BitBake options
809 as there is enough code to run
810 <filename>autodiscovery</filename> for BitBake
811 ports.
812 Doing so prevents collisions.
813 </note>
814 </para></listitem>
815 <listitem><para><emphasis>Start Builds Using BitBake:</emphasis>
816 Use the <filename>bitbake</filename> command to start a
817 build on a build system.
818 Here is an example that builds the
819 <filename>core-image-minimal</filename> image:
820 <literallayout class='monospaced'>
821 $ bitbake core-image-minimal
822 </literallayout>
823 When you are finished with a build in a given
824 Build Directory, be sure to <filename>kill</filename>
825 the BitBake server for that build area:
826 <literallayout class='monospaced'>
827 $ bitbake -m
828 </literallayout>
829 </para></listitem>
830 </orderedlist>
831 </para>
832
833 <para>
834 For information on how to use the Toaster web interface,
835 see the
836 "<link linkend='using-the-toaster-web-interface'>Using the Toaster Web Interface</link>"
837 section.
838 </para>
839 </section>
840 </section>
841
842 <section id='using-toaster-in-build-mode'>
843 <title>Using Toaster in Build Mode</title>
844
845 <para>
846 This section describes how to use Toaster in Build Mode
847 after setting Toaster up as a local instance or as a hosted
848 service.
849 </para>
850
851 <section id='setting-up-locally-and-running-in-build-mode'>
852 <title>Setting Up Locally and Running in Build Mode</title>
853
854 <para>
855 Follow these steps to set up a local instance of Toaster and
856 then run in Build Mode:
857 <orderedlist>
858 <listitem><para><emphasis>Prepare your Build System:</emphasis>
859 Be sure your system has the Toaster requirements
860 by following the steps in the
861 "<link linkend='toaster-establishing-toaster-system-dependencies'>Establishing Toaster System Dependencies</link>"
862 section.
863 </para></listitem>
864 <listitem><para><emphasis>Get Set Up to Use the Yocto Project:</emphasis>
865 Get the requirements set up so that you can use the
866 Yocto Project to build images.
867 See the
868 "<ulink url='&YOCTO_DOCS_QS_URL;#yp-resources'>Setting Up to Use the Yocto Project</ulink>"
869 section in the Yocto Project Quick Start for information.
870 </para></listitem>
871 <listitem><para><emphasis>Start Toaster:</emphasis>
872 From the root of the source directory (e.g
873 <filename>poky/</filename>), run the following command:
874 <literallayout class='monospaced'>
875 $ bitbake/bin/toaster
876 </literallayout>
877 </para></listitem>
878 <listitem><para><emphasis>Create a Superuser:</emphasis>
879 Django will ask you if you want to create a superuser.
880 You can skip this step, but it is recommended that you
881 create a superuser.
882 You can use the superuser to access the Django
883 administration interface and make changes to the
884 Toaster configuration.
885 </para></listitem>
886 <listitem><para><emphasis>Select the Build Log Directory:</emphasis>
887 Toaster asks you to specify the directory where you
888 want to store the build log files.
889 Choosing a directory for these files makes sure they
890 are always available to you.
891 If you do not choose a directory, the logs can
892 disappear (e.g. deleting the Build Directory).</para>
893 <para>When Toaster prompts you for the Build Log
894 directory, you can select the suggested default
895 or provide a path to a different directory.
896 </para></listitem>
897 <listitem><para><emphasis>Specify the Layer Checkout Directory:</emphasis>
898 Toaster asks you to specify the directory into which
899 layers are checked out.
900 Toaster clones any layers needed for your builds
901 inside this directory.</para>
902 <para>When Toaster prompts you for the Layer
903 checkout directory, you can select the suggested
904 default or provide a path to a different directory.
905 </para></listitem>
906 <listitem><para><emphasis>Specify the Build Directory Path:</emphasis>
907 Toaster asks you to specify the path to the
908 Build Directory.
909 You can select the suggested default or provide a
910 path to a different directory.
911 </para></listitem>
912 <listitem><para><emphasis>Choose Whether or not to Import a Default Toaster Configuration File:</emphasis>
913 Toaster asks you if you want to import a default
914 Toaster configuration file.
915 Toaster configurations are stored in
916 JSON files called
917 <filename>toasterconf.json</filename>.
918 For information on JSON files, see the
919 "<link linkend='toaster-json-files'>JSON Files</link>"
920 section.</para>
921 <para>You can skip importing a configuration file
922 by entering "0" at the prompt.
923 However, it is recommended that you import one of the
924 configuration files listed during this step.
925 You can always amend the imported configuration during
926 a later stage through the Django administration
927 interface.</para>
928 <para>For general information on Django, see the
929 available
930 <ulink url='https://docs.djangoproject.com/en/1.7/'>documentation</ulink>.
931 You can also find information on Toaster-specific
932 <filename>manage.py</filename> commands in the
933 "<link linkend='toaster-useful-commands'>Useful Commands</link>"
934 section.
935 </para></listitem>
936 <listitem><para><emphasis>Open the Browser:</emphasis>
937 If no browser window appears, open your favorite
938 browser and enter the following:
939 <literallayout class='monospaced'>
940 http://localhost:8000/toastergui
941 </literallayout>
942 You can now use the Toaster web interface.
943 </para></listitem>
944 </orderedlist>
945 </para>
946 </section>
947
948 <section id='setting-up-a-hosted-service-and-running-in-build-mode'>
949 <title>Setting Up a Hosted Service and Running in Build Mode</title>
950
951 <para>
952 Follow these steps to set up a hosted service and run Toaster
953 in Build Mode:
954 <orderedlist>
955 <listitem><para><emphasis>Prepare your Build System:</emphasis>
956 Be sure your system has the Toaster requirements
957 by following the steps in the
958 "<link linkend='toaster-establishing-toaster-system-dependencies'>Establishing Toaster System Dependencies</link>"
959 section.
960 </para></listitem>
961 <listitem><para><emphasis>Get Set Up to Use the Yocto Project:</emphasis>
962 Get the requirements set up so that you can use the
963 Yocto Project to build images.
964 See the
965 "<ulink url='&YOCTO_DOCS_QS_URL;#yp-resources'>Setting Up to Use the Yocto Project</ulink>"
966 section in the Yocto Project Quick Start for information.
967 </para></listitem>
968 <listitem><para><emphasis>Be Sure Management is Enabled:</emphasis>
969 If you are running Toaster under Apache, you need to
970 be sure management is enabled.
971 To enable management, set
972 <filename>MANAGED</filename> to "True" by adding
973 the following to the
974 <filename>bitbake/lib/toaster/settings.py</filename>
975 file:
976 <literallayout class='monospaced'>
977 MANAGED="True"
978 </literallayout>
979 </para></listitem>
980 <listitem><para><emphasis>Set Up Toaster for Normal Usage:</emphasis>
981 You need to configure each build environment, layer
982 sources, and BitBake versions.</para>
983 <para>Verify that your releases have been loaded correctly by
984 using the Toaster web interface to create a new
985 project.
986 Check the "Releases" dropdown menu to be sure your
987 newly specified releases exist.</para>
988 <para>If you want to use the administration interface
989 for this step, here is a set of example commands
990 with some descriptions as an example:
991 <literallayout class='monospaced'>
992 # Create the user under which the builds will run
993 $ adduser poky
994
995 # Bring up the administration interface
996 $xdg-open http://<replaceable>server-address</replaceable>/admin/
997
998 # Login with the admin user previously created
999
1000 # Go to the BuildEnvironment object in Build Environments and
1001 # set address to local host, sourcedir to /home/poky, and
1002 # builddir to /home/pokybuild.
1003 #
1004 # Save your changes and exit
1005
1006 # Go to Home, Layer Sources and select add Layer Source
1007 # Name: OpenEmbedded, Sourcetype: layerindex,
1008 # Apiurl: http://layers openembedded.org/layerindex/api/
1009 # Save your changes and exit
1010
1011 # Go to Home, Bitbake Versions, Add bitbake version;
1012 # Take version information from: http://git.openembedded.org/bitbake/refs/heads,
1013 # This example assumes "master" version.
1014 # set Name: master, Giturl git://git.openembedded.org/bitbake
1015 # branch master, dirpath /
1016 # Save your changes and exit
1017 </literallayout>
1018 You also need to configure the project releases, the
1019 default variables, and update information from the
1020 layer index.
1021 Continuing with the example:
1022 <literallayout class='monospaced'>
1023 # Go to Home, Releases, Add release
1024 # set Name: master, Description: Current master release, select Bitbake Version,
1025 # and Branch: master
1026 # Save your changes and exit
1027
1028 # Go to Home, Toaster Settings, select the Setting for DEFAULT_RELEASE
1029 # set Helptext: This selects the default release., Value: master
1030 # Save your changes and exit
1031
1032 # Go to Home, Bitbake Versions, Add bitbake version;
1033 # take version information from : http://git.openembedded.org/bitbake/refs/heads,
1034 # this manual assumes the master version
1035 # set Name: master, Giturl git://git.openembedded.org/bitbake
1036 # branch master, dirpath /
1037 # Save your changes and exit
1038
1039 # Update the information
1040 # bitbake/lib/toaster/manage.py lsupdates
1041 </literallayout>
1042 For reference information on Toaster-specific
1043 <filename>manage.py</filename> commands, see the
1044 "<link linkend='toaster-useful-commands'>Useful Commands</link>"
1045 section.
1046 </para></listitem>
1047 <listitem><para><emphasis>Install and Set up the Database Server:</emphasis>
1048 You can use any SQL server out of the box.
1049 It is recommended that you use
1050 <filename>mysql-server</filename> because it has
1051 the advantages of advanced SQL features along with a
1052 fast and reliable database.
1053 However, setting up <filename>mysql-server</filename>
1054 is more complex and might require a Database
1055 Administrator to tune it.</para>
1056 <para>Another supported database backend is
1057 <filename>sqlite3</filename>.
1058 With <filename>sqlite3</filename>, you have the
1059 advantage of no configuration and an easy installation.
1060 However, Toaster still requires direct access to the
1061 backend.
1062 The <filename>sqlite</filename> backend is also slower
1063 as compared to <filename>mysql-server</filename>, and
1064 has no transactional support.</para>
1065 <para>You should set up proper username and password
1066 access on the shared database for everyone that will
1067 be using Toaster.
1068 You need administrator rights for the root account,
1069 which is not the same thing as root access on the
1070 machine.
1071 Here is an example that installs
1072 <filename>mysql-server</filename> and sets up
1073 some user accounts and the database.
1074 <literallayout class='monospaced'>
1075 $ apt-get install mysql-server
1076 $ mysql -u root
1077 mysql> CREATE USER 'newuser'@'localhost' IDENTIFIED BY 'password';
1078 mysql> GRANT ALL PRIVILEGES ON * . * TO 'newuser'@'localhost';
1079 mysql> GRANT ALL PRIVILEGES ON * . * TO 'newuser'@'localhost';
1080 mysql> CREATE DATABASE 'toaster';
1081 </literallayout>
1082 You need a separate clone of the
1083 <ulink url='&YOCTO_DOCS_DEV_URL;#source-repositories'>Source Repositories</ulink>
1084 for the Database Server.
1085 This clone is only used for getting the latest Toaster
1086 files.
1087 You can set this up using the following Git command.
1088 Be sure to set up the directory outside of any
1089 Build Directories.
1090 <literallayout class='monospaced'>
1091 $ git clone git://git.yoctoproject.org/poky
1092 </literallayout>
1093 In the separately cloned tree for the Database Server,
1094 edit the
1095 <filename>bitbake/lib/toaster/toastermain/settings.py</filename>
1096 file so that the <filename>DATABASES</filename> value
1097 points to the previously created database server.
1098 Use the username and password established
1099 earlier.
1100 Here is an example:
1101 <literallayout class='monospaced'>
1102 $ cat /opt/bitbake/lib/toaster/toastermain/settings.py
1103 ...
1104 DATABASES = {
1105 'default': {
1106 'ENGINE': 'django.db.backends.mysql',
1107 'NAME': 'toaster',
1108 'USER': 'newuser',
1109 'PASSWORD': 'password',
1110 'HOST': '192.168.0.25',
1111 'PORT': '3306',
1112 }
1113 ...
1114 </literallayout>
1115 </para></listitem>
1116 <listitem><para><emphasis>Create the Database</emphasis>
1117 Use the following commands to create the default
1118 database structure:
1119 <literallayout class='monospaced'>
1120 $ bitbake/lib/toaster/manage.py syncdb
1121 $ bitbake/lib/toaster/manage.py migrate orm
1122 $ bitbake/lib/toaster/manage.py migrate bldcontrol
1123 </literallayout>
1124 The interface asks you if you want to create a
1125 superuser.
1126 Do not skip this step.
1127 You will use the superuser account to access the
1128 administration interface and make changes to the
1129 Toaster configuration.
1130 </para></listitem>
1131 <listitem><para><emphasis>Select Where the Build Process Takes Place:</emphasis>
1132 You need to create three directories for storing
1133 build artifacts, downloading sources, and running
1134 builds.
1135 All three directories need to be writable by
1136 the user, which is "poky" in this example.
1137 The build artifacts directory needs to readable by the
1138 apache user.
1139 You also need free disk space in the range of
1140 100 Gbytes.
1141 Following are three suggested directories:
1142 <literallayout class='monospaced'>
1143 /home/poky/buildartifacts/
1144 /home/poky/build/
1145 /home/poky/sources/
1146 </literallayout>
1147 </para></listitem>
1148 <listitem><para><emphasis>Set Up the <filename>toasterconf.json</filename> File:</emphasis>
1149 <ulink url='https://wiki.yoctoproject.org/wiki/File:Toasterconf.json.txt.patch'>Download the hosted <filename>toasterconf.json</filename> file</ulink>
1150 from the Yocto Project wiki and edit it to suit your
1151 environment.
1152 For information on the relevant sections of the file,
1153 see the
1154 "<link linkend='toaster-json-files'>JSON Files</link>"
1155 section.</para>
1156 <para>After editing the file, load it by running
1157 the following:
1158 <literallayout class='monospaced'>
1159 $ bitbake/lib/toaster/manage.py loadconf path-to-toasterconf.json-file
1160 </literallayout>
1161 For reference information on Toaster-specific
1162 <filename>manage.py</filename>, see the
1163 "<link linkend='toaster-useful-commands'>Useful Commands</link>"
1164 section.
1165 </para></listitem>
1166 <listitem><para><emphasis>Check the Toaster Settings:</emphasis>
1167 Configure the build environment by running the
1168 following:
1169 <literallayout class='monospaced'>
1170 $ bitbake/lib/toaster/manage.py checksettings
1171 </literallayout>
1172 When prompted, paste in the directory paths created
1173 previously during Step 7.
1174 For reference information on Toaster-specific
1175 <filename>manage.py</filename>, see the
1176 "<link linkend='toaster-useful-commands'>Useful Commands</link>"
1177 section.
1178 </para></listitem>
1179 <listitem><para><emphasis>Install and Set Up the Web Server:</emphasis>
1180 For a production environment, it is recommended that
1181 you install and set up a front-end web server.
1182 This server allows for load balancing and
1183 multi-threading over Toaster and
1184 <ulink url='https://docs.djangoproject.com/en/1.7/howto/deployment/wsgi/'><filename>django</filename> WSGI</ulink>.
1185 Here is an example that uses Apache web server:
1186 <literallayout class='monospaced'>
1187 $ apt-get install apache2 libapache2-mod-wsgi
1188 $ a2enmod wsgi
1189 $ cat /etc/apache2/sites-available/000-default.conf
1190
1191 ...
1192
1193 # the WSGIPythonPath is global
1194 WSGIPythonPath /opt/bitbake/lib/toaster/
1195
1196 ...
1197
1198 #snip - in VirtualHost
1199 WSGIScriptAlias / /opt/bitbake/lib/toaster/toastermain/wsgi.py
1200
1201 &lt;Directory //opt/bitbake/lib/toaster/toastermain/&gt;
1202 &lt;Files wsgi.py&gt;
1203 Require all granted
1204 &lt;/Files&gt;
1205 &lt;/Directory&gt;
1206
1207 ...
1208 </literallayout>
1209 You need to collect static media from Toaster and
1210 continue configuring Apache to serve that static
1211 media:
1212 <literallayout class='monospaced'>
1213 $ mkdir /var/www.html/static &amp;&amp; cd /var/www.html/static
1214 $ /opt bitbake/lib/toaster/manage.py collectstatic
1215 $ cat /etc/apache2/sites-available/000-default.conf
1216
1217 ...
1218
1219 # in VirtualHost, AHEAD of the WSGIScriptAlias definition
1220 Alias /static/ /var/www.html/static/
1221
1222 &lt;Directory /var/www.html/static/&gt;
1223 Require all granted
1224 &lt;/Directory&gt;
1225
1226 ...
1227
1228 WSGIScript Alias / /opt/bitbake/lib/toaster/toastermain/wsgi.py
1229
1230 ...
1231 </literallayout>
1232 </para></listitem>
1233 <listitem><para><emphasis>Start Toaster:</emphasis>
1234 Synchronize the databases for Toaster, and then start
1235 up the web server.
1236 Here is an example that continues with the assumed
1237 components from the previous steps:
1238 <literallayout class='monospaced'>
1239 $ /opt/bitbake/lib/toaster/manage.py syncdb
1240 $ /opt/bitbake/lib/toaster/manage.py migrate orm
1241 $ /opt/bitbake/lib/toaster/manage.py migrate bldcontrol
1242
1243 $ service apache2 restart
1244 </literallayout>
1245 For reference information on the
1246 <filename>manage.py</filename> commands used here,
1247 see the
1248 "<link linkend='toaster-useful-commands'>Useful Commands</link>"
1249 section.
1250 </para></listitem>
1251 <listitem><para><emphasis>Set up Build Control and Open the Web Interface:</emphasis>
1252 You need to run the build control manager.
1253 You can do this as shown in the following example:
1254 <literallayout class='monospaced'>
1255 # as the "poky" user, start the runbuilds command in a loop (or put it in crontab!)
1256 $ sudo -i -u poky
1257 $ while true; do /opt/bitbake/lib/toaster/manage.py runbuilds; sleep 10; done
1258
1259 # open up the web interface
1260 $ xdg-open http://[server-address]/toastergui/
1261 </literallayout>
1262 It is suggested that you enable build control by
1263 setting <filename>runbuilds</filename> in the
1264 <filename>crontab</filename> as follows:
1265 <literallayout class='monospaced'>
1266 $ crontab -l
1267 * * * * * /opt/bitbake/lit/toaster/manage.py runbuilds
1268 </literallayout>
1269 </para></listitem>
1270 <listitem><para><emphasis>Open the Browser:</emphasis>
1271 Once the Apache server is running, connect to it with
1272 your favorite browser and verify that the Toaster
1273 interface comes up:
1274 <literallayout class='monospaced'>
1275 http://localhost:8000/toastergui
1276 </literallayout>
1277 You can track accesses and errors in the Apache
1278 service logs.
1279 </para></listitem>
1280 </orderedlist>
1281 </para>
1282 </section>
1283 </section>
1284-->
1285
1286 <section id='using-the-toaster-web-interface'> 478 <section id='using-the-toaster-web-interface'>
1287 <title>Using the Toaster Web Interface</title> 479 <title>Using the Toaster Web Interface</title>
1288 480
@@ -1453,105 +645,4 @@
1453 </para> 645 </para>
1454 </section> 646 </section>
1455 </section> 647 </section>
1456
1457<!--
1458 <section id='toaster-gui-vids-1'>
1459 <title>Toaster Homepage and Table Controls</title>
1460
1461 <para>
1462 This video goes over the Toaster entry page, and provides
1463 an overview of the data manipulation capabilities of Toaster,
1464 which include search, sorting and filtering by different
1465 criteria.
1466 <mediaobject>
1467 <videoobject>
1468 <videodata width="640" height="480" fileref="http://www.youtube.com/v/QEARDnrR1Xw"></videodata>
1469 </videoobject>
1470 </mediaobject>
1471 </para>
1472 </section>
1473
1474 <section id='toaster-gui-vids-2'>
1475 <title>Build Dashboard</title>
1476
1477 <para>
1478 This video shows you the build dashboard, a page providing an
1479 overview of the information available for a selected build.
1480 <mediaobject>
1481 <videoobject>
1482 <videodata width="640px" height="480px" fileref="http://www.youtube.com/v/KKqHYcnp2gE"></videodata>
1483 </videoobject>
1484 </mediaobject>
1485 </para>
1486 </section>
1487
1488 <section id='toaster-gui-vids-3'>
1489 <title>Image Information</title>
1490
1491 <para>
1492 This video walks through the information Toaster provides
1493 about images: packages installed and root file system.
1494 <mediaobject>
1495 <videoobject>
1496 <videodata width="640px" height="480px" fileref="http://www.youtube.com/v/XqYGFsmA0Rw"></videodata>
1497 </videoobject>
1498 </mediaobject>
1499 </para>
1500 </section>
1501
1502 <section id='toaster-gui-vids-4'>
1503 <title>Configuration</title>
1504
1505 <para>
1506 This video shows the information Toaster provides about build
1507 configuration.
1508 <mediaobject>
1509 <videoobject>
1510 <videodata width="640px" height="480px" fileref="http://www.youtube.com/v/UW-j-T2TzIg"></videodata>
1511 </videoobject>
1512 </mediaobject>
1513 </para>
1514 </section>
1515
1516 <section id='toaster-gui-vids-5'>
1517 <title>Tasks</title>
1518
1519 <para>
1520 This video shows the information Toaster provides about the
1521 tasks run by the build system.
1522 <mediaobject>
1523 <videoobject>
1524 <videodata width="640px" height="480px" fileref="http://www.youtube.com/v/D4-9vGSxQtw"></videodata>
1525 </videoobject>
1526 </mediaobject>
1527 </para>
1528 </section>
1529
1530 <section id='toaster-gui-vids-6'>
1531 <title>Recipes and Packages Built</title>
1532
1533 <para>
1534 This video shows the information Toaster provides about recipes
1535 and packages built.
1536 <mediaobject>
1537 <videoobject>
1538 <videodata width="640px" height="480px" fileref="http://www.youtube.com/v/x-6dx4huNnw"></videodata>
1539 </videoobject>
1540 </mediaobject>qYgDZ8YzV6w
1541 </para>
1542 </section>
1543 <section id='toaster-gui-vids-7'>
1544 <title>Performance Data</title>
1545
1546 <para>
1547 This video shows the build performance data provided by
1548 Toaster.
1549 <mediaobject>
1550 <videoobject>
1551 <videodata width="640px" height="480px" fileref="http://www.youtube.com/v/qWGMrJoqusQ"></videodata>
1552 </videoobject>
1553 </mediaobject>
1554 </para>
1555 </section>
1556-->
1557</chapter> 648</chapter>
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2024-05-06 00:33:50 +0000