<trclass="field-odd field"><thclass="field-name">Authors:</th><tdclass="field-body">Brian C. Lane <<aclass="reference external"href="mailto:bcl%40redhat.com">bcl<span>@</span>redhat<span>.</span>com</a>></td>
</tr>
</tbody>
</table>
<p>lorax-composer is an API server that is compatible with the Weldr project’s
bdcs-api REST protocol. More information on Weldr can be found <aclass="reference external"href="http://www.weldr.io">on the Weldr
blog</a>.</p>
<p>The server runs as root, and communication with it is via a unix domain socket
(<ttclass="docutils literal"><spanclass="pre">/run/weldr/api.socket</span></tt> by default). The directory and socket are owned by
root:weldr so that any user in the weldr group can use the API to control
lorax-composer.</p>
<p>When starting the server it will check for the correct permissions and
ownership of a pre-existing directory, or it will create a new one if it
doesn’t exist. The socket path and group owner’s name can be changed from the
cmdline by passing it the <ttclass="docutils literal"><spanclass="pre">--socket</span></tt> and <ttclass="docutils literal"><spanclass="pre">--group</span></tt> arguments.</p>
<p>As of version 19.7.7 it will drop root privileges for the API thread. The queue
and compose thread still runs as root because it needs to be able to
mount/umount files and run Anaconda.</p>
<divclass="section"id="logs">
<h2>Logs<aclass="headerlink"href="#logs"title="Permalink to this headline">¶</a></h2>
<p>Logs are stored under <ttclass="docutils literal"><spanclass="pre">/var/log/lorax-composer/</span></tt> and include all console
messages as well as extra debugging info and API requests.</p>
</div>
<divclass="section"id="quickstart">
<h2>Quickstart<aclass="headerlink"href="#quickstart"title="Permalink to this headline">¶</a></h2>
<olclass="arabic simple">
<li>Create a <ttclass="docutils literal"><spanclass="pre">weldr</span></tt> user and group by running <ttclass="docutils literal"><spanclass="pre">useradd</span><spanclass="pre">weldr</span></tt></li>
<li>Remove any pre-existing socket directory with <ttclass="docutils literal"><spanclass="pre">rm</span><spanclass="pre">-rf</span><spanclass="pre">/run/weldr/</span></tt>
A new directory with correct permissions will be created the first time the server runs.</li>
<li>Either start it via systemd with <ttclass="docutils literal"><spanclass="pre">systemctl</span><spanclass="pre">start</span><spanclass="pre">lorax-composer</span></tt> or
run it directly with <ttclass="docutils literal"><spanclass="pre">lorax-composer</span><spanclass="pre">/path/to/recipes/</span></tt></li>
</ol>
<p>The <ttclass="docutils literal"><spanclass="pre">/path/to/recipes/</span></tt> is where the recipe’s git repo will be created, and
all the recipes created with the <ttclass="docutils literal"><spanclass="pre">/api/v0/recipes/new</span></tt> route will be stored.
If there are recipe <ttclass="docutils literal"><spanclass="pre">.toml</span></tt> files in the top level of the directory they will
be imported into the recipe git storage.</p>
</div>
<divclass="section"id="composing-images">
<h2>Composing Images<aclass="headerlink"href="#composing-images"title="Permalink to this headline">¶</a></h2>
<p>As of version 19.7.7 lorax-composer can create <ttclass="docutils literal"><spanclass="pre">tar</span></tt> output images. You can use curl to start
<p>And then monitor it by passing the returned build UUID to <ttclass="docutils literal"><spanclass="pre">/compose/status/<uuid></span></tt>.</p>
<p>Version 19.7.10 adds support for <ttclass="docutils literal"><spanclass="pre">live-iso</span></tt> and <ttclass="docutils literal"><spanclass="pre">partitioned-disk</span></tt></p>
</div>
<divclass="section"id="adding-output-types">
<h2>Adding Output Types<aclass="headerlink"href="#adding-output-types"title="Permalink to this headline">¶</a></h2>
<p>livemedia-creator supports a large number of output types, and only some of
these are currently available via lorax-composer. To add a new output type to
lorax-composer a kickstart file needs to be added to <ttclass="docutils literal"><spanclass="pre">./share/composer/</span></tt>. The
name of the kickstart is what will be used by the <ttclass="docutils literal"><spanclass="pre">/compose/types</span></tt> route, and the
<ttclass="docutils literal"><spanclass="pre">compose_type</span></tt> field of the POST to start a compose. It also needs to have
code added to the <aclass="reference internal"href="pylorax.api.html#pylorax.api.compose.compose_args"title="pylorax.api.compose.compose_args"><ttclass="xref py py-func docutils literal"><spanclass="pre">pylorax.api.compose.compose_args()</span></tt></a> function. The
<ttclass="docutils literal"><spanclass="pre">_MAP</span></tt> entry in this function defines what lorax-composer will pass to
<aclass="reference internal"href="pylorax.html#pylorax.installer.novirt_install"title="pylorax.installer.novirt_install"><ttclass="xref py py-func docutils literal"><spanclass="pre">pylorax.installer.novirt_install()</span></tt></a> when it runs the compose. When the
compose is finished the output files need to be copied out of the build
<aclass="reference internal"href="pylorax.api.html#pylorax.api.compose.move_compose_results"title="pylorax.api.compose.move_compose_results"><ttclass="xref py py-func docutils literal"><spanclass="pre">pylorax.api.compose.move_compose_results()</span></tt></a> handles this for each type.
You should move them instead of copying to save space.</p>
<p>If the new output type does not have support in livemedia-creator it should be
added there first. This will make the output available to the widest number of
<h3>Example: Add partitioned disk support<aclass="headerlink"href="#example-add-partitioned-disk-support"title="Permalink to this headline">¶</a></h3>
<p>Partitioned disk support is something that livemedia-creator already supports
via the <ttclass="docutils literal"><spanclass="pre">--make-disk</span></tt> cmdline argument. To add this to lorax-composer it
needs 3 things:</p>
<ulclass="simple">
<li>A <ttclass="docutils literal"><spanclass="pre">partitioned-disk.ks</span></tt> file in <ttclass="docutils literal"><spanclass="pre">./share/composer/</span></tt></li>
<li>A new entry in the _MAP in <aclass="reference internal"href="pylorax.api.html#pylorax.api.compose.compose_args"title="pylorax.api.compose.compose_args"><ttclass="xref py py-func docutils literal"><spanclass="pre">pylorax.api.compose.compose_args()</span></tt></a></li>
<li>Add a bit of code to <aclass="reference internal"href="pylorax.api.html#pylorax.api.compose.move_compose_results"title="pylorax.api.compose.move_compose_results"><ttclass="xref py py-func docutils literal"><spanclass="pre">pylorax.api.compose.move_compose_results()</span></tt></a> to move the disk image from
the compose directory to the results directory.</li>
</ul>
<p>The <ttclass="docutils literal"><spanclass="pre">partitioned-disk.ks</span></tt> is pretty similar to the example minimal kickstart
in <ttclass="docutils literal"><spanclass="pre">./docs/rhel7-minimal.ks</span></tt>. You should remove the <ttclass="docutils literal"><spanclass="pre">url</span></tt> and <ttclass="docutils literal"><spanclass="pre">repo</span></tt>
commands, they will be added by the compose process. Make sure the bootloader
packages are included in the <ttclass="docutils literal"><spanclass="pre">%packages</span></tt> section at the end of the kickstart,
and you will want to leave off the <ttclass="docutils literal"><spanclass="pre">%end</span></tt> so that the compose can append the
list of packages from the recipe.</p>
<p>The new <ttclass="docutils literal"><spanclass="pre">_MAP</span></tt> entry should be a copy of one of the existing entries, but with <ttclass="docutils literal"><spanclass="pre">make_disk</span></tt> set
to <ttclass="docutils literal"><spanclass="pre">True</span></tt>. Make sure that none of the other <ttclass="docutils literal"><spanclass="pre">make_*</span></tt> options are <ttclass="docutils literal"><spanclass="pre">True</span></tt>. The <ttclass="docutils literal"><spanclass="pre">image_name</span></tt> is
what the name of the final image will be.</p>
<p><ttclass="docutils literal"><spanclass="pre">move_compose_results()</span></tt> can be as simple as moving the output file into
the results directory, or it could do some post-processing on it. The end of
the function should always clean up the <ttclass="docutils literal"><spanclass="pre">./compose/</span></tt> directory, removing any
unneeded extra files. This is especially true for the <ttclass="docutils literal"><spanclass="pre">live-iso</span></tt> since it produces
the contents of the iso as well as the boot.iso itself.</p>
</div>
</div>
</div>
</div>
</div>
</div>
<divclass="sphinxsidebar">
<divclass="sphinxsidebarwrapper">
<h3><ahref="index.html">Table Of Contents</a></h3>
