Merge "Update installation instructions"

doc/source/faq.rst

@@ -26,6 +26,7 @@ Just update resource::
 
     solar resource update rsync1 '{"password": "vagrant", "key": null}'
 
+.. _faq_running_celery_worker:
 
 .. note::
 
@@ -53,6 +54,7 @@ There are several places where we search for config values:
 3. `.config.override` in CWD
 4. You can also set upper-cased env variable which matches one of those in config
 
+.. _faq_using_sqlbackend:
 
 Why do you use celery with SQL backend instead of X ?
 -----------------------------------------------------
@@ -62,6 +64,7 @@ For simplicity, but nothing stops you from changing these defaults::
   celery_broker: sqla+sqlite:////tmp/celery.db
   celery_backend: db+sqlite:////tmp/celery.db
 
+.. _faq_what_database:
 
 What database can I use with solar ?
 ------------------------------------

doc/source/installation.rst

@@ -1,14 +1,25 @@
 Installation
 ============
 
+Please note that currently Solar is in a beta stage and it shouldn't be used on
+production.
+
+We also recommend testing Solar in a vagrant env where fully working development
+environment will be created.
+
+If you want to try Solar outside Vagrant jump to `Local environment`_
+
 Supported development platforms
 -------------------------------
 
 Linux or MacOS
 
-Additional software
+Vagrant environment
 -------------------
 
+Additional software
+~~~~~~~~~~~~~~~~~~~
+
 `VirtualBox <https://www.virtualbox.org/wiki/Downloads/>`_ 5.x,
 `Vagrant <http://www.vagrantup.com/downloads.html/>`_ 1.7.x
 
@@ -18,21 +29,23 @@ Note: Make sure that `Vagrant VirtualBox Guest plugin <https://github.com/dotles
 
   vagrant plugin install vagrant-vbguest
 
-Note: If you are using VirtualBox 5.0 it's worth uncommenting paravirtprovider setting in `vagrant-settings.yaml` for speed improvements:
+Note: If you are using VirtualBox 5.0 on Linux system, it's worth uncommenting paravirtprovider
+setting in `vagrant-settings.yaml` for speed improvements:
 
 .. code-block:: bash
 
   paravirtprovider: kvm
 
-For details see Customizing `vagrant-settings.yaml` section.
+For details see `Customizing vagrant-settings.yaml`_ section.
 
 Setup development env
----------------------
+~~~~~~~~~~~~~~~~~~~~~
 
 Setup environment:
 
 .. code-block:: bash
 
+  git clone https://github.com/openstack/solar
   cd solar
   vagrant up
 
@@ -49,7 +62,8 @@ Get ssh details for running slave nodes (vagrant/vagrant):
 
   vagrant ssh-config
 
-You can make/restore snapshots of boxes (this is way faster than reprovisioning them)
+You can make/restore snapshots of boxes (this is way faster than reprovisioning
+them)
 with the `snapshotter.py` script:
 
 .. code-block:: bash
@@ -60,20 +74,86 @@ with the `snapshotter.py` script:
 
 `snapshoter.py` to run requires python module `click`.
 
-1. On debian based systems you can install it via `sudo aptitude install python-click-cli`,
-2. On fedora 22 you can install it via `sudo dnf install python-click`,
-3. If you use virtualenv or similar tool then you can install it just with `pip install click`,
-4. If you don't have virtualenv and your operating system does not provide package for it then `sudo pip install click`.
-5. If you don't have `pip` then [install it](https://pip.pypa.io/en/stable/installing/) and then execute command step 4.
+* On debian based systems you can install it via
+ `sudo aptitude install python-click-cli`,
+* On fedora 22 you can install it via `sudo dnf install python-click`,
+* If you use virtualenv or similar tool then you can install it just with
+ `pip install click`,
+* If you don't have virtualenv and your operating system does not provide
+ package for it then `sudo pip install click`.
+* If you don't have `pip` then
+ [install it](https://pip.pypa.io/en/stable/installing/) and then execute
+ command step 4.
 
 Customizing vagrant-settings.yaml
----------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Solar is shipped with sane defaults in `vagrant-setting.yaml_defaults`. If you need to adjust them for your needs, e.g. changing resource allocation for VirtualBox machines, you should just compy the file to `vagrant-setting.yaml` and make your modifications.
+Solar is shipped with sane defaults in `vagrant-setting.yaml_defaults`. If you
+need to adjust them for your needs, e.g. changing resource allocation for
+VirtualBox machines, you should just copy the file to `vagrant-setting.yaml`
+and make your modifications.
 
 Image based provisioning with Solar
--------------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+* In `vagrant-setting.yaml_defaults` or `vagrant-settings.yaml` file uncomment
+  `preprovisioned: false` line.
+* Run `vagrant up`, it will take some time because it builds image for
+  bootstrap and IBP images.
+* Now you can run provisioning
+  `/vagrant/solar-resources/examples/provisioning/provision.sh`
+
+Local environment
+-----------------
+
+If you want to test Solar locally you may install it via pip:
+
+.. code-block:: bash
+
+  pip install solar
+
+Create solar configuration `solar_config` and paste following data:
+
+.. code-block:: yaml
+
+  celery_broker: sqla+sqlite:////tmp/celery.db
+  celery_backend: db+sqlite:////tmp/celery.db
+  solar_db: sqlite:////tmp/solar.db
+
+and set path to this configuration:
+
+.. code-bloc:: bash
+
+  export SOLAR_CONFIG_OVERRIDE=<full/path/solar_config>
+
+For more information about configuration see our FAQ questions:
+:ref:`here <faq_using_sqlbackend>` and
+:ref:`here <faq_what_database>`.
+
+You also need to download Solar resources and
+add them to a Solar repository.
+
+.. code-block:: bash
+
+  git clone https://github.com/Mirantis/solar-resources
+
+  sudo mkdir -p /var/lib/solar/repositories
+  sudo chown -R <your_user_name> /var/lib/solar/
+
+  solar repo import -l solar-resources/resources/
+  solar repo import -l solar-resources/templates/
+
+Next step is to start Solar orchestration worker.
+
+.. code-block:: bash
+
+  pip install gevent
+  sudo mkdir -p /var/run/celery/
+  sudo chown salmon -R /var/run/celery/
+  solar-celery start
+
+.. note::
+
+  `gevent` is not required to use Solar. If you don't want to use it
+  see :ref:`How can I run solar celery worker <faq_running_celery_worker>`.
 
-* In `vagrant-setting.yaml_defaults` or `vagrant-settings.yaml` file uncomment `preprovisioned: false` line.
-* Run `vagrant up`, it will take some time because it builds image for bootstrap and IBP images.
-* Now you can run provisioning `/vagrant/solar-resources/examples/provisioning/provision.sh`