diff --git a/README.rst b/README.rst index 8882975..0fd557d 100644 --- a/README.rst +++ b/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 `_. diff --git a/doc/source/getting_started.rst b/doc/source/getting_started.rst new file mode 100644 index 0000000..7b346d0 --- /dev/null +++ b/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 `_ 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` + diff --git a/doc/source/index.rst b/doc/source/index.rst index 3b36b61..f0ece5d 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -8,6 +8,8 @@ Table of Contents: :maxdepth: 2 readme + getting_started + project_architecture webapi/index Indices and tables diff --git a/doc/source/project_architecture.rst b/doc/source/project_architecture.rst new file mode 100644 index 0000000..2aaace8 --- /dev/null +++ b/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 `_: REST API +* `python-surveilclient `_: command line interface and Python library +* `Alignak `_: Core monitoring framework +* `Bansho `_: Surveil web interface +* `InfluxDB `_: Storing metrics +* `Redis `_: API caching +* `Grafana `_: Data visualization diff --git a/docker-compose.yml b/docker-compose.yml index 6020ba8..c08b5b7 100644 --- a/docker-compose.yml +++ b/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/