summaryrefslogtreecommitdiffstats
path: root/documentation/toaster-manual/toaster-manual-setup-and-use.xml
blob: 74c00c498c2aa5583bdf04914e3f96d547cef313 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
<!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='starting-toaster-for-local-development'>
        <title>Starting Toaster for Local Development</title>

        <para>
            Once you have set up the Yocto Project and installed the
            Toaster system dependencies as described in
            "<link linkend='toaster-manual-start'>Preparing to Use Toaster</link>",
            you are ready to start Toaster.
        </para>

        <para>
            If you want to configure and start your builds using the
            Toaster web interface
            (i.e. "<link linkend='toaster-build-mode'>Build Mode</link>"),
            navigate to the root of your
            <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>
            (e.g. <filename>poky</filename>):
            <literallayout class='monospaced'>
     $ cd poky
            </literallayout>
            Next, start Toaster:
            <literallayout class='monospaced'>
     $ bitbake/bin/toaster
            </literallayout>
            Open your favourite browser and enter the following:
            <literallayout class='monospaced'>
     http://127.0.0.1:8000
            </literallayout>
            If you would rather configure and start your builds
            using the command line
            (i.e. <link linkend='toaster-analysis-mode'>Analysis Mode</link>),
            you can get Toaster to "listen"
            to your builds and collect information about them.
            To do that, navigate to the root of your Source Directory:
            <literallayout class='monospaced'>
     $ cd poky
            </literallayout>
            Once in that directory, source the build environment script:
            <literallayout class='monospaced'>
     $ source oe-init-build-env
            </literallayout>
            Next, from the build directory (e.g.
            <filename>poky/build</filename>), start Toaster using this
            command:
            <literallayout class='monospaced'>
     $ source ../bitbake/bin/toaster
            </literallayout>
            You can now run builds normally.
        </para>

        <para>
            To see the build information provided by Toaster, open your
            favorite browser and enter the following:
            <literallayout class='monospaced'>
     http://127.0.0.1:8000
            </literallayout>
        </para>
    </section>

    <section id='setting-a-different-port'>
        <title>Setting a Different Port</title>

        <para>
            By default, Toaster starts on port 8000.
            You can use the <filename>WEBPORT</filename> parameter to
            set a different port.
            For example, either of the following commands sets the
            port to "8400":
            <literallayout class='monospaced'>
     $ bitbake/bin/toaster webport=8400
            </literallayout>
            or
            <literallayout class='monospaced'>
     $ source ../bitbake/bin/toaster webport=8400
            </literallayout>
        </para>
    </section>

    <section id='the-directory-for-cloning-layers'>
        <title>The Directory for Cloning Layers</title>

        <para>
            If you are running Toaster in
            <link linkend='toaster-build-mode'>Build Mode</link>,
            Toaster creates a <filename>_toaster_clones</filename>
            directory inside your Source Directory
            (i.e. <filename>poky</filename>).
            For example, suppose you use this command to start Toaster:
            <literallayout class='monospaced'>
     poky/bitbake/bin/toaster
            </literallayout>
            In this example, Toaster creates and uses the
            <filename>poky/_toaster_clones</filename>
            directory to clone any layers needed for your builds.
        </para>

        <para>
            Alternatively, if you would like all of your Toaster related
            files and directories to be in a particular location other than
            the default, you can set the <filename>TOASTER_DIR</filename>
            environment variable, which takes precedence over your current
            working directory.
            Setting this environment variable causes Toaster to create and use
            <filename>$TOASTER_DIR./_toaster_clones</filename>.
        </para>
    </section>

    <section id='toaster-the-build-directory'>
        <title>The Build Directory</title>

        <para>
            If you are running Toaster in
            <link linkend='toaster-build-mode'>Build Mode</link>,
            Toaster creates a build directory within your Source
            Directory (e.g. <filename>poky</filename>).
            For example, suppose you use this command to start Toaster:
            <literallayout class='monospaced'>
     poky/bitbake/bin/toaster
            </literallayout>
            In this example, Toaster creates and uses the
            <filename>poky/build</filename>
            directory to execute the builds.
        </para>

        <para>
            Alternatively, if you would like all of your Toaster related files
            and directories to be in a particular location, you can set
            the <filename>TOASTER_DIR</filename> environment variable,
            which takes precedence over your current working directory.
            Setting this environment variable causes Toaster to use
            <filename>$TOASTER_DIR./build</filename> as the build directory.
        </para>
    </section>

    <section id='toaster-creating-a-django-super-user'>
        <title>Creating a Django Superuser</title>

        <para>
            Toaster is built on the
            <ulink url='https://www.djangoproject.com/'>Django framework</ulink>.
            Django provides an administration interface you can use
            to edit Toaster configuration parameters.
        </para>

        <para>
            To access the Django administration interface, you must
            create a superuser by following these steps:
            <orderedlist>
                <listitem><para>
                    If you used <filename>virtualenv</filename>, which is
                    recommended, to set up the Toaster system dependencies,
                    you need be sure the virtual environment is activated.
                    To activate this environment, use the following:
                    <literallayout class='monospaced'>
     $ source venv/bin/activate
                    </literallayout>
                    </para></listitem>
                <listitem><para>
                    From the root of your checkout directory, invoke the
                    following command from <filename>manage.py</filename>:
                    <literallayout class='monospaced'>
     $ ./bitbake/lib/toaster/manage.py createsuperuser
                    </literallayout>
                    </para></listitem>
                <listitem><para>
                    Django prompts you for the username, which you need to
                    provide.
                    </para></listitem>
                <listitem><para>
                    Django prompts you for an email address, which is
                    optional.
                    </para></listitem>
                <listitem><para>
                    Django prompts you for a password, which you must provide.
                    </para></listitem>
                <listitem><para>
                    Django prompts you to re-enter your password for verification.
                    </para></listitem>
            </orderedlist>
            After completing these steps, the following confirmation message
            appears:
            <literallayout class='monospaced'>
     Superuser created successfully.
            </literallayout>
        </para>

        <para>
            Creating a superuser allows you to access the Django administration
            interface through a browser.
            The URL for this interface is the same as the URL used for the
            Toaster instance with "/admin" on the end.
            For example, if you are running Toaster locally, use the
            following URL:
            <literallayout class='monospaced'>
     http://127.0.0.1:8000/admin
            </literallayout>
            You can use the Django administration interface to set Toaster
            configuration parameters such as the build directory, layer sources,
            default variable values, and BitBake versions.
        </para>
    </section>

    <section id='toaster-setting-up-a-production-instance-of-toaster'>
        <title>Setting Up a Production Instance of Toaster</title>

        <para>
            You can use a production instance of Toaster to share the
            Toaster instance with remote users, multiple users, or both.
            The production instance is also the setup that can cope with
            heavier loads on the web service.
            Use the instructions in the following sections to set up
            Toaster in
            <link linkend='toaster-build-mode'>Build Mode</link>
            where builds and projects are run,
            viewed, and defined through the Toaster web interface.
        </para>

        <section id='toaster-production-instance-requirements'>
            <title>Requirements</title>

            <para>
                Be sure you meet the following requirements:
                <note>
                    You must comply with all Apache,
                    <filename>mod-wsgi</filename>, and Mysql requirements.
                </note>
                <itemizedlist>
                    <listitem><para>
                        Have all the build requirements as described in
                        "<link linkend='toaster-setting-up-the-basic-system-requirements'>Setting Up the Basic System Requirements</link>"
                        chapter.
                        </para></listitem>
                    <listitem><para>
                        Have an Apache webserver.
                        </para></listitem>
                    <listitem><para>
                        Have <filename>mod-wsgi</filename> for the Apache
                        webserver.
                        </para></listitem>
                    <listitem><para>
                        Use the Mysql database server.
                        </para></listitem>
                    <listitem><para>
                        If you are using Ubuntu 14.04.3, run the following:
                        <literallayout class='monospaced'>
     $ sudo apt-get install apache2 libapache2-mod-wsgi mysql-server virtualenv libmysqlclient-dev
                        </literallayout>
                        </para></listitem>
                    <listitem><para>
                        If you are using Fedora 22 or a RedHat distribution, run
                        the following:
                        <literallayout class='monospaced'>
     $ sudo dnf install httpd mod_wsgi python-virtualenv gcc mysql-devel
                        </literallayout>
                        </para></listitem>
                </itemizedlist>
            </para>
        </section>

        <section id='toaster-installation-steps'>
            <title>Installation</title>

            <para>
                Perform the following steps to install Toaster:
                <orderedlist>
                    <listitem><para>
                        Checkout a copy of <filename>poky</filename>
                        into the web server directory.
                        You will be using <filename>/var/www/toaster</filename>:
                        <literallayout class='monospaced'>
     $ mkdir -p /var/www/toaster
     $ cd /var/www/toaster/
     $ git clone git://git.yoctoproject.org/poky
     $ git checkout &DISTRO_NAME;
                        </literallayout>
                        </para></listitem>
                    <listitem><para>
                        Initialize a virtual environment and install Toaster
                        dependencies.
                        Using a virtual environment keeps the Python packages
                        isolated from your system-provided packages:
                        <literallayout class='monospaced'>
     $ cd /var/www/toaster/
     $ virtualenv venv
     $ source ./venv/bin/activate
     $ pip install -r ./poky/bitbake/toaster-requirements.txt
     $ pip install mysql
     $ pip install MySQL-python
                        </literallayout>
                        <note>
                            Isolating these packages is not required but is
                            recommended.
                            Alternatively, you can use your operating system's
                            package manager to install the packages.
                        </note>
                        </para></listitem>
                    <listitem><para>
                        Configure Toaster by editing
                        <filename>/var/www/toaster/poky/bitbake/lib/toaster/toastermain/settings.py</filename>
                        as follows:
                        <itemizedlist>
                            <listitem><para>
                                Edit the <filename>DATABASE</filename> settings:
                                <literallayout class='monospaced'>
     DATABASES = {
         'default': {
             'ENGINE': 'django.db.backends.mysql',
             'NAME': 'toaster_data',
             'USER': 'toaster',
             'PASSWORD': 'yourpasswordhere',
             'HOST': 'localhost',
             'PORT': '3306',
     }
                                </literallayout>
                                </para></listitem>
                            <listitem><para>
                                Edit the <filename>SECRET_KEY</filename>:
                                <literallayout class='monospaced'>
     SECRET_KEY = '<replaceable>your_secret_key</replaceable>'
                                </literallayout>
                                </para></listitem>
                            <listitem><para>
                                Edit the <filename>STATIC_ROOT</filename>:
                                <literallayout class='monospaced'>
     STATIC_ROOT = '/var/www/toaster/static_files/'
                                </literallayout>
                                </para></listitem>
                            <listitem><para>
                                Enable Build Mode by adding the following
                                line to <filename>settings.py</filename>:
                                <literallayout class='monospaced'>
     BUILD_MODE=True
                                </literallayout>
                                </para></listitem>
                        </itemizedlist>
                        </para></listitem>
                    <listitem><para>
                        Add the database and user to the <filename>mysql</filename>
                        server defined earlier:
                        <literallayout class='monospaced'>
     $ mysql -u root -p
     mysql> CREATE DATABASE toaster;
     mysql> CREATE USER 'toaster'@'localhost' identified by 'yourpasswordhere';
     mysql> GRANT all on toaster_data.* to 'toaster'@'localhost';
     mysql> quit
                        </literallayout>
                        </para></listitem>
                    <listitem><para>
                        Get Toaster to create the database schema,
                        default data, and gather the statically-served files:
                        <literallayout class='monospaced'>
     $ cd  /var/www/toaster/poky/
     $ ./bitbake/lib/toaster/manage.py syncdb --migrate
     $ ./bitbake/lib/toaster/manage.py loadconf ./meta-yocto/conf/toasterconf.json
     $ ./bitbake/lib/toaster/manage.py lsupdates
     $ ./bitbake/lib/toaster/manage.py collectstatic
                        </literallayout>
                        </para>

                        <para>
                            For the above set of commands, after moving to the
                            <filename>poky</filename> directory,
                            the <filename>syncdb</filename> command with the
                            <filename>migrate</filename> option makes sure the database
                            schema has had changes propagated correctly (i.e.
                            migrations).
                            See the
                            <ulink url='https://south.readthedocs.org/en/latest/commands.html#syncdb'><filename>syncdb</filename></ulink>
                            command for more information.
                        </para>

                        <para>
                            The
                            <link linkend='toaster-command-loadconf'><filename>loadconf</filename></link>
                            command loads the
                            <filename>./meta-yocto/conf/toasterconf.json</filename>
                            JSON file.
                        </para>

                        <para>
                            The <filename>lsupdates</filename> command fetches
                            information about machines, recipes and
                            layers available as part of OpenEmbedded.
                            The information is fetched from the
                            <ulink url='http://layers.openembedded.org/'>OpenEmbedded Metadata Index</ulink>.
                            This information provides easy access to metadata
                            from Toaster, and it is key for Toaster's usability.
                            It is not recommended that you use Toaster without
                            fetching this information."
                        </para>

                        <para>
                            Finally, the <filename>collectstatic</filename> command
                            is a Django framework command that collects all the
                            statically served files into a designated directory to
                            be served up by the Apache web server.
                            For more information on this Django command, see
                            <ulink url='https://docs.djangoproject.com/en/1.7/ref/contrib/staticfiles/'></ulink>.
                        </para></listitem>
                    <listitem><para>
                        Add an Apache configuration file for Toaster to your Apache web
                        server's configuration directory.
                        If you are using Ubuntu or Debian, put the file here:
                        <literallayout class='monospaced'>
     /etc/apache2/conf-available/toaster.conf
                        </literallayout>
                        If you are using Fedora or RedHat, put it here:
                        <literallayout class='monospaced'>
     /etc/httpd/conf.d/toaster.conf
                        </literallayout>
                        Following is a sample Apache configuration for Toaster
                        you can follow:
                        <literallayout class='monospaced'>
     Alias /static /var/www/toaster/static_files
     &lt;Directory /var/www/toaster/static_files&gt;
             Order allow,deny
             Allow from all
             Require all granted
     &lt;/Directory&gt;

     WSGIDaemonProcess toaster_wsgi python-path=/var/www/toaster/poky/bitbake/lib/toaster:/var/www/toaster/venv/lib/python2.7/site-packages

     WSGIScriptAlias / "/var/www/toaster/poky/bitbake/lib/toaster/toastermain/wsgi.py"
     &lt;Location /&gt;
         WSGIProcessGroup toastern_wsgi
     &lt;/Location&gt;
                        </literallayout>
                        If you are using Ubuntu or Debian,
                        you will need to enable the config and module for Apache:
                        <literallayout class='monospaced'>
     $ sudo a2enmod wsgi
     $ sudo a2enconf toaster
                        </literallayout>
                        Finally, restart Apache to make sure all new configuration
                        is loaded.
                        For Ubuntu and Debian use:
                        <literallayout class='monospaced'>
     $ sudo service apache2 restart
                        </literallayout>
                        For Fedora and RedHat use:
                        <literallayout class='monospaced'>
     $ sudo service httpd restart
                        </literallayout>
                        </para></listitem>
                    <listitem><para>
                        Install the build runner service.
                        This service needs to be running in order to dispatch
                        builds.
                        Use this command:
                        <literallayout class='monospaced'>
     /var/www/toaster/poky/bitbake/lib/toaster/manage.py runbuilds
                        </literallayout>
                        Here is an example:
                        <literallayout class='monospaced'>
     #!/bin/sh
     # toaster run builds dispatcher
     cd /var/www/toaster/
     source ./venv/bin/activate
     ./bitbake/lib/toaster/manage.py runbuilds
                        </literallayout>
                        </para></listitem>
                </orderedlist>
                You can now open up a browser and start using Toaster.
            </para>
        </section>
    </section>




<!--    <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'>Setting Up to Use the Yocto Project</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'>Setting Up to Use the Yocto Project</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

     &lt;Directory //opt/bitbake/lib/toaster/toastermain/&gt;
         &lt;Files wsgi.py&gt;
             Require all granted
         &lt;/Files&gt;
     &lt;/Directory&gt;

        ...
                        </literallayout>
                        You need to collect static media from Toaster and
                        continue configuring Apache to serve that static
                        media:
                        <literallayout class='monospaced'>
     $ mkdir /var/www.html/static &amp;&amp; cd /var/www.html/static
     $ /opt/bitbake/lib/toaster/manage.py collectstatic
     $ cat /etc/apache2/sites-available/000-default.conf

        ...

     # in VirtualHost, AHEAD of the WSGIScriptAlias definition
     Alias /static/ /var/www.html/static/

     &lt;Directory /var/www.html/static/&gt;
     Require all granted
     &lt;/Directory&gt;

        ...

     WSGIScript Alias / /opt/bitbake/lib/toaster/toastermain/wsgi.py

        ...
                        </literallayout>
                        </para></listitem>
                    <listitem><para><emphasis>Start Toaster:</emphasis>
                        Synchronize the databases for toaster, and then start
                        up the web server.
                        Here is an example that continues with the assumed
                        components from the previous steps:
                        <literallayout class='monospaced'>
     $ /opt/bitbake/lib/toaster/manage.py syncdb
     $ /opt/bitbake/lib/toaster/manage.py migrate orm
     $ /opt/bitbake/lib/toaster/manage.py migrate bldcontrol

     $ service apache2 restart
                        </literallayout>
                        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 &dash;&dash;postread conf/toaster.conf &dash;&dash;server-only -t xmlrpc -B localhost:0 &amp;&amp; export BBSERVER=localhost:-1
                        </literallayout>
                        </para></listitem>
                    <listitem><para><emphasis>Start the Logging Server:</emphasis>
                        Start the Toaster Logging Interface using the following
                        command:
                        <literallayout class='monospaced'>
     $ nohup bitbake &dash;&dash;observe-only -u toasterui >toaster_ui.log &amp;
                        </literallayout>
                        <note>
                            No hard-coded ports are used in the BitBake options
                            as there is enough code to run
                            <filename>autodiscovery</filename> for BitBake
                            ports.
                            Doing so prevents collisions.
                        </note>
                        </para></listitem>
                    <listitem><para><emphasis>Start Builds Using BitBake:</emphasis>
                        Use the <filename>bitbake</filename> command to start a
                        build on a build system.
                        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'>Setting Up to Use the Yocto Project</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'>Setting Up to Use the Yocto Project</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

     &lt;Directory //opt/bitbake/lib/toaster/toastermain/&gt;
         &lt;Files wsgi.py&gt;
             Require all granted
         &lt;/Files&gt;
     &lt;/Directory&gt;

        ...
                        </literallayout>
                        You need to collect static media from Toaster and
                        continue configuring Apache to serve that static
                        media:
                        <literallayout class='monospaced'>
     $ mkdir /var/www.html/static &amp;&amp; cd /var/www.html/static
     $ /opt bitbake/lib/toaster/manage.py collectstatic
     $ cat /etc/apache2/sites-available/000-default.conf

        ...

     # in VirtualHost, AHEAD of the WSGIScriptAlias definition
     Alias /static/ /var/www.html/static/

     &lt;Directory /var/www.html/static/&gt;
     Require all granted
     &lt;/Directory&gt;

        ...

     WSGIScript Alias / /opt/bitbake/lib/toaster/toastermain/wsgi.py

        ...
                        </literallayout>
                        </para></listitem>
                    <listitem><para><emphasis>Start Toaster:</emphasis>
                        Synchronize the databases for Toaster, and then start
                        up the web server.
                        Here is an example that continues with the assumed
                        components from the previous steps:
                        <literallayout class='monospaced'>
     $ /opt/bitbake/lib/toaster/manage.py syncdb
     $ /opt/bitbake/lib/toaster/manage.py migrate orm
     $ /opt/bitbake/lib/toaster/manage.py migrate bldcontrol

     $ service apache2 restart
                        </literallayout>
                        For reference information on the
                        <filename>manage.py</filename> commands used here,
                        see the
                        "<link linkend='toaster-useful-commands'>Useful Commands</link>"
                        section.
                        </para></listitem>
                    <listitem><para><emphasis>Set up Build Control and Open the Web Interface:</emphasis>
                        You need to run the build control manager.
                        You can do this as shown in the following example:
                        <literallayout class='monospaced'>
     # as the "poky" user, start the runbuilds command in a loop (or put it in crontab!)
     $ sudo -i -u poky
     $ while true; do /opt/bitbake/lib/toaster/manage.py runbuilds; sleep 10; done

     # open up the web interface
     $ xdg-open http://[server-address]/toastergui/
                        </literallayout>
                        It is suggested that you enable build control by
                        setting <filename>runbuilds</filename> in the
                        <filename>crontab</filename> as follows:
                        <literallayout class='monospaced'>
     $ crontab -l
     * * * * *  /opt/bitbake/lit/toaster/manage.py runbuilds
                        </literallayout>
                        </para></listitem>
                    <listitem><para><emphasis>Open the Browser:</emphasis>
                        Once the Apache server is running, connect to it with
                        your favorite browser and verify that the Toaster
                        interface comes up:
                        <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>
        </para>

        <section id='web-interface-videos'>
            <title>Toaster Web Interface Videos</title>

            <para>
                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>Build Custom Layers:</emphasis>
                        This
                        <ulink url='https://www.youtube.com/watch?v=QJzaE_XjX5c'>video</ulink>
                        shows you how to build custom layers that are used with
                        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-web-interface-preferred-version'>
            <title>Building a Specific Recipe Given Multiple Versions</title>

            <para>
                Occasionally, a layer might provide more than one version of
                the same recipe.
                For example, the <filename>openembedded-core</filename> layer
                provides two versions of the <filename>bash</filename> recipe
                (i.e. 3.2.48 and 4.3.30-r0) and two versions of the
                <filename>which</filename> recipe (i.e. 2.21 and 2.18).
                The following figure shows this exact scenario:
                <imagedata fileref="figures/bash-oecore.png" align="center" width="9in" depth="6in" />
            </para>

            <para>
                By default, the OpenEmbedded build system builds one of the
                two recipes.
                For the <filename>bash</filename> case, version 4.3.30-r0 is
                built by default.
                Unfortunately, Toaster as it exists, is not able to override
                the default recipe version.
                If you would like to build bash 3.2.48, you need to set the
                <ulink url='&YOCTO_DOCS_REF_URL;#var-PREFERRED_VERSION'><filename>PREFERRED_VERSION</filename></ulink>
                variable.
                You can do so from Toaster, using the "Add variable" form,
                which is available in the "BitBake variables" page of the
                project configuration section as shown in the following screen:
                <imagedata fileref="figures/add-variable.png" align="center" width="9in" depth="6in" />
            </para>

            <para>
                To specify <filename>bash</filename> 3.2.48 as the version to build,
                enter "PREFERRED_VERSION_bash" in the "Variable" field, and "3.2.48"
                in the "Value" field.
                Next, click the "Add variable" button:
                <imagedata fileref="figures/set-variable.png" align="center" width="9in" depth="6in" />
            </para>

            <para>
                After clicking the "Add variable" button, the settings for
                <filename>PREFERRED_VERSION</filename> are added to the bottom
                of the BitBake variables list.
                With these settings, the OpenEmbedded build system builds the
                desired version of the recipe rather than the default version:
                <imagedata fileref="figures/variable-added.png" align="center" width="9in" depth="6in" />
            </para>
        </section>
    </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>