From e4c27d634b8238a5ef54f9901d2ed15e4a31882b Mon Sep 17 00:00:00 2001 From: Forrest Alvarez Date: Sun, 20 Oct 2013 02:48:01 +0000 Subject: [PATCH 1/4] Updated the 0.17.0 docs to link over to halite, and clear up that it is not included with salt-master. Created a new halite tutorial that talks about how to set up halite, this is still incomplete for the amount of info I would like in it. --- doc/topics/releases/0.17.0.rst | 13 +++++++++---- doc/topics/tutorials/halite.rst | 0 2 files changed, 9 insertions(+), 4 deletions(-) create mode 100644 doc/topics/tutorials/halite.rst diff --git a/doc/topics/releases/0.17.0.rst b/doc/topics/releases/0.17.0.rst index b0f1319f72..9062819f32 100644 --- a/doc/topics/releases/0.17.0.rst +++ b/doc/topics/releases/0.17.0.rst @@ -23,15 +23,20 @@ Major Features Halite ------ -The new Halite web GUI is now available, a great deal of work has been put into -Halite to make it fully event driven and amazingly fast. The Halite UI can be -started from within the Salt Master, or standalone, and does not require an -external database to run, it is very lightweight! +The new Halite web GUI is now available on PyPi, a great deal of work has +been put into Halite to make it fully event driven and amazingly fast. The +Halite UI can be started from within the Salt Master (after being installed +from PyPi), or standalone, and does not require an external database to run, +it is very lightweight! This initial release of Halite is primarily the framework for the UI and the communication systems making it easy to extend and build the UI up. It presently supports watching the event bus and firing commands over Salt. +At this time Halite is not available as a package, but installation +documentation is available at: +http://docs.saltstack.com/topics/tutorials/halite.html + Halite is, like the rest of Salt, Open Source! Much more will be coming in the future of Halite! diff --git a/doc/topics/tutorials/halite.rst b/doc/topics/tutorials/halite.rst new file mode 100644 index 0000000000..e69de29bb2 From 503972789882ba7cf3080960c8b022104b7b66f3 Mon Sep 17 00:00:00 2001 From: Forrest Alvarez Date: Wed, 23 Oct 2013 04:51:52 +0000 Subject: [PATCH 2/4] initial add of the halite docs, still need a lot of work. --- doc/topics/tutorials/halite.rst | 209 ++++++++++++++++++++++++++++++++ 1 file changed, 209 insertions(+) diff --git a/doc/topics/tutorials/halite.rst b/doc/topics/tutorials/halite.rst index e69de29bb2..a4a1d88b29 100644 --- a/doc/topics/tutorials/halite.rst +++ b/doc/topics/tutorials/halite.rst @@ -0,0 +1,209 @@ +================================= +Installing and Configuring Halite +================================= + +In this tutorial we'll walk through installing and setting up Halite. As of +2013-10-12 a packaged version of Halite is not available, in addition the +current version of Halite is considered pre-aplha and is supportd only in +Salt 0.17 or greater. You will need to check out the latest version from +Github: https://github.com/saltstack/halite + +Installing Halite +================= + +Before beginning this tutorial ensure that the salt-master is installed. To +install the salt-master please review the installation documentation: +http://docs.saltstack.com/topics/installation/index.html + +.. note:: + + Halite only works with Salt versions greater than 0.17. + + +To begin the installation of Halite you'll need to install pip. The +Salt package, as well as the bootstrap do not install pip by default. + +On CentOS: + +.. code-block:: bash + + $ yum install python-pip + + +On Debian: + +.. code-block:: bash + + $ apt-get install python-pip + + +Once you have pip installed, use it to install halite: + +.. code-block:: bash + + $ pip install -U halite + + +Depending on the webserver you want to run halite through, you'll need to +install that piece as well. On RHEL based distros use one of the following: + +.. code-block:: bash + + $ pip install cherrypy + + +.. code-block:: bash + + $ pip install paste + + +.. code-block:: bash + + $ yum install python-devel + $ yum install gcc + $ pip install gevent + + +On Debian based distributions: + +.. code-block:: bash + + $ pip install CherryPy + + +.. code-block:: bash + + $ pip install paste + + +.. code-block:: bash + + $ apt-get install gcc + $ apt-get install python-dev + $ pip install gevent + + +Configuring Halite Permissions +============================== + +Configuring Halite access permissions is easy. By default you only need to +ensure that the @runner group is configured. In the /etc/salt/master file +uncomment and modify the following lines: + +.. code-block:: yaml + + external_auth: + pam: + testuser: + - .* + - '@runner' + + +.. note:: + + You cannot use the root user for pam login, it will fail to authenticate. + +Halite uses the runner manage.status to get the status of minions so runner +permissions are required. As you can see in this example the root user has +been configured, if you aren't running Halite as the root user, you'll need +to modify this value. For example: + +.. code-block:: yaml + + external_auth: + pam: + mytestuser: + - .* + - '@runner' + - '@wheel' + + +Currently Halite allows, but does not require any wheel modules. + + +Configuring Halite settings +=========================== + +Once you've configured the permissions for Halite, you'll need to set up the +Halite settings in the /etc/salt/master file. Halite supports CherryPy, Paste +and Gevent out of the box. + +To configure cherrypy add the following to the bottom of your /etc/salt/master file: + +.. code-block: yaml + + halite: + level: 'debug' + server: 'cherrypy' + host: '0.0.0.0' + port: '8080' + cors: False + tls: True + certpath: '/etc/pki/tls/certs/localhost.crt' + keypath: '/etc/pki/tls/certs/localhost.key' + pempath: '/etc/pki/tls/certs/localhost.pem' + + +If you wish to use paste: + +.. code-block: yaml + + halite: + level: 'debug' + server: 'paste' + host: '0.0.0.0' + port: '8080' + cors: False + tls: True + certpath: '/etc/pki/tls/certs/localhost.crt' + keypath: '/etc/pki/tls/certs/localhost.key' + pempath: '/etc/pki/tls/certs/localhost.pem' + + +To use gevent: + +.. code-block: yaml + + halite: + level: 'debug' + server: 'gevent' + host: '0.0.0.0' + port: '8080' + cors: False + tls: True + certpath: '/etc/pki/tls/certs/localhost.crt' + keypath: '/etc/pki/tls/certs/localhost.key' + pempath: '/etc/pki/tls/certs/localhost.pem' + + +The "cherrypy" and "gevent" servers require the certpath and keypath files +to run tls/ssl. The .crt file holds the public cert and the .key file holds +the private key. Whereas the "paste" server requires a single .pem file that +contains both the cert and key. This can be created simply by concatenating +the .crt and .key files. + +If you want to use a self signed cert you can create one using the Salt.tls +module: + +.. code-block:: bash + + salt '*' tls.create_ca_signed_cert test localhost + + +When using self signed certs, browsers will need approval before accepting the +cert. If the web application page has been cached with a non https version of +the app then the browser cache will have to be cleared before it will +recognize and prompt to accept the self signed certificate. + +Once you've configured the halite section of your /etc/salt/master, you can +restart the salt-master service, and your halite instance will be available. +Depending on your configuration the instance will be available either at +http://localhost:8080/app, http://domain:8080/app, or +http://123.456.789.012:8080/app depending on how your system is configured. + +.. note:: + + halite requires an HTML 5 compliant browser. + + +All logs relating to halite are logged to the default /var/log/salt/master file. From b64dc90a209a6b97949a3fa8d06ee2f3f32eb1c1 Mon Sep 17 00:00:00 2001 From: Forrest Alvarez Date: Wed, 23 Oct 2013 05:22:17 +0000 Subject: [PATCH 3/4] updated hacking (developing) tutorial with information on running a simplye python http server to show changes that you have made. --- doc/topics/hacking.rst | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/doc/topics/hacking.rst b/doc/topics/hacking.rst index 332c00802c..a7b7a4bb15 100644 --- a/doc/topics/hacking.rst +++ b/doc/topics/hacking.rst @@ -431,3 +431,10 @@ Change to salt documentation directory, then: .. code-block:: bash make SPHINXBUILD=sphinx-1.0-build html + +Once you've updated the documentation, you can run the following command to +launch a simple Python http server to see your changes: + +.. code-block:: bash + + cd _build/html; python -m SimpleHTTPServer From d6f78e2484f24d90da750b6ab07dd6e7c4e63ccf Mon Sep 17 00:00:00 2001 From: Forrest Alvarez Date: Thu, 24 Oct 2013 03:56:19 +0000 Subject: [PATCH 4/4] Reworked part of the halite docs to clarify the running of halite itself, created sections in prep for nginx/apache work. --- doc/topics/tutorials/halite.rst | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/doc/topics/tutorials/halite.rst b/doc/topics/tutorials/halite.rst index a4a1d88b29..7da5200709 100644 --- a/doc/topics/tutorials/halite.rst +++ b/doc/topics/tutorials/halite.rst @@ -195,6 +195,10 @@ cert. If the web application page has been cached with a non https version of the app then the browser cache will have to be cleared before it will recognize and prompt to accept the self signed certificate. + +Starting halite +=============== + Once you've configured the halite section of your /etc/salt/master, you can restart the salt-master service, and your halite instance will be available. Depending on your configuration the instance will be available either at @@ -207,3 +211,14 @@ http://123.456.789.012:8080/app depending on how your system is configured. All logs relating to halite are logged to the default /var/log/salt/master file. + + +Running your halite instance through nginx +========================================== + + + +Running your halite instance through apache +=========================================== + +