halite 0.1.17

======
Halite
======

(Code-name) Halite is a Salt GUI. Status is pre-alpha. Contributions are
very welcome. Join us in #salt on Freenode or on the salt-users mailing
list.

For best results it is recommended to use Halite with the develop branch of Salt.
Halite is, however, known to work with Salt version greater than ``Hydrogen``.
To install the develop branch of Salt:

.. code-block:: bash

$gitclone-bdevelophttps://github.com/saltstack/salt.git$ cd salt && python setup.py install
$salt-master--version$ salt-master -l debug

This version of Halite is designed to work out of the box with SaltStack when
the PyPi package version of Halite is installed. The PyPi (PIP) version of Halite
is a minified version tailored for this purpose. (https://pypi.python.org/pypi/halite)
Halite makes use of the ``Bottle`` (WSGI) web framework. Servers that are tested and
known to work with Halite are ``paste``, ``cherrypy`` and ``gevent``.

To pip install Halite.

.. code-block:: bash

$pipinstall-UhaliteThispurposeofthsrepositoryistoenabledevelopmentofcustomversionsoftheUIthatcouldbedeployedwithdifferentservers,differentconfigurations,etcandalsofordevelopmentoffuturefeaturesfortheSaltpackagedversion.Features========HighstateConsistencyCheck---------------------------Halitecanpollforhighstateconsistency.Thisissimilartoexecuting‘‘salt\text{*}state.highstatetest=True‘‘andcheckingfortheresults.Pollingisturned‘‘OFF‘‘bydefault.Toswitchpollingonnavigatetothepreferencestabandcheck‘‘highStateCheck.performCheck‘‘.Thepolltimercanbeadjustedusing‘‘highStateCheck.intervalSeconds‘‘andissetto300Seconds(5minutes)bydefault.Oncethesesettingsareupdatedclick‘‘Update‘‘andreloadthepage.Theseoptionsaredepictedinthescreenshotbelow...image::screenshots/HighstatePollSettings.pngHighstateconsistencycheckresultscanbeseenontheminionview.Minionsthathaveinconsistentstatehaveaflagnexttothemasshowninthescreenshot...image::screenshots/MinionWithFlag.pngThe‘‘Highstate‘‘subtabforeachminiondisplaysthestateitemsthatlackconsistency.Alloftheinconsistentitemswillbedisplayedhereforeasyvisualization.Thescreenshotbelowshowsamessagethatmightappearwhenhighstateconsistencyisdisturbed...image::screenshots/HighstateSubtab.pngThecogiconthatappearsinthe‘‘Monitor‘‘sectioncanbeclickedtoperformhighstateconsistencycheck.Theondemandcheckonlyworksinthescenariowherepollingisoff.Inthecasewherepollingisswitchedon(asdiscussedabove)thecogiconwillappeartobespinning(anddoesnotrespondtoclicks)...image::screenshots/HighstateCheckCog.pngInstallationquickstart=======================Thissectionexplainsinstallationofthe‘‘devlopment‘‘versionofHalite.IfyouareinterestedininstallingHaliteasanenduser,pleasefollowthe‘tutorial<http://docs.saltstack.com/topics/tutorials/halite.html>{‘}_{i}nstead.\ast SetuppermissionsforuserswhowilluseHaliteForexampleinmasterconfig:..code-block::bashexterna{l}_{a}uth:pam:myusername:-.\ast {-}^{\prime }@runne{r}^{\prime }{-}^{\prime }@whee{l}^{\prime }Haliteusestherunner‘‘manage.present‘‘togetthestatusofminionssorunnerpermissionsarerequired.CurrentlyHaliteallowsbutdoesnotrequireanywheelmodules.\ast ClonetheHaliterepository::..code-block::bashgitclonehttps://github.com/saltstack/halite\ast Runhalite/halite/serve{r}_{b}ottle.py(usewith-hoptiontogetparameters)Thesimplestapproachistoruntheserverwithitdynamicallygeneratingthemainwebapploadpage(main.html)incoffescriptmode,wherethecoffeescriptistranspiledtojavascriptonthefly.Ineachcasetheappropriateserverpackagemustbeinstalled...code-block::bash$ ./server_bottle.py -d -C -l debug -s cherrypy

$./serve{r}_{b}ottle.py-d-C-ldebug-spaste$ ./server_bottle.py -d -C -l debug -s gevent



* Navigate html5 compliant browser to http://localhost:8080/app

* Login
The default eauth method is 'pam'. To change go to the preferences page.

Documentation
=============

Preferences
-----------

The navbar has a login form. Enter the eauth username and password to login to salt.

.. image:: screenshots/LoggedOut.png

Once logged in, the navbar will display the username highlighted in blue and a logout button.
To logout click on the logout button.

.. image:: screenshots/LoggedIn.png



Click on the SaltStack logo to go to the preferences page

.. image:: screenshots/Preferences.png

On this page one can change the eauth method to something other than 'pam' such
as 'ldap'.

Check ``fetchGrains`` if you want grains data to be loaded when Halite loads.
Checking ``preloadJobCache`` will fetch all previously completed, cached jobs.

Once all changes are made click ``Update`` and refresh the browser page.

Commands
----------

To navigate to the console view click on the 'console' tab.

.. image:: screenshots/HomeConsole.png

This view has two sections. The ``Command`` section and the ``Monitor`` section.
The ``Command`` section is collapsed by default. Clicking on the downward chevron will
expand the ``Command`` section.

The top section of the Console view has controls for entering basic salt commands.
The target field will target minions with the command selected. There is ping button
with the bullhorn icon and the action menu has some preselected common commands.

Expanded Commands
-----------------

.. image:: screenshots/CommandForm.png

Click on the downward chevron button to expand the ``Command`` form with additional
fields for entering any salt module function. To enter "runner" functions prepend
"runner." to the function name. For example, "runner.manage.status". To enter wheel
functions prepend "wheel." to the wheel function name. For example, "wheel.config.values".
For commands that require arguments enter them in the arguments fields. The number of argument
fields equals the number of arguments accepted by the function.

Click on the Execute button or press the Return key to execute the command.

You can choose the ``Target Format`` which will be used by the ``Target`` field to target minions.

There is a ping button with the bullhorn icon and the Macro menu has some preselected commands
for "speed dial".

There is also a history feature which appears as a book icon on the top right corner of the ``Command`` panel.

Checking ``Live Doc Search`` will show the documentation related to the command being
entered in the ``Function`` field. Un-check it to conserve screen real estate.

Monitors
---------

The bottom section of the console view has monitor view buttons. Each button will
show panels with the associated information.

* Command Monitor

Shows panels, one per command that has been executed by this user on this console.
Clicking on the dropdown button will show the associated job ids that have been
run with this command and the completion status via an icon.
Red is fail, Green is success.
Clicking on the button on the panel will rerun the command.

.. image:: screenshots/CommandMonitor.png

* Job Monitor

Shows panels, one per job that has been run by any minion associated with this
master. Clicking on the associated dropdown button with expand to show Result and Event data.
Selecting the result button will show the returner and return data
for each minion targeted by the job.

.. image:: screenshots/JobMonitor.png

Selecting the Event button will show the events associated with the job.

.. image:: screenshots/JobMonitorEvent.png

* Minion Monitor

Shows panels, one per minion that have keys associated with this master. The minion
panels have icons to show the up/down status of the minion and the grains status.
Selecting dropdown buttons will show grains data as well as minion (not job) generated events.

.. image:: screenshots/MinionMonitor.png



With the grains button selected one can see all the grains for the minion.

.. image:: screenshots/MinionGrains.png




* Event Monitor

Shows panels, one per event associated with this Master.

.. image:: screenshots/EventMonitor.png

More details coming. TBD


Browser requirements
--------------------

Support for ES5 and HTML5 is required. This means any modern browser or IE10+.

Server requirements
-------------------

* The static media for this app is server-agnostic and may be served from any
web server at a configurable URL prefix.
* This app uses the HTML5 history API.

Libraries used
--------------

Client side web application requirements:

* AngularJS framework (http://angularjs.org/)
* Bootstrap layout CSS (http://twbs.github.io/bootstrap/)
* AngularUI framework (http://angular-ui.github.io/)
* Underscore JS module (http://underscorejs.org/‎)
* Underscore string JS module (http://epeli.github.io/underscore.string/)
* Font Awesome Bootstrap Icon Fonts (http://fortawesome.github.io/Font-Awesome/)
* CoffeeScript Python/Ruby like javascript transpiler (http://coffeescript.org/)
* Karma Test Runner (http://karma-runner.github.io/0.8/index.html)
* Jasmine unit test framework (http://pivotal.github.io/jasmine/)
* Protractor E2E test framework for angular apps (https://github.com/angular/protractor)

Optional dependencies:

* Cherrypy web server (http://http://www.cherrypy.org/)
* Paste web server (http://pythonpaste.org/)
* Gevent web server(http://www.gevent.org/)

For nodejs testing:

* Express javascript web server


Deployment
-------------

There are two approaches to deploying Halite.

1) Use it from Salt.
The 0.17 release of salt will run halite automatically if the Halite package is
installed. So for example after installing SaltStack one can install the Halite
python package with

.. code-block:: bash

$pipinstall-UhaliteConfigurethemasterconfigforhaliteasfollows...code-block::bashhalite:level{:}^{\prime }debu{g}^{\prime }server{:}^{\prime }cherryp{y}^{\prime }host{:}^{\prime }0.0.0{.0}^{\prime }port{:}^{\prime }{8080}^{\prime }cors:Falsetls:Truecertpath{:}^{\prime }/etc/pki/tls/certs/localhost.cr{t}^{\prime }keypath{:}^{\prime }/etc/pki/tls/certs/localhost.ke{y}^{\prime }pempath{:}^{\prime }/etc/pki/tls/certs/localhost.pe{m}^{\prime }The"cherrypy"and"gevent"serversrequirethecertpathandkeypathfilestoruntls/ssl.The.crtfileholdsthepubliccertandthe.keyfileholdstheprivatekey.Whereasthe"paste"serverrequiresasingle.pemfilethatcontainsboththecertandkey.Thiscanbecreatedsimplybyconcatenatingthe.crtand.keyfiles.IfyouwanttouseaselfsignedcertyoucancreateoneusingtheSalt.tlsmodule..code-block::bashsal{t}^{\prime }{\ast }^{\prime }tls.creat{e}_c{a}_{s}igne{d}_{c}erttestlocalhostWhenusingselfsignedcerts,browserswillneedapprovalbeforeacceptingthecert.Ifthewebapplicationpagehasbeencachedwithanonhttpsversionoftheappthenthebrowsercachewillhavetobeclearedbeforeitwillrecognizeandprompttoaccepttheselfsignedcertificate.YouwillalsoneedtoconfiguretheeauthmethodtobeusedbyusersoftheWUI.Seequickstartaboveforanexample.Installtheappropriatehttpwsgiserverselectedinthemasterconfigabove.Inthiscaseits"cherrypy".Theothertestedserversare"paste"and"gevent".Theservermustbemulti-threaded,asynchronous,ormulti-processinginordertosupporttheServerSentEventstreamingconnnectionusedbytheWUI.RestarttheSaltStackMasterandnavigateyourhtml5compliantbrowsertohttps://localhost:8080/apporhoweveryouhaveconfiguredyourmasterabove.Ifyouhaveproblemslookfor"Halite:"inthesaltstackmasterlogoutput.CustomizedDeployment====TheHalitegithubrepositoryprovidesaskeletonframeworkforbuildingyourowncustomdeployment.Onecanrunthedefaultbottle.pyframworkformthecommandlinethusly..code-block::bash$ ./server_bottly.py -g
$./serve{r}_{b}ottle.py-scherrypyorfromapythonapplication..code-block::pythonimporthalitehalite.start()Thefullsetofoptionsisgivenby..code-block::bash$ ./server_bottle.py -h
usage: server_bottle.py [-h] [-l {info,debug,critical,warning,error}]
[-s SERVER] [-a HOST] [-p PORT] [-b BASE] [-x] [-t]
[-c CERT] [-k KEY] [-e PEM] [-g] [-f LOAD] [-C] [-d]

Runs localhost web application wsgi service on given host address and port.
Default host:port is 0.0.0.0:8080. (0.0.0.0 is any interface on localhost)

optional arguments:
-h, --help show this help message and exit
-l {info,debug,critical,warning,error}, --level {info,debug,critical,warning,error}
Logging level.
-s SERVER, --server SERVER
Web application WSGI server type.
-a HOST, --host HOST Web application WSGI server ip host address.
-p PORT, --port PORT Web application WSGI server ip port.
-b BASE, --base BASE Base Url path prefix for client side web application.
-x, --cors Enable CORS Cross Origin Resource Sharing on server.
-t, --tls Use TLS/SSL (https).
-c CERT, --cert CERT File path to tls/ssl cacert certificate file.
-k KEY, --key KEY File path to tls/ssl private key file.
-e PEM, --pem PEM File path to tls/ssl pem file with both cert and key.
-g, --gen Generate web app load file. Default is 'app/main.html'
or if provided the file specified by -f option.
-f LOAD, --load LOAD Filepath to save generated web app load file upon -g
option.
-C, --coffee Upon -g option generate to load coffeescript.
-d, --devel Development mode.

The http server provides two functions.

1) Provide content delivery network for the base load of the web application static
content such as html and javascript files.

2) Provide dynamic rest api interface to salt/client/api.py module that is used by
the web application via ajax and SSE connections. Because SSE and CORS
(Cross Origin Resource Sharing is not univesally supported even among HTML5 compliant
browsers, a single server serves both the static content and the rest API).
An alternative approach would be to to use a web socket to stream the events.
This would not require CORS. This may bea future option for Halite.

To deploy with apache, modify server_bottle.startServer so it creates the app but
does not call bottle.run on it but returns it to MOD_WSGI.
See (http://bottlepy.org/docs/dev/deployment.html) for other details in using bottle.py
with Apache and Mod_wsgi.

To do a custom deployment with some other framework like Django etc. would involve
replicating the endpoints from server_bottle.

Architecture
-------------

The following diagram illustrates how the various pieces to Halite interact.

.. image:: diagrams/HaliteArchitecture.png

Testing
-------

To run the karma jasmine ``unit test`` runner

.. code-block:: bash

$cdhalite$ karma start karma_unit.conf.js

To run the protractor ``e2e test`` runner first start up a web server. More information
about using protractor can be found on their website.

Make sure that the end to end test is setup to login to Halite

.. code-block:: bash
$vimhalite/test/spec-e2e/credentials.coffeeInthatfilechangethefollowing..code-block::coffeescriptlogin=username{:}^{\prime }you{r}_{h}alit{e}_{u}sernam{e}^{\prime }password{:}^{\prime }you{r}_{h}alit{e}_{p}asswor{d}^{\prime }Nowyoucanrunthetestsusingthefollowingcommands.Makesureyouhavethe‘‘webdriver-manager‘‘started.Moreinfocanbefoundonthe‘Protractor<https://github.com/angular/protractor>{‘}_{w}ebpage...code-block::bash$ cd halite
$protractorprotractor.conf.jsTorunthe‘‘functional‘‘testsmakesureyouhavethePython‘‘webtest‘‘and‘‘nose‘‘modulesinstalled.Enteryourcredentialsandtheminionnameinanewfilecalled‘‘halite/test/functional/config/override.conf‘‘..code-block::python[login]username=you{r}_{u}se{r}_{n}amepassword=you{r}_{p}assword[minions]apache=minio{n}_{c}onnecte{d}_t{o}_{t}hi{s}_{m}asterThefunctionaltestscanberunvia‘‘nose‘‘...code-block::bash$ cd halite
$nosetestsYoumighthavetobuildthedistribution(fordevelopment)..code-block::bash$ cd halite
$ ./prep_dist.py


Subtree can be fetched by running ``git subtree pull --prefix=halite/lattice lattice master --squash``

.. ............................................................................
.. _`halite`: https://github.com/saltstack/halite