README.demo

This experimental demo works by running anaconda on the local system to create a live iso.

It is based on livemedia-creator with most of the unnecessary code removed from
it.  It uses the Bottle web framework and Mako templates for the UI. Templates
are in ./share/html/templates/ It places the resulting iso in
./share/html/static/ using a unique name.

HOW TO RUN THIS
===============

Install the requirements for lorax, either by installing lorax or by reading
them from the lorax.spec file.  Install anaconda-core and anaconda-tui

Run it, as root, from the working directory like so:

PYTHONPATH=./src/ ./src/sbin/lmc-web-composer --debug --ks-template=./share/composer-template.ks \
--lorax-templates=./share/

Add a --proxy if you have one, it'll speed things up when you have to rerun it.

Browse to port 80 on the system it is running on, eg. http://localhost/ Click
on the BIG RED BUTTON.  Wait a while. Eventually the iso will show up under
http://localhost/isos/

If things break there will be a traceback on the console it was run from. Logs
from the anaconda run are copied into /var/log/lmc-web-composer/ and the
application's logs are in /var/log/lmc-web-composer.log and program.log

Current state is that this is a VERY rough demo with a single API entry:

POST to /api/v0/compose will trigger running anaconda with the specified
kickstart template using the Fedora 24 repos, and adding tmux and screen to the
package list.

Some things that need to be figured out:

1. User selection of repos and 'modules' to feed to the kickstart template
2. A better UI maybe?
3. Feedback to the UI during the compose process.
4. Debug output in the UI when it fails.
5. Tell the UI when the compose finished and where to find the final iso.
6. Lock the compose so that it won't run more than one at a time.
7. Lock the dnf API while metadata is being downloaded.


API Documentation
=================

The API is available from /api/v0/ and the available methods are:

* POST /api/v0/compose
  This takes a parameter, "module", which is the name of the module to compose.
  The result will be written to /static/live-<date+time>.iso when it is finished.
  The default is to compose a live iso, this can be changed by passing the "type"
  parameter and one of the supported types returned by the /compose/types API call.
  Make sure that the previous compose has finished before calling this again. Currently
  there is nothing preventing this (TODO).

  On success this call will return a 202 to indicate the compose has started and include
  a Location header with a path to a status URL.

* GET /api/v0/compose/log/<kbytes>
  Read the end of the log, starting back <kbytes> from the end. It will
  find the start of the next line and return all the lines up to the end
  of the file.

  This will return lines from the lmc-web-compose log when anaconda is
  not running, and when anaconda is running it will return lines from
  anaconda's logs.

* GET /api/v0/compose/status
  Returns a JSON object with one of 3 possible statuses:
  "compose not started", "compose running", and "compose finished"

* GET /api/v0/composer/<id>
  Returns a JSON object with the status of a specific compose.

  compose_id contains the ID passed in for the compose.
  status contains one of "compose running", "compose finished" or "compose failed"
  if the compose finished, "image" contains a path to the result

  If the compose does not exist, returns a 404.

* POST /api/v0/compose/cancel
  Cancel the currently running compose
  This will terminate anaconda, if it is running, but will not stop
  it after that point (mksquashfs and creation of the iso). It may
  take a few seconds for the cancel to have any effect. /status will
  indicate that the compose has finished after it has been terminated.

* GET /api/v0/compose/types
  Returns a list of JSON objects with the possible compose types and their support
  status (true or false) for the composer instance. eg. 
  {"types": [{"name": "iso", "enabled": "true"}, ...] }

* GET /api/v0/isos
  Returns a list of the available composed ISO as a JSON object
  {"iso" : [iso1, iso2, ...]}. The isos themselves are accessible as /static/iso1, etc.

* GET /api/v0/module/list
  This returns a JSON object of the form {"modules": <list>} with information on all
  the modules that the composer knows about. The useful parts of the objects in the
  list are probably "name" and "summary".

* GET /api/v0/module/info/<module-list>
  This accepts a comma separated list of module names and returns a JSON object of the
  form: {"MODULE-NAME": {"packages": [list of packages]}, ...}
  eg. {"fm-httpd": {"packages": ["shared-mime-info", "pam", ...]}}

* GET /api/v0/dnf/transaction/<package list>
  This accepts a comma separated list of rpm package names and returns a JSON object
  of the form {"packages": <list>} with a list of all package tuples that would be
  included in a dnf transaction that selects the packages in <package list>. eg.
  {"packages": [["gzip", "x86_64", "0", "1.6", "10.fc24"], ...]}

* GET /api/v0/dnf/info/<package list>
  This accepts a comma separated list of rpm package names and returns a JSON object
  with information about the listed packages using the form: {"package-name": {"files": ...}}
  eg. {"pam": {"url": "http://www.linux-pam.org/", "size": 742158, ...}}

* GET /api/v0/recipe/list
  This returns a JSON object of the form {"recipes": ["apache+mysql", "cabal"]} which
  is a list of the available recipes.

* GET /api/v0/recipe/<names>
  Return a JSON object with the content of the recipe(s). names can be a single
  recipe name or a comma separated list.
  {"apache+mysql": {"name": "apache+mysql", description: "Apache and MySQL", modules: ["apache", "mysql"]} }

* POST /api/v0/recipe/<name>
  This takes a parameter, recipe, which is the text of the recipe to save
  under the <name>.