Improved getting_started documentation

Change-Id: I507c4a6149a94ec5b3411eae892cf7d09ac66256

README.rst

@@ -18,36 +18,8 @@ Project Info
 * Open Gerrit Changesets: https://review.openstack.org/#/q/status:open+surveil,n,z
 * Bug tracker: https://bugs.launchpad.net/surveil
 
-Getting Started
+
+Getting started
 ###############
 
-Developpement environnement
----------------------------
-
-Surveil's developpement environnement is based on Docker and docker-compose.
-
-You can install docker-compose with the following command:
-
-    :bash:`sudo pip install -U docker-compose`
-
-You will then be able to use the environment with the following commands:
-
-* :bash:`sudo docker-compose up`: Launch Surveil and its dependencies in containers.
-* :bash:`sudo docker-compose down`: Kill the active docker containers, if any.
-* :bash:`sudo docker-compose rm`: Remove all containers, if any.
-* :bash:`sudo docker-compose`: Build the docker images.
-
-Configuration for the different services running in the Docker containers are
-stored in tools/docker.
-
-After running :bash:`sudo docker-compose up`, you should be able to acces all
-services at the ports configured in the docker-compose.yml file.
-
-* Surveil API: http://localhost:8080/v1/hello
-* Bansho (surveil web interface): http://localhost:8888 (any login info is fine)
-* InfluxDB: http://localhost:8083 (user:root pw:root)
-* Grafana: http://localhost:80 (user:admin pw:admin)
-* Shinken WebUI: http://localhost:7767/all (user:admin pw:admin)
-
-The Surveil container mounts your local project folder and pecan reloads every
-time the project files change thus providing a proper development environment.
+There is a getting started guide available `here <https://surveil.readthedocs.org>`_.

doc/source/getting_started.rst

@@ -0,0 +1,66 @@
+.. role:: bash(code)
+   :language: bash
+
+Getting Started
+###############
+
+Developpement environnement
+---------------------------
+
+1. Starting the containers
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Surveil's developpement environnement is based on Docker and docker-compose.
+
+You can install docker-compose with the following command:
+
+    :bash:`sudo pip install -U docker-compose`
+
+You will then be able to use the environment with the following commands:
+
+* :bash:`sudo docker-compose up`: Launch Surveil and its dependencies in containers.
+* :bash:`sudo docker-compose down`: Kill the active docker containers, if any.
+* :bash:`sudo docker-compose rm`: Remove all containers, if any.
+* :bash:`sudo docker-compose build`: Build the docker images.
+
+Configuration for the different services running in the Docker containers are
+stored in tools/docker.
+
+After running :bash:`sudo docker-compose up`, you should be able to acces all
+services at the ports configured in the docker-compose.yml file.
+
+* Surveil API: http://localhost:8080/v1/hello
+* Bansho (surveil web interface): http://localhost:8888 (any login info is fine)
+* InfluxDB: http://localhost:8083 (user:root pw:root)
+* Grafana: http://localhost:80 (user:admin pw:admin)
+* Shinken WebUI: http://localhost:7767/all (user:admin pw:admin)
+
+After about 40 seconds, a script will be executed to create fake hosts in the
+Surveil configuration. You should see it in the docker-compose logs.
+
+The Surveil container mounts your local project folder and pecan reloads every
+time the project files change thus providing a proper development environment.
+
+**Note**: Fedora users might want to uncomment the :bash:`privileged: true` line in `docker.compose.yml` if they face permissions issues.
+
+2. Interacting with the API
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You can use the `python-surveilclient <https://pypi.python.org/pypi/python-surveilclient>`_ CLI to interact with the API.
+
+Install it with the following command:
+
+    :bash:`sudo pip install -U python-surveilclient`
+
+You'll need to provide the Surveil API URL. You can do this with the
+``--surveil-api-url`` parameter, but its easier to just set it as environment
+variable::
+
+    export SURVEIL_API_URL=http://localhost:8080/v2
+    export SURVEIL_AUTH_URL=http://localhost:8080/v2/auth
+
+
+You can now use the CLI to view the status of the currently monitored hosts:
+
+    :bash:`surveil status-host-list`
+

doc/source/index.rst

@@ -8,6 +8,8 @@ Table of Contents:
    :maxdepth: 2
 
    readme
+   getting_started
+   project_architecture
    webapi/index
 
 Indices and tables

doc/source/project_architecture.rst

@@ -0,0 +1,22 @@
+Surveil project architecture
+============================
+
+Global project architecture
+###########################
+
+.. image:: https://github.com/stackforge/surveil-specs/raw/master/surveil_architecture.png
+   :height: 2400px
+   :width: 800px
+   :alt: Surveil software architecture
+   :align: center
+
+Main components
+###############
+
+* `Surveil <https://github.com/stackforge/surveil>`_: REST API
+* `python-surveilclient <https://github.com/stackforge/python-surveilclient>`_: command line interface and Python library
+* `Alignak <https://github.com/Alignak-monitoring/alignak>`_: Core monitoring framework
+* `Bansho <https://github.com/stackforge/bansho>`_: Surveil web interface
+* `InfluxDB <https://github.com/influxdb/influxdb>`_: Storing metrics
+* `Redis <http://redis.io/>`_: API caching
+* `Grafana <http://grafana.org/>`_: Data visualization

docker-compose.yml

@@ -11,6 +11,7 @@ surveil:
   volumes:
    - ./surveil:/opt/surveil/surveil
   command: bash -c "cd /opt/surveil && ./setup.sh && python setup.py develop && ((sleep 40 && surveil-init --demo) &) && sleep 20 && surveil-api --reload"
+#  privileged: true # Fedora users might want to uncomment this if they face permission issues
 
 shinken:
   build: tools/docker/shinken_container/