summaryrefslogtreecommitdiffstats
path: root/documentation/toaster-manual/toaster-manual-setup-and-use.xml
diff options
context:
space:
mode:
Diffstat (limited to 'documentation/toaster-manual/toaster-manual-setup-and-use.xml')
-rw-r--r--documentation/toaster-manual/toaster-manual-setup-and-use.xml920
1 files changed, 765 insertions, 155 deletions
diff --git a/documentation/toaster-manual/toaster-manual-setup-and-use.xml b/documentation/toaster-manual/toaster-manual-setup-and-use.xml
index f56d67ed37..b148d4f405 100644
--- a/documentation/toaster-manual/toaster-manual-setup-and-use.xml
+++ b/documentation/toaster-manual/toaster-manual-setup-and-use.xml
@@ -6,12 +6,6 @@
6 6
7<title>Setting Up and Using Toaster</title> 7<title>Setting Up and Using Toaster</title>
8 8
9 <para>
10 You can set up Toaster as a local instance or as a hosted service.
11 Furthermore, you can use Toaster in Analysis Mode or Build Mode
12 from both set ups.
13 </para>
14
15 <section id='using-toaster-in-analysis-mode'> 9 <section id='using-toaster-in-analysis-mode'>
16 <title>Using Toaster in Analysis Mode</title> 10 <title>Using Toaster in Analysis Mode</title>
17 11
@@ -41,19 +35,14 @@
41 "<ulink url='&YOCTO_DOCS_QS_URL;#yp-resources'>What You Need and How You Get It</ulink>" 35 "<ulink url='&YOCTO_DOCS_QS_URL;#yp-resources'>What You Need and How You Get It</ulink>"
42 section in the Yocto Project Quick Start for information. 36 section in the Yocto Project Quick Start for information.
43 </para></listitem> 37 </para></listitem>
44 <listitem><para><emphasis>Be Sure Ports are Free:</emphasis>
45 Make sure that port 8000 and 8200 are free.
46 In other words, make sure the ports do not have servers
47 on them.
48 </para></listitem>
49 <listitem><para><emphasis>Source your Build Environment Setup Script:</emphasis> 38 <listitem><para><emphasis>Source your Build Environment Setup Script:</emphasis>
50 From your 39 From your
51 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink> 40 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>
52 (e.g. <filename>poky/build</filename>), source the build 41 (e.g. <filename>poky/build</filename>), source the build
53 environment setup script (i.e. 42 environment setup script
54 <ulink url="&YOCTO_DOCS_REF_URL;#structure-core-script"><filename>&OE_INIT_FILE;</filename></ulink> 43 <ulink url="&YOCTO_DOCS_REF_URL;#structure-core-script"><filename>&OE_INIT_FILE;</filename></ulink>
55 or 44 or
56 <ulink url="&YOCTO_DOCS_REF_URL;#structure-memres-core-script"><filename>oe-init-build-env-memres</filename></ulink>). 45 <ulink url="&YOCTO_DOCS_REF_URL;#structure-memres-core-script"><filename>oe-init-build-env-memres</filename></ulink>.
57 </para></listitem> 46 </para></listitem>
58 <listitem><para><emphasis>Start Toaster:</emphasis> 47 <listitem><para><emphasis>Start Toaster:</emphasis>
59 From the 48 From the
@@ -72,13 +61,20 @@
72 $ bitbake core-image-minimal 61 $ bitbake core-image-minimal
73 </literallayout> 62 </literallayout>
74 </para></listitem> 63 </para></listitem>
64 <listitem><para><emphasis>Open Your Browser:</emphasis>
65 Open your browser and visit
66 <filename>http://host:port/toastergui</filename>.
67 For host and port values, see the output of the
68 <filename>source toaster start</filename> command.
69 For information on how to use Toaster, see the
70 "<link linkend='using-the-toaster-web-interface'>Using the Toaster Web Interface</link>"
71 section.
72 </para></listitem>
75 </orderedlist> 73 </orderedlist>
76 </para> 74 </para>
77 75
78 <para> 76 <para>
79 For information on how to use Toaster, see the 77
80 "<link linkend='using-the-toaster-interface'>Using the Toaster Interface</link>"
81 section.
82 </para> 78 </para>
83 </section> 79 </section>
84 80
@@ -86,68 +82,45 @@
86 <title>Setting Up a Hosted Service and Running in Analysis Mode</title> 82 <title>Setting Up a Hosted Service and Running in Analysis Mode</title>
87 83
88 <para> 84 <para>
89 A hosted service resides on a server and allows 85 A hosted service resides on a shared server and allows
90 multiple users to take advantage of Toaster. 86 multiple users to take advantage of Toaster.
91 In a production environment, you might want to have multiple
92 local instances of Toaster, which run on various remote
93 build machines, and have those local instances access and use
94 a single hosted Toaster service.
95 </para> 87 </para>
96 88
97 <para> 89 <para>
98 Starting Toaster with the <filename>toaster</filename> command 90 In a production environment, you might want to have multiple
99 (i.e. the script), causes three things to start: 91 local instances of the Toaster Logging Interface running on
92 various remote build machines, and have those local instances
93 access and use a single web server.
94 To do this, you need to do the following:
100 <itemizedlist> 95 <itemizedlist>
101 <listitem><para> 96 <listitem><para>
102 The BitBake server. 97 Maintain a common SQL database.
103 </para></listitem>
104 <listitem><para>
105 The Toaster User Interface, which connects to the
106 BitBake server on one side and to the SQL
107 database on the other side.
108 </para></listitem> 98 </para></listitem>
109 <listitem><para> 99 <listitem><para>
110 The web server, which reads the database and displays 100 Set up separate instances of BitBake servers
111 the web user interface. 101 and Toaster Logging Interfaces for each of those
102 separate BitBake servers.
112 </para></listitem> 103 </para></listitem>
113 </itemizedlist> 104 </itemizedlist>
114 Rather than starting Toaster with the script, you can set up
115 and start multiple instances of Toaster by manually starting
116 as many or few of these three components across your
117 environment.
118 This is possible because it is not required that Toaster starts
119 all three of its separate components in order to run.
120 Minimally, a local instance of Toaster requires just one of the
121 components.
122 </para> 105 </para>
123 106
124 <para> 107 <para>
125 The concepts for setting up multiple local instances of 108 The common SQL database allows the Web server to show data from
126 Toaster that share a single hosted service revolve
127 around maintaining a common SQL database and Web server that
128 shows data from that common database as well as setting up
129 separate local instances of BitBake servers and Toaster user
130 interfaces for each of those separate BitBake build
131 directories.
132 </para>
133
134 <para>
135 The common SQL database and the Web server show data from
136 all the various BitBake builds. 109 all the various BitBake builds.
137 Setting the SQL database outside of any 110 Setting the SQL database outside of any
138 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink> 111 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
139 maintains a separation layer between the various local builds 112 maintains a separation between the various builds.
140 and the common database. 113 The BitBake servers, the SQL server, and the Web server or
141 The database is persistent because the logging database is set 114 servers can be run on separate machines.
142 up external to the BitBake database server (e.g. MySQL).
143 It is not even necessary to run the BitBake servers, the SQL
144 server, and the Web server on the same machine.
145 Each component can be run on its own machine.
146 </para> 115 </para>
147 116
148 <para> 117 <para>
149 Follow these steps to set up and run a hosted service and run 118 Follow these steps to set up and run a hosted service and run
150 Toaster in Analysis Mode: 119 Toaster in Analysis Mode:
120 <note>
121 The steps assume a Toaster installation path of
122 <filename>/opt/bitbake/</filename>.
123 </note>
151 <orderedlist> 124 <orderedlist>
152 <listitem><para><emphasis>Prepare your Build System:</emphasis> 125 <listitem><para><emphasis>Prepare your Build System:</emphasis>
153 Be sure your system has the Toaster requirements 126 Be sure your system has the Toaster requirements
@@ -162,71 +135,153 @@
162 "<ulink url='&YOCTO_DOCS_QS_URL;#yp-resources'>What You Need and How You Get It</ulink>" 135 "<ulink url='&YOCTO_DOCS_QS_URL;#yp-resources'>What You Need and How You Get It</ulink>"
163 section in the Yocto Project Quick Start for information. 136 section in the Yocto Project Quick Start for information.
164 </para></listitem> 137 </para></listitem>
165 <listitem><para><emphasis>Be Sure Ports are Free:</emphasis> 138 <listitem><para><emphasis>Install and Set up the Database Server:</emphasis>
166 Make sure that port 8000 and 8200 are free. 139 You can use any SQL server out of the box.
167 In other words, make sure the ports do not have servers 140 It is recommended that you use
168 on them. 141 <filename>mysql-server</filename> because it has
169 </para></listitem> 142 the advantages of advanced SQL features along with a
170 <listitem><para><emphasis>Set up the SQL Logging Server and the Web Server:</emphasis> 143 fast and reliable database.
171 You can use any SQL server out of the box (e.g. 144 However, setting up <filename>mysql-server</filename>
172 <filename>mysgl-server</filename> for an Ubuntu build 145 is more complex and might require a Database
173 system). 146 Administrator to tune it.</para>
174 <note> 147 <para>Another supported database backend is
175 If you are concerned about performance, you might 148 <filename>sqlite3</filename>.
176 want to hand-tune the server. 149 With <filename>sqlite3</filename>, you have the
177 </note> 150 advantage of no configuration and an easy installation.
178 You must set up proper username and password access on 151 However, Toaster still requires direct access to the
179 the shared server for everyone that will be using 152 backend.
180 Toaster. 153 The <filename>sqlite</filename> backend is also slower
181 You need administration rights for the 154 as compared to <filename>mysql-server</filename>, and
182 <filename>mysql</filename> root account, which is not 155 has no transactional support.</para>
183 the same thing as root access on the machine.</para> 156 <para>You should set up proper username and password
184 <para>Clone a separate, local Git repository of the 157 access on the shared database for everyone that will
185 Toaster master branch to use for running the Web 158 be using Toaster.
186 server. 159 You need administrator rights for the root account,
187 The Git repository for Toaster is part of the 160 which is not the same thing as root access on the
188 Yocto Project 161 machine.
189 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>. 162 Here is an example that installs
190 Consequently, you just need to set up a separate 163 <filename>mysql-server</filename> and sets up
191 local clone of the Yocto Project Source Directory 164 some user accounts and the database.
192 (e.g. <filename>poky</filename>): 165 <literallayout class='monospaced'>
166 $ apt-get install mysql-server
167 $ mysql -u root
168 mysql> CREATE USER 'newuser'@'localhost' IDENTIFIED BY 'password';
169 mysql> GRANT ALL PRIVILEGES ON * . * TO 'newuser'@'localhost';
170 mysql> GRANT ALL PRIVILEGES ON * . * TO 'newuser'@'localhost';
171 mysql> CREATE DATABASE 'toaster';
172 </literallayout>
173 You need a separate clone of the
174 <ulink url='&YOCTO_DOCS_DEV_URL;#source-repositories'>Source Repositories</ulink>
175 for the Database Server.
176 This clone is only used for getting the latest Toaster
177 files.
178 You can set this up using the following Git command.
179 Be sure to set up the directory outside of any
180 Build Directories.
193 <literallayout class='monospaced'> 181 <literallayout class='monospaced'>
194 $ git clone git://git.yoctoproject.org/poky 182 $ git clone git://git.yoctoproject.org/poky
195 </literallayout> 183 </literallayout>
196 You do not perform builds on this tree. 184 In the separately cloned tree for the Database Server,
197 You need to create this local repository away from any
198 build areas.</para>
199 <para>In the separately cloned tree for the Web server,
200 edit the 185 edit the
201 <filename>bitbake/lib/toaster/toastermain/settings.py</filename> 186 <filename>bitbake/lib/toaster/toastermain/settings.py</filename>
202 file so that the <filename>DATABASES</filename> value 187 file so that the <filename>DATABASES</filename> value
203 points to the previously created database server. 188 points to the previously created database server.
204 Use the username and password established 189 Use the username and password established
205 earlier.</para> 190 earlier.
206 <para>Run the database sync scripts to create the 191 Here is an example:
207 needed tables as follows: 192 <literallayout class='monospaced'>
193 $ cat /opt/bitbake/lib/toaster/toastermain/settings.py
194 ...
195 DATABASES = {
196 'default': {
197 'ENGINE': 'django.db.backends.mysql',
198 'NAME': 'toaster',
199 'USER': 'newuser',
200 'PASSWORD': 'password',
201 'HOST': '192.168.0.25',
202 'PORT': '3306',
203 }
204 ...
205 </literallayout>
206 </para></listitem>
207 <listitem><para><emphasis>Install and Set Up the Web Server:</emphasis>
208 For a production environment, it is recommended that
209 you install and set up a front-end web server.
210 This server allows for load balancing and
211 multi-threading over Toaster and
212 <filename>django</filename> WSGI.
213 Here is an example that uses Apache web server.
214 <literallayout class='monospaced'>
215 $ apt-get install apache2 libapache2-mod-wsgi
216 $ a2enmod wsgi
217 $ cat /etc/apache2/sites-available/000-default.conf
218
219 ...
220
221 # the WSGIPythonPath is global
222 WSGIPythonPath /opt/bitbake/lib/toaster/
223
224 ...
225
226 #snip - in VirtualHost
227 WSGIScriptAlias / /opt/bitbake/lib/toaster/toastermain/wsgi.py
228
229 &lt;Directory //opt/bitbake/lib/toaster/toastermain/&gt;
230 &lt;Files wsgi.py&gt;
231 Require all granted
232 &lt;/Files&gt;
233 &lt;/Directory&gt;
234
235 ...
236 </literallayout>
237 You need to collect static media from Toaster and
238 continue configuring Apache to serve that static
239 media:
208 <literallayout class='monospaced'> 240 <literallayout class='monospaced'>
209 $ python bitbake/lib/toaster/manage.py syncdb 241 $ mkdir /var/www.html/static &amp;&amp; cd /var/www.html/static
210 $ python bitbake/lib/toaster/manage.py migrate orm 242 $ /opt/bitbake/lib/toaster/manage.py collectstatic
243 $ cat /etc/apache2/sites-available/000-default.conf
244
245 ...
246
247 # in VirtualHost, AHEAD of the WSGIScriptAlias definition
248 Alias /static/ /var/www.html/static/
249
250 &lt;Directory /var/www.html/static/&gt;
251 Require all granted
252 &lt;/Directory&gt;
253
254 ...
255
256 WSGIScript Alias / /opt/bitbake/lib/toaster/toastermain/wsgi.py
257
258 ...
211 </literallayout> 259 </literallayout>
212 You can start the Web server in the foreground or the 260 </para></listitem>
213 background using these commands, respectively: 261 <listitem><para><emphasis>Start Toaster:</emphasis>
262 Synchronize the databases for toaster, and then start
263 up the web server.
264 Here is an example that continues with the assumed
265 components from the previous steps:
214 <literallayout class='monospaced'> 266 <literallayout class='monospaced'>
215 $ python bitbake/lib/toaster/manage.py runserver 267 $ /opt/bitbake/lib/toaster/manage.py syncdb
216 $ nohup python bitbake/lib/toaster/manage.py runserver 2>toaster_web.log >toaster_web.log &amp; 268 $ /opt/bitbake/lib/toaster/manage.py migrate orm
269 $ /opt/bitbake/lib/toaster/manage.py migrate bldcontrol
270
271 $ service apache2 restart
217 </literallayout> 272 </literallayout>
273 You can find general documentation on
274 <filename>manage.py</filename> at the
275 <ulink url='https://docs.djangoproject.com/en/1.7/ref/django-admin/'>Django</ulink>
276 site.
277 For reference information on Toaster-specific
278 <filename>manage.py</filename> commands,
279 see the
280 "<link linkend='toaster-useful-commands'>Useful Commands</link>"
281 section.
218 </para></listitem> 282 </para></listitem>
219 <listitem><para><emphasis>Enable Build Logging to the Common SQL Server for Each Build Directory you are Using:</emphasis> 283 <listitem><para><emphasis>Enable Build Logging to the Common SQL Server for Each Build Directory you are Using:</emphasis>
220 For each build system that will be using Toaster and 284 In the Build Directory, create the required
221 the shared SQL server, you need to edit the
222 <filename>bitbake/lib/toaster/toastermain/settings.py</filename>
223 file to alter the <filename>DATABASES</filename> value
224 so that it points to the common SQL logging server.
225 <note><title>REVIEWER NOTE</title>
226 I don't see how to do this from the Wiki.
227 I need more clarification.
228 </note></para>
229 <para>In the Build Directory, create the required
230 <filename>conf/toaster.conf</filename> file as 285 <filename>conf/toaster.conf</filename> file as
231 described in 286 described in
232 <ulink url='https://wiki.yoctoproject.org/wiki/Setting_up_a_local_instance_of_Toaster'>BitBake Extra Options</ulink>. 287 <ulink url='https://wiki.yoctoproject.org/wiki/Setting_up_a_local_instance_of_Toaster'>BitBake Extra Options</ulink>.
@@ -240,24 +295,16 @@
240 INHERIT += "buildhistory" 295 INHERIT += "buildhistory"
241 BUILDHISTORY_COMMIT = "1" 296 BUILDHISTORY_COMMIT = "1"
242 </literallayout> 297 </literallayout>
243 Start the BitBake server using the following command: 298 You also need to point to the database.
299 You can do this by exporting the
300 <filename>DATABASE_URL</filename> variable as follows:
244 <literallayout class='monospaced'> 301 <literallayout class='monospaced'>
245 $ bitbake &dash;&dash;postread conf/toaster.conf &dash;&dash;server-only -t xmlrpc -B localhost:0 &amp;&amp; export BBSERVER=localhost:-1 302 export DATABASE_URL=mysql://<replaceable>newuser</replaceable>:<replaceable>password</replaceable>@192.168.0.25:3306/toaster
246 </literallayout> 303 </literallayout>
247 Start the logging user interface using the following
248 command:
249 <literallayout class='monospaced'>
250 $ nohup bitbake &dash;&dash;observe-only -u toasterui >toaster_ui.log &amp;
251 </literallayout>
252 <note>
253 No hard-coded ports are used as there is enough code
254 to run <filename>autodiscovery</filename>
255 for ports to prevent collisions.
256 </note>
257 </para></listitem> 304 </para></listitem>
258 <listitem><para><emphasis>Source your Build Environment Setup Script:</emphasis> 305 <listitem><para><emphasis>Source your Build Environment Setup Script:</emphasis>
259 From your 306 From your
260 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink> 307 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>
261 on each of the build systems, 308 on each of the build systems,
262 (e.g. <filename>poky/build</filename>), source the 309 (e.g. <filename>poky/build</filename>), source the
263 build environment setup script (i.e. 310 build environment setup script (i.e.
@@ -265,6 +312,26 @@
265 or 312 or
266 <ulink url="&YOCTO_DOCS_REF_URL;#structure-memres-core-script"><filename>oe-init-build-env-memres</filename></ulink>). 313 <ulink url="&YOCTO_DOCS_REF_URL;#structure-memres-core-script"><filename>oe-init-build-env-memres</filename></ulink>).
267 </para></listitem> 314 </para></listitem>
315 <listitem><para><emphasis>Start the BitBake Server:</emphasis>
316 Start the BitBake server using the following command:
317 <literallayout class='monospaced'>
318 $ bitbake --postread conf/toaster.conf --server-only -t xmlrpc -B localhost:0 &amp;&amp; export BBSERVER=localhost:-1
319 </literallayout>
320 </para></listitem>
321 <listitem><para><emphasis>Start the Logging Server:</emphasis>
322 Start the Toaster Logging Interface using the following
323 command:
324 <literallayout class='monospaced'>
325 $ nohup bitbake --observe-only -u toasterui >toaster_ui.log &amp;
326 </literallayout>
327 <note>
328 No hard-coded ports are used in the BitBake options
329 as there is enough code to run
330 <filename>autodiscovery</filename> for BitBake
331 ports.
332 Doing so prevents collisions.
333 </note>
334 </para></listitem>
268 <listitem><para><emphasis>Start Builds Using BitBake:</emphasis> 335 <listitem><para><emphasis>Start Builds Using BitBake:</emphasis>
269 Use the <filename>bitbake</filename> command to start a 336 Use the <filename>bitbake</filename> command to start a
270 build on a build system. 337 build on a build system.
@@ -284,8 +351,9 @@
284 </para> 351 </para>
285 352
286 <para> 353 <para>
287 For information on how to use Toaster, see the 354 For information on how to use the Toaster web interface,
288 "<link linkend='using-the-toaster-interface'>Using the Toaster Interface</link>" 355 see the
356 "<link linkend='using-the-toaster-web-interface'>Using the Toaster Web Interface</link>"
289 section. 357 section.
290 </para> 358 </para>
291 </section> 359 </section>
@@ -303,65 +371,607 @@
303 <section id='setting-up-locally-and-running-in-build-mode'> 371 <section id='setting-up-locally-and-running-in-build-mode'>
304 <title>Setting Up Locally and Running in Build Mode</title> 372 <title>Setting Up Locally and Running in Build Mode</title>
305 373
306 <note><title>REVIEWER NOTE</title> 374 <para>
307 I need the information on how to do this. 375 Follow these steps to set up a local instance of Toaster and
308 </note> 376 then run in Build Mode:
377 <orderedlist>
378 <listitem><para><emphasis>Prepare your Build System:</emphasis>
379 Be sure your system has the Toaster requirements
380 by following the steps in the
381 "<link linkend='toaster-establishing-toaster-system-dependencies'>Establishing Toaster System Dependencies</link>"
382 section.
383 </para></listitem>
384 <listitem><para><emphasis>Get Set Up to Use the Yocto Project:</emphasis>
385 Get the requirements set up so that you can use the
386 Yocto Project to build images.
387 See the
388 "<ulink url='&YOCTO_DOCS_QS_URL;#yp-resources'>What You Need and How You Get It</ulink>"
389 section in the Yocto Project Quick Start for information.
390 </para></listitem>
391 <listitem><para><emphasis>Start Toaster:</emphasis>
392 From the root of the source directory (e.g
393 <filename>poky/</filename>), run the following command:
394 <literallayout class='monospaced'>
395 $ bitbake/bin/toaster
396 </literallayout>
397 </para></listitem>
398 <listitem><para><emphasis>Create a Superuser:</emphasis>
399 Django will ask you if you want to create a superuser.
400 You can skip this step, but it is recommended that you
401 create a superuser.
402 You can use the superuser to access the Django
403 administration interface and make changes to the
404 Toaster configuration.
405 </para></listitem>
406 <listitem><para><emphasis>Select the Build Log Directory:</emphasis>
407 Toaster asks you to specify the directory where you
408 want to store the build log files.
409 Choosing a directory for these files makes sure they
410 are always available to you.
411 If you do not choose a directory, the logs can
412 disappear (e.g. deleting the Build Directory).</para>
413 <para>When Toaster prompts you for the Build Log
414 directory, you can select the suggested default
415 or provide a path to a different directory.
416 </para></listitem>
417 <listitem><para><emphasis>Specify the Layer Checkout Directory:</emphasis>
418 Toaster asks you to specify the directory into which
419 layers are checked out.
420 Toaster clones any layers needed for your builds
421 inside this directory.</para>
422 <para>When Toaster prompts you for the Layer
423 checkout directory, you can select the suggested
424 default or provide a path to a different directory.
425 </para></listitem>
426 <listitem><para><emphasis>Specify the Build Directory Path:</emphasis>
427 Toaster asks you to specify the path to the
428 Build Directory.
429 You can select the suggested default or provide a
430 path to a different directory.
431 </para></listitem>
432 <listitem><para><emphasis>Choose Whether or not to Import a Default Toaster Configuration File:</emphasis>
433 Toaster asks you if you want to import a default
434 Toaster configuration file.
435 Toaster configurations are stored in
436 JSON files called
437 <filename>toasterconf.json</filename> and supports
438 several types.
439 For information on JSON files, see the
440 "<link linkend='toaster-json-files'>JSON Files</link>"
441 section.</para>
442 <para>You can skip importing a configuration file
443 by entering "0" at the prompt.
444 However, it is recommended that you import one of the
445 configuration files listed during this step.
446 You can always amend the imported configuration during
447 a later stage through the Django administration
448 interface.</para>
449 <para>For general information on Django, see the
450 available
451 <ulink url='https://docs.djangoproject.com/en/1.7/'>documentation</ulink>.
452 You can also find information on Toaster-specific
453 <filename>manage.py</filename> commands in the
454 "<link linkend='toaster-useful-commands'>Useful Commands</link>"
455 section.
456 </para></listitem>
457 <listitem><para><emphasis>Open the Browser:</emphasis>
458 If no browser window appears, open your favorite
459 browser and enter the following:
460 <literallayout class='monospaced'>
461 http://localhost:8000/toastergui
462 </literallayout>
463 You can now use the Toaster web interface.
464 </para></listitem>
465 </orderedlist>
466 </para>
309 </section> 467 </section>
310 468
311 <section id='setting-up-a-hosted-service-and-running-in-build-mode'> 469 <section id='setting-up-a-hosted-service-and-running-in-build-mode'>
312 <title>Setting Up a Hosted Service and Running in Build Mode</title> 470 <title>Setting Up a Hosted Service and Running in Build Mode</title>
313 471
314 <note><title>REVIEWER NOTE</title> 472 <para>
315 Right now, the 473 Follow these steps to set up a hosted service and run Toaster
316 <ulink url='https://wiki.yoctoproject.org/wiki/Setting_up_a_hosted_managed_mode_for_Toaster'>WIKI PAGE</ulink> 474 in Build Mode:
317 has some information on this but I don't understand it. 475 <orderedlist>
318 I need more information. 476 <listitem><para><emphasis>Prepare your Build System:</emphasis>
319 </note> 477 Be sure your system has the Toaster requirements
478 by following the steps in the
479 "<link linkend='toaster-establishing-toaster-system-dependencies'>Establishing Toaster System Dependencies</link>"
480 section.
481 </para></listitem>
482 <listitem><para><emphasis>Get Set Up to Use the Yocto Project:</emphasis>
483 Get the requirements set up so that you can use the
484 Yocto Project to build images.
485 See the
486 "<ulink url='&YOCTO_DOCS_QS_URL;#yp-resources'>What You Need and How You Get It</ulink>"
487 section in the Yocto Project Quick Start for information.
488 </para></listitem>
489 <listitem><para><emphasis>Be Sure Management is Enabled:</emphasis>
490 If you are running Toaster under Apache, you need to
491 be sure management is enabled.
492 To enable management, set
493 <filename>MANAGED</filename> to "True" by adding
494 the following to the
495 <filename>bitbake/lib/toaster/settings.py</filename>
496 file:
497 <literallayout class='monospaced'>
498 MANAGED="True"
499 </literallayout>
500 </para></listitem>
501 <listitem><para><emphasis>Configure the Build Environment:</emphasis>
502 Configure the build environment by running the
503 following:
504 <literallayout class='monospaced'>
505 bitbake/lib/toaster/manage.py checksettings
506 </literallayout>
507 For reference information on Toaster-specific
508 <filename>manage.py</filename> commands, see the
509 "<link linkend='toaster-useful-commands'>Useful Commands</link>"
510 section.
511 </para></listitem>
512 <listitem><para><emphasis>Load a Configuration File:</emphasis>
513 Load a configuration file by running the following:
514 <literallayout class='monospaced'>
515 bitbake/lib/toaster/manage.py loadconf <replaceable>path-to-toasterconf.json-file</replaceable>
516 </literallayout>
517 For reference information on Toaster-specific
518 <filename>manage.py</filename> commands, see the
519 "<link linkend='toaster-useful-commands'>Useful Commands</link>"
520 section.
521 </para></listitem>
522 <listitem><para><emphasis>Set Up Toaster for Normal Usage:</emphasis>
523 You need to configure each build environment, layer
524 sources, and BitBake versions.</para>
525 <para>Verify that your releases have been loaded correctly by
526 using the Toaster web interface to create a new
527 project.
528 Check the "Releases" dropdown menu to be sure your
529 newly specified releases exist.</para>
530 <para>If you want to use the administration interface
531 for this step, here is a set of example commands
532 with some descriptions as an example:
533 <literallayout class='monospaced'>
534 # Create the user under which the builds will run
535 $ adduser poky
536
537 # Bring up the administration interface
538 $xdg-open http://<replaceable>server-address</replaceable>/admin/
539
540 # Login with the admin user previously created
541
542 # Go to the BuildEnvironment object in Build Environments and
543 # set address to local host, sourcedir to /home/poky, and
544 # builddir to /home/pokybuild.
545 #
546 # Save your changes and exit
547
548 # Go to Home, Layer Sources and select add Layer Source
549 # Name: OpenEmbedded, Sourcetype: layerindex,
550 # Apiurl: http://layers openembedded.org/layerindex/api/
551 # Save your changes and exit
552
553 # Go to Home, Bitbake Versions, Add bitbake version;
554 # Take version information from: http://git.openembedded.org/bitbake/refs/heads,
555 # This example assumes "master" version.
556 # set Name: master, Giturl git://git.openembedded.org/bitbake
557 # branch master, dirpath /
558 # Save your changes and exit
559 </literallayout>
560 You also need to configure the project releases, the
561 default variables, and update information from the
562 layer index.
563 Continuing with the example:
564 <literallayout class='monospaced'>
565 # Go to Home, Releases, Add release
566 # set Name: master, Description: Current master release, select Bitbake Version,
567 # and Branch: master
568 # Save your changes and exit
569
570 # Go to Home, Toaster Settings, select the Setting for DEFAULT_RELEASE
571 # set Helptext: This selects the default release., Value: master
572 # Save your changes and exit
573
574 # Go to Home, Bitbake Versions, Add bitbake version;
575 # take version infor from : http://git.openembedded.org/bitbake/refs/heads,
576 # this manual assumes the master version
577 # set Name: master, Giturl git://git.openembedded.org/bitbake
578 # branch master, dirpath /
579 # Save your changes and exit
580
581 # Update the information
582 # bitbake/lib/toaster/manage.py lsupdates
583 </literallayout>
584 For reference information on Toaster-specific
585 <filename>manage.py</filename> commands, see the
586 "<link linkend='toaster-useful-commands'>Useful Commands</link>"
587 section.
588 </para></listitem>
589 <listitem><para><emphasis>Install and Set up the Database Server:</emphasis>
590 You can use any SQL server out of the box.
591 It is recommended that you use
592 <filename>mysql-server</filename> because it has
593 the advantages of advanced SQL features along with a
594 fast and reliable database.
595 However, setting up <filename>mysql-server</filename>
596 is more complex and might require a Database
597 Administrator to tune it.</para>
598 <para>Another supported database backend is
599 <filename>sqlite3</filename>.
600 With <filename>sqlite3</filename>, you have the
601 advantage of no configuration and an easy installation.
602 However, Toaster still requires direct access to the
603 backend.
604 The <filename>sqlite</filename> backend is also slower
605 as compared to <filename>mysql-server</filename>, and
606 has no transactional support.</para>
607 <para>You should set up proper username and password
608 access on the shared database for everyone that will
609 be using Toaster.
610 You need administrator rights for the root account,
611 which is not the same thing as root access on the
612 machine.
613 Here is an example that installs
614 <filename>mysql-server</filename> and sets up
615 some user accounts and the database.
616 <literallayout class='monospaced'>
617 $ apt-get install mysql-server
618 $ mysql -u root
619 mysql> CREATE USER 'newuser'@'localhost' IDENTIFIED BY 'password';
620 mysql> GRANT ALL PRIVILEGES ON * . * TO 'newuser'@'localhost';
621 mysql> GRANT ALL PRIVILEGES ON * . * TO 'newuser'@'localhost';
622 mysql> CREATE DATABASE 'toaster';
623 </literallayout>
624 You need a separate clone of the
625 <ulink url='&YOCTO_DOCS_DEV_URL;#source-repositories'>Source Repositories</ulink>
626 for the Database Server.
627 This clone is only used for getting the latest Toaster
628 files.
629 You can set this up using the following Git command.
630 Be sure to set up the directory outside of any
631 Build Directories.
632 <literallayout class='monospaced'>
633 $ git clone git://git.yoctoproject.org/poky
634 </literallayout>
635 In the separately cloned tree for the Database Server,
636 edit the
637 <filename>bitbake/lib/toaster/toastermain/settings.py</filename>
638 file so that the <filename>DATABASES</filename> value
639 points to the previously created database server.
640 Use the username and password established
641 earlier.
642 Here is an example:
643 <literallayout class='monospaced'>
644 $ cat /opt/bitbake/lib/toaster/toastermain/settings.py
645 ...
646 DATABASES = {
647 'default': {
648 'ENGINE': 'django.db.backends.mysql',
649 'NAME': 'toaster',
650 'USER': 'newuser',
651 'PASSWORD': 'password',
652 'HOST': '192.168.0.25',
653 'PORT': '3306',
654 }
655 ...
656 </literallayout>
657 </para></listitem>
658 <listitem><para><emphasis>Create the Database</emphasis>
659 Use the following commands to create the default
660 database structure:
661 <literallayout class='monospaced'>
662 $ bitbake/lib/toaster/manage.py syncdb
663 $ bitbake/lib/toaster/manage.py migrate orm
664 $ bitbake/lib/toaster/manage.py migrate bldcontrol
665 </literallayout>
666 The interface asks you if you want to create a
667 superuser.
668 Do not skip this step.
669 You will use the superuser account to access the
670 administration interface and make changes to the
671 Toaster configuration.
672 </para></listitem>
673 <listitem><para><emphasis>Select Where the Build Process Takes Place:</emphasis>
674 You need to create three directories for storing
675 build artifacts, downloading sources, and running
676 builds.
677 All three directories need to be writable by
678 the "poky" user.
679 The build artifacts directory needs to readable by the
680 apache user.
681 You also need free disk space in the range of
682 100 Gbytes.
683 Following are three suggested directories:
684 <literallayout class='monospaced'>
685 /home/poky/buildartifacts/
686 /home/poky/build/
687 /home/poky/sources/
688 </literallayout>
689 </para></listitem>
690 <listitem><para><emphasis>Set Up the <filename>toasterconf.json</filename> File:</emphasis>
691 Download the <filename>toasterconf.json</filename> file
692 from the
693 <ulink url='https://wiki.yoctoproject.org/wiki/File:Toasterconf.json.txt.patch'>File:Toasterconf.json.txt.patch</ulink>
694 wiki page and edit it to suit your environment.
695 For information on the relevant sections of the file,
696 see the
697 "<link linkend='toaster-json-files'>JSON Files</link>"
698 section.
699 </para></listitem>
700 <listitem><para><emphasis>Check the Toaster Settings:</emphasis>
701 You can check the Toaster settings by running this
702 command:
703 <literallayout class='monospaced'>
704 $ bitbake/lib/toaster/manage.py checksettings
705 </literallayout>
706 When prompted, paste in the directory paths created
707 previously during Step 9.
708 Alternatively, you can select the edited
709 <filename>toasterconf.json</filename> file set up in
710 Step 5.
711 </para></listitem>
712 <listitem><para><emphasis>Install and Set Up the Web Server:</emphasis>
713 For a production environment, it is recommended that
714 you install and set up a front-end web server.
715 This server allows for load balancing and
716 multi-threading over Toaster and
717 <filename>django</filename> WSGI.
718 Here is an example that uses Apache web server:
719 <literallayout class='monospaced'>
720 $ apt-get install apache2 libapache2-mod-wsgi
721 $ a2enmod wsgi
722 $ cat /etc/apache2/sites-available/000-default.conf
723
724 ...
725
726 # the WSGIPythonPath is global
727 WSGIPythonPath /opt/bitbake/lib/toaster/
728
729 ...
730
731 #snip - in VirtualHost
732 WSGIScriptAlias / /opt/bitbake/lib/toaster/toastermain/wsgi.py
733
734 &lt;Directory //opt/bitbake/lib/toaster/toastermain/&gt;
735 &lt;Files wsgi.py&gt;
736 Require all granted
737 &lt;/Files&gt;
738 &lt;/Directory&gt;
739
740 ...
741 </literallayout>
742 You need to collect static media from Toaster and
743 continue configuring Apache to serve that static
744 media:
745 <literallayout class='monospaced'>
746 $ mkdir /var/www.html/static &amp;&amp; cd /var/www.html/static
747 $ /opt bitbake/lib/toaster/manage.py collectstatic
748 $ cat /etc/apache2/sites-available/000-default.conf
749
750 ...
751
752 # in VirtualHost, AHEAD of the WSGIScriptAlias definition
753 Alias /static/ /var/www.html/static/
754
755 &lt;Directory /var/www.html/static/&gt;
756 Require all granted
757 &lt;/Directory&gt;
758
759 ...
760
761 WSGIScript Alias / /opt/bitbake/lib/toaster/toastermain/wsgi.py
762
763 ...
764 </literallayout>
765 </para></listitem>
766 <listitem><para><emphasis>Start Toaster:</emphasis>
767 Synchronize the databases for toaster, and then start
768 up the web server.
769 Here is an example that continues with the assumed
770 components from the previous steps:
771 <literallayout class='monospaced'>
772 $ /opt/bitbake/lib/toaster/manage.py syncdb
773 $ /opt/bitbake/lib/toaster/manage.py migrate orm
774 $ /opt/bitbake/lib/toaster/manage.py migrate bldcontrol
775
776 $ service apache2 restart
777 </literallayout>
778 For reference information on the
779 <filename>manage.py</filename> commands used here,
780 see the
781 "<link linkend='toaster-useful-commands'>Useful Commands</link>"
782 section.
783 </para></listitem>
784 <listitem><para><emphasis>Set up Build Control and Open the Web Interface:</emphasis>
785 You need to run the build control manager.
786 You can do this as shown in the following example:
787 <literallayout class='monospaced'>
788 # as the "poky" user, start the runbuilds command in a loop (or put it in crontab!)
789 $ sudo -i -u poky
790 $ while true; do /opt/bitbake/lib/toaster/manage.py runbuilds; sleep 10; done
791
792 # open up the web interface
793 $ xdg-open http://[server-address]/toastergui/
794 </literallayout>
795 It is suggested that you enable build control by
796 setting <filename>runbuilds</filename> in the
797 <filename>crontab</filename> as follows:
798 <literallayout class='monospaced'>
799 $ crontab -l
800 * * * * * /opt/bitbake/lit/toaster/manage.py runbuilds
801 </literallayout>
802 </para></listitem>
803 <listitem><para><emphasis>Open the Browser:</emphasis>
804 Once the Apache server is running, connect to it with
805 your favorite browser and verify that the Toaster
806 interface comes up.
807 You can track accesses and errors in the Apache
808 service logs:
809 <literallayout class='monospaced'>
810 http://localhost:8000/toastergui
811 </literallayout>
812 You can now use the Toaster web interface.
813 </para></listitem>
814 </orderedlist>
815 </para>
320 </section> 816 </section>
321 </section> 817 </section>
322 818
323 <section id='using-the-toaster-interface'> 819 <section id='using-the-toaster-web-interface'>
324 <title>Using the Toaster Interface</title> 820 <title>Using the Toaster Web Interface</title>
325 821
326 <para> 822 <para>
327 The Toaster interface allows you to examine the following: 823 The Toaster web interface allows you to do the following:
328 <itemizedlist> 824 <itemizedlist>
329 <listitem><para> 825 <listitem><para>
330 Outcome of the build, errors and warnings thrown 826 Browse all OpenEmbedded layers available for your
827 selected version of the build system
828 </para></listitem>
829 <listitem><para>
830 Import your own layers for building.
331 </para></listitem> 831 </para></listitem>
332 <listitem><para> 832 <listitem><para>
333 Packages included in an image 833 Add and remove layers from your configuration.
334 </para></listitem> 834 </para></listitem>
335 <listitem><para> 835 <listitem><para>
336 Image directory structure 836 Set configuration variables.
337 </para></listitem> 837 </para></listitem>
338 <listitem><para> 838 <listitem><para>
339 Build configuration 839 Select a target or multiple targets to build.
340 </para></listitem> 840 </para></listitem>
341 <listitem><para> 841 <listitem><para>
342 Recipes and packages built 842 Start your builds.
343 </para></listitem> 843 </para></listitem>
344 <listitem><para> 844 <listitem><para>
345 Full dependency chain for tasks, recipes and packages 845 See what was built (recipes and packages) and what
846 packages were installed into your final image.
346 </para></listitem> 847 </para></listitem>
347 <listitem><para> 848 <listitem><para>
348 Tasks run by the build system 849 Browse the directory structure of your image.
349 </para></listitem> 850 </para></listitem>
350 <listitem><para> 851 <listitem><para>
351 Performance information such as time, CPU usage, and 852 See the value of all variables in your build configuration,
352 disk I/O per task 853 and which files set each value.
854 </para></listitem>
855 <listitem><para>
856 Examine error, warning and trace messages to aid in
857 debugging.
858 </para></listitem>
859 <listitem><para>
860 See information about the BitBake tasks executed and
861 reused during your build, including those that used
862 shared state.
863 </para></listitem>
864 <listitem><para>
865 See dependency relationships between recipes, packages
866 and tasks.
867 </para></listitem>
868 <listitem><para>
869 See performance information such as build time, task time,
870 CPU usage, and disk I/O.
353 </para></listitem> 871 </para></listitem>
354 </itemizedlist> 872 </itemizedlist>
355 For several useful videos that show how to effectively use the 873 Following are several videos that show how to use the Toaster GUI.
356 Toaster interface, see the 874 To get a larger replay of a video after it has started playing,
357 <ulink url='https://www.yoctoproject.org/documentation/toaster-manual-17'>Toaster Documentation</ulink> 875 click in the image title area.
358 on the Yocto Project website.
359 <note><title>REVIEWER NOTE</title>
360 We have agreed to get rid of the manual page on the website,
361 contains the links to the GUI videos.
362 We have agreed to host the videos on Vimeo and to embed the
363 videos in this new Toaster manual.
364 </note>
365 </para> 876 </para>
877
878 <section id='toaster-gui-vids-1'>
879 <title>Toaster Homepage and Table Controls</title>
880
881 <para>
882 This video goes over the Toaster entry page, and provides
883 an overview of the data manipulation capabilities of Toaster,
884 which include search, sorting and filtering by different
885 criteria.
886 <mediaobject>
887 <videoobject>
888 <videodata width="640" height="480" fileref="http://www.youtube.com/v/QEARDnrR1Xw"></videodata>
889 </videoobject>
890 </mediaobject>
891 </para>
892 </section>
893
894 <section id='toaster-gui-vids-2'>
895 <title>Build Dashboard</title>
896
897 <para>
898 This video shows you the build dashboard, a page providing an
899 overview of the information available for a selected build.
900 <mediaobject>
901 <videoobject>
902 <videodata width="640px" height="480px" fileref="http://www.youtube.com/v/KKqHYcnp2gE"></videodata>
903 </videoobject>
904 </mediaobject>
905 </para>
906 </section>
907
908 <section id='toaster-gui-vids-3'>
909 <title>Image Information</title>
910
911 <para>
912 This video walks through the information Toaster provides
913 about images: packages installed and root file system.
914 <mediaobject>
915 <videoobject>
916 <videodata width="640px" height="480px" fileref="http://www.youtube.com/v/XqYGFsmA0Rw"></videodata>
917 </videoobject>
918 </mediaobject>
919 </para>
920 </section>
921
922 <section id='toaster-gui-vids-4'>
923 <title>Configuration</title>
924
925 <para>
926 This video shows the information Toaster provides about build
927 configuration.
928 <mediaobject>
929 <videoobject>
930 <videodata width="640px" height="480px" fileref="http://www.youtube.com/v/UW-j-T2TzIg"></videodata>
931 </videoobject>
932 </mediaobject>
933 </para>
934 </section>
935
936 <section id='toaster-gui-vids-5'>
937 <title>Tasks</title>
938
939 <para>
940 This video shows the information Toaster provides about the
941 tasks run by the build system.
942 <mediaobject>
943 <videoobject>
944 <videodata width="640px" height="480px" fileref="http://www.youtube.com/v/D4-9vGSxQtw"></videodata>
945 </videoobject>
946 </mediaobject>
947 </para>
948 </section>
949
950 <section id='toaster-gui-vids-6'>
951 <title>Recipes and Packages Built</title>
952
953 <para>
954 This video shows the information Toaster provides about recipes
955 and packages built.
956 <mediaobject>
957 <videoobject>
958 <videodata width="640px" height="480px" fileref="http://www.youtube.com/v/x-6dx4huNnw"></videodata>
959 </videoobject>
960 </mediaobject>
961 </para>
962 </section>
963 <section id='toaster-gui-vids-7'>
964 <title>Performance Data</title>
965
966 <para>
967 This video shows the build performance data provided by
968 Toaster.
969 <mediaobject>
970 <videoobject>
971 <videodata width="640px" height="480px" fileref="http://www.youtube.com/v/qWGMrJoqusQ"></videodata>
972 </videoobject>
973 </mediaobject>
974 </para>
975 </section>
366 </section> 976 </section>
367</chapter> 977</chapter>
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2024-05-26 03:58:51 +0000