Migrate the README file to a basic documentation
This commit is contained in:
Christian Berendt
parent
6d5e3abf83
commit
6f8116ed34
153
README.rst
153
README.rst
|
|
@ -1,155 +1,2 @@
|
|||
First App Application for OpenStack (faafo)
|
||||
===========================================
|
||||
|
||||
Workflow
|
||||
--------
|
||||
|
||||
.. image:: images/diagram.png
|
||||
|
||||
FIXME(berendt): Add new API service and webinterface to the workflow description.
|
||||
|
||||
* The producer generates a random number of tasks with random parameters and a UUID as identifier.
|
||||
* The producer pushes the generated tasks into the exchange :code:`tasks`.
|
||||
* The producer inserts a new record for each task into the database (including all parameters and the UUID).
|
||||
* The producer sleeps for a random number of seconds and will generate more tasks after awakening.
|
||||
* All messages in the :code:`tasks` exchange will be routed into the :code:`tasks` queue.
|
||||
* The worker waits for new messages in the :code:`tasks` queue.
|
||||
* After receiving a message the worker generates an image based on the received parameters and writes the result into a local file (identified by the UUID).
|
||||
* After writing an image the worker pushes the result (the checksum of the generated image and the duration identified by the UUID) into the exchange :code:`results`.
|
||||
* All messages in the :code:`results` exchange will be routed into the :code:`results` queue.
|
||||
* The tracker waits for new messages in the :code:`results` queue.
|
||||
* After receiving a message the tracker updates the duration and checksum value of the corresponding database record (identified by the UUID).
|
||||
|
||||
Frameworks
|
||||
----------
|
||||
|
||||
* http://flask.pocoo.org/
|
||||
* http://python-requests.org
|
||||
* http://www.sqlalchemy.org/
|
||||
* https://github.com/celery/kombu
|
||||
* https://pillow.readthedocs.org/
|
||||
|
||||
Example image
|
||||
-------------
|
||||
|
||||
.. image:: images/example.png
|
||||
|
||||
Vagrant environment
|
||||
-------------------
|
||||
|
||||
The `Vagrant <https://www.vagrantup.com/>`_ environment and the `Ansible <http://www.ansible.com/home>`_
|
||||
playbook is used only for local tests and development of the application.
|
||||
|
||||
The installation of Vagrant is described at https://docs.vagrantup.com/v2/installation/index.html.
|
||||
|
||||
The Vagrant plugin `vagrant-hostmanager <https://github.com/smdahlen/vagrant-hostmanager>`_ is required.
|
||||
|
||||
.. code::
|
||||
|
||||
$ vagrant plugin install vagrant-hostmanager
|
||||
|
||||
To speedup the provisioning you can install the Vagrant plugin `vagrant-cachier <https://github.com/fgrehm/vagrant-cachier>`_.
|
||||
|
||||
.. code::
|
||||
|
||||
$ vagrant plugin install vagrant-cachier
|
||||
|
||||
Bootstrap the Vagrant environment.
|
||||
|
||||
.. code::
|
||||
|
||||
$ vagrant up
|
||||
|
||||
The RabbitMQ server and the MySQL server are running on the machine :code:`service.`
|
||||
|
||||
There is a machine for each service of the tutorial application:
|
||||
|
||||
* :code:`api` - :code:`vagrant ssh api` - :code:`sh run_api.sh`
|
||||
* :code:`producer` - :code:`vagrant ssh producer` - :code:`sh run_producer.sh`
|
||||
* :code:`tracker` - :code:`vagrant ssh tracker` - :code:`sh run_tracker.sh`
|
||||
* :code:`worker` - :code:`vagrant ssh worker` - :code:`sh run_worker.sh`
|
||||
|
||||
RabbitMQ server
|
||||
~~~~~~~~~~~~~~~
|
||||
|
||||
The webinterface of the RabbitMQ server is reachable on TCP port :code:`15672`. The login is
|
||||
possible with the user :code:`guest` and the password :code:`secretsecret`.
|
||||
|
||||
MySQL server
|
||||
~~~~~~~~~~~~
|
||||
|
||||
The password of the user :code:`root` is :code:`secretsecret`. The password of the user :code:`tutorial`
|
||||
for the database :code:`tutorial` is also :code:`secretsecret`.
|
||||
|
||||
Virtual environment
|
||||
-------------------
|
||||
|
||||
Create a new virtual environment, install all required dependencies and
|
||||
the application itself.
|
||||
|
||||
.. code::
|
||||
|
||||
$ virtualenv .venv
|
||||
$ source .venv/bin/activate
|
||||
$ pip install -r requirements.txt
|
||||
$ python setup.py install
|
||||
|
||||
Now open a new screen or tmux session. Aftwards run the api, worker, producer, and
|
||||
tracker services in the foreground, each service in a separate window.
|
||||
|
||||
.. code::
|
||||
|
||||
$ source .venv/bin/activate; faafo-api
|
||||
$ source .venv/bin/activate; faafo-worker
|
||||
$ source .venv/bin/activate; faafo-tracker
|
||||
$ source .venv/bin/activate; faafo-producer
|
||||
|
||||
Example outputs
|
||||
---------------
|
||||
|
||||
API Service
|
||||
~~~~~~~~~~~
|
||||
|
||||
FIXME(berendt): add output of the API service
|
||||
|
||||
Producer service
|
||||
~~~~~~~~~~~~~~~~
|
||||
|
||||
FIXME(berendt): update output (introduction of oslo.logging)
|
||||
|
||||
.. code::
|
||||
|
||||
2015-02-12 22:21:42,870 generating 2 task(s)
|
||||
2015-02-12 22:21:42,876 generated task: {'width': 728, 'yb': 2.6351683415972076, 'uuid': UUID('66d5f67e-d26d-42fb-9d88-3c3830b4187a'), 'iterations': 395, 'xb': 1.6486035545865234, 'xa': -1.2576814065507933, 'ya': -2.8587178863035616, 'height': 876}
|
||||
2015-02-12 22:21:42,897 generated task: {'width': 944, 'yb': 2.981696583462036, 'uuid': UUID('6f873111-8bc2-4d73-9a36-ed49915699c8'), 'iterations': 201, 'xb': 3.530775320058914, 'xa': -3.3511031734533794, 'ya': -0.921920674639712, 'height': 962}
|
||||
2015-02-12 22:21:42,927 sleeping for 2.680171 seconds
|
||||
|
||||
Tracker service
|
||||
~~~~~~~~~~~~~~~
|
||||
|
||||
FIXME(berendt): update output (introduction of oslo.logging)
|
||||
|
||||
.. code::
|
||||
|
||||
2015-02-12 22:20:26,630 processing result be42a131-e4aa-4db5-80d1-1956784f4b81
|
||||
2015-02-12 22:20:26,630 elapsed time 5.749099 seconds
|
||||
2015-02-12 22:20:26,631 checksum 7ba5bf955a94f1aa02e5f442869b8db88a5915b7c2fb91ffba74708b8d799c2a
|
||||
|
||||
Worker service
|
||||
~~~~~~~~~~~~~~
|
||||
|
||||
FIXME(berendt): update output (introduction of oslo.logging)
|
||||
|
||||
.. code::
|
||||
|
||||
2015-02-12 22:20:59,258 processing task 20a00e9e-baec-4045-bc57-2cb9d8d1aa61
|
||||
2015-02-12 22:21:01,506 task 20a00e9e-baec-4045-bc57-2cb9d8d1aa61 processed in 2.246601 seconds
|
||||
2015-02-12 22:21:01,553 saved result of task 20a00e9e-baec-4045-bc57-2cb9d8d1aa61 to file /home/vagrant/20a00e9e-baec-4045-bc57-2cb9d8d1aa61.png
|
||||
2015-02-12 22:21:01,554 pushed result: {'duration': 2.246600866317749, 'checksum': 'faa0f00a72fac53e02c3eb392c5da8365139e509899e269227e5c27047af6c1f', 'uuid': UUID('20a00e9e-baec-4045-bc57-2cb9d8d1aa61')}
|
||||
|
||||
References
|
||||
----------
|
||||
|
||||
* http://en.wikipedia.org/wiki/Julia_set
|
||||
* http://en.wikipedia.org/wiki/Mandelbrot_set
|
||||
* http://code.activestate.com/recipes/577120-julia-fractals/
|
||||
|
|
|
|||
|
|
@ -0,0 +1,17 @@
|
|||
# Licensed under the Apache License, Version 2.0 (the "License");
|
||||
# you may not use this file except in compliance with the License.
|
||||
# You may obtain a copy of the License at
|
||||
#
|
||||
# http://www.apache.org/licenses/LICENSE-2.0
|
||||
#
|
||||
# Unless required by applicable law or agreed to in writing, software
|
||||
# distributed under the License is distributed on an "AS IS" BASIS,
|
||||
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
|
||||
# implied.
|
||||
# See the License for the specific language governing permissions and
|
||||
# limitations under the License.
|
||||
|
||||
copyright = u'2015, OpenStack contributors'
|
||||
master_doc = 'index'
|
||||
project = u'First App Application for OpenStack'
|
||||
source_suffix = '.rst'
|
||||
|
|
@ -0,0 +1,72 @@
|
|||
Development
|
||||
===========
|
||||
|
||||
Vagrant environment
|
||||
-------------------
|
||||
|
||||
The `Vagrant <https://www.vagrantup.com/>`_ environment and the `Ansible <http://www.ansible.com/home>`_
|
||||
playbook is used only for local tests and development of the application.
|
||||
|
||||
The installation of Vagrant is described at https://docs.vagrantup.com/v2/installation/index.html.
|
||||
|
||||
The Vagrant plugin `vagrant-hostmanager <https://github.com/smdahlen/vagrant-hostmanager>`_ is required.
|
||||
|
||||
.. code::
|
||||
|
||||
$ vagrant plugin install vagrant-hostmanager
|
||||
|
||||
To speedup the provisioning you can install the Vagrant plugin `vagrant-cachier <https://github.com/fgrehm/vagrant-cachier>`_.
|
||||
|
||||
.. code::
|
||||
|
||||
$ vagrant plugin install vagrant-cachier
|
||||
|
||||
Bootstrap the Vagrant environment.
|
||||
|
||||
.. code::
|
||||
|
||||
$ vagrant up
|
||||
|
||||
The RabbitMQ server and the MySQL server are running on the machine :code:`service.`
|
||||
|
||||
There is a machine for each service of the tutorial application:
|
||||
|
||||
* :code:`api` - :code:`vagrant ssh api` - :code:`sh run_api.sh`
|
||||
* :code:`producer` - :code:`vagrant ssh producer` - :code:`sh run_producer.sh`
|
||||
* :code:`tracker` - :code:`vagrant ssh tracker` - :code:`sh run_tracker.sh`
|
||||
* :code:`worker` - :code:`vagrant ssh worker` - :code:`sh run_worker.sh`
|
||||
|
||||
RabbitMQ server
|
||||
~~~~~~~~~~~~~~~
|
||||
|
||||
The webinterface of the RabbitMQ server is reachable on TCP port :code:`15672`. The login is
|
||||
possible with the user :code:`guest` and the password :code:`secretsecret`.
|
||||
|
||||
MySQL server
|
||||
~~~~~~~~~~~~
|
||||
|
||||
The password of the user :code:`root` is :code:`secretsecret`. The password of the user :code:`tutorial`
|
||||
for the database :code:`tutorial` is also :code:`secretsecret`.
|
||||
|
||||
Virtual environment
|
||||
-------------------
|
||||
|
||||
Create a new virtual environment, install all required dependencies and
|
||||
the application itself.
|
||||
|
||||
.. code::
|
||||
|
||||
$ virtualenv .venv
|
||||
$ source .venv/bin/activate
|
||||
$ pip install -r requirements.txt
|
||||
$ python setup.py install
|
||||
|
||||
Now open a new screen or tmux session. Aftwards run the api, worker, producer, and
|
||||
tracker services in the foreground, each service in a separate window.
|
||||
|
||||
.. code::
|
||||
|
||||
$ source .venv/bin/activate; faafo-api
|
||||
$ source .venv/bin/activate; faafo-worker
|
||||
$ source .venv/bin/activate; faafo-tracker
|
||||
$ source .venv/bin/activate; faafo-producer
|
||||
|
Before Width: | Height: | Size: 39 KiB After Width: | Height: | Size: 39 KiB |
|
Before Width: | Height: | Size: 40 KiB After Width: | Height: | Size: 40 KiB |
|
|
@ -0,0 +1,11 @@
|
|||
Implementation
|
||||
==============
|
||||
|
||||
Frameworks
|
||||
----------
|
||||
|
||||
* http://flask.pocoo.org/
|
||||
* http://python-requests.org
|
||||
* http://www.sqlalchemy.org/
|
||||
* https://github.com/celery/kombu
|
||||
* https://pillow.readthedocs.org/
|
||||
|
|
@ -0,0 +1,13 @@
|
|||
First App Application for OpenStack
|
||||
===================================
|
||||
|
||||
Contents:
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
workflow
|
||||
implementation
|
||||
usage
|
||||
development
|
||||
references
|
||||
|
|
@ -0,0 +1,6 @@
|
|||
References
|
||||
==========
|
||||
|
||||
* http://en.wikipedia.org/wiki/Julia_set
|
||||
* http://en.wikipedia.org/wiki/Mandelbrot_set
|
||||
* http://code.activestate.com/recipes/577120-julia-fractals/
|
||||
|
|
@ -0,0 +1,51 @@
|
|||
Usage
|
||||
=====
|
||||
|
||||
Example image
|
||||
-------------
|
||||
|
||||
.. image:: images/example.png
|
||||
|
||||
|
||||
Example outputs
|
||||
---------------
|
||||
|
||||
API Service
|
||||
~~~~~~~~~~~
|
||||
|
||||
FIXME(berendt): add output of the API service
|
||||
|
||||
Producer service
|
||||
~~~~~~~~~~~~~~~~
|
||||
|
||||
FIXME(berendt): update output (introduction of oslo.logging)
|
||||
|
||||
.. code::
|
||||
|
||||
2015-02-12 22:21:42,870 generating 2 task(s)
|
||||
2015-02-12 22:21:42,876 generated task: {'width': 728, 'yb': 2.6351683415972076, 'uuid': UUID('66d5f67e-d26d-42fb-9d88-3c3830b4187a'), 'iterations': 395, 'xb': 1.6486035545865234, 'xa': -1.2576814065507933, 'ya': -2.8587178863035616, 'height': 876}
|
||||
2015-02-12 22:21:42,897 generated task: {'width': 944, 'yb': 2.981696583462036, 'uuid': UUID('6f873111-8bc2-4d73-9a36-ed49915699c8'), 'iterations': 201, 'xb': 3.530775320058914, 'xa': -3.3511031734533794, 'ya': -0.921920674639712, 'height': 962}
|
||||
2015-02-12 22:21:42,927 sleeping for 2.680171 seconds
|
||||
|
||||
Tracker service
|
||||
~~~~~~~~~~~~~~~
|
||||
|
||||
FIXME(berendt): update output (introduction of oslo.logging)
|
||||
|
||||
.. code::
|
||||
|
||||
2015-02-12 22:20:26,630 processing result be42a131-e4aa-4db5-80d1-1956784f4b81
|
||||
2015-02-12 22:20:26,630 elapsed time 5.749099 seconds
|
||||
2015-02-12 22:20:26,631 checksum 7ba5bf955a94f1aa02e5f442869b8db88a5915b7c2fb91ffba74708b8d799c2a
|
||||
|
||||
Worker service
|
||||
~~~~~~~~~~~~~~
|
||||
|
||||
FIXME(berendt): update output (introduction of oslo.logging)
|
||||
|
||||
.. code::
|
||||
|
||||
2015-02-12 22:20:59,258 processing task 20a00e9e-baec-4045-bc57-2cb9d8d1aa61
|
||||
2015-02-12 22:21:01,506 task 20a00e9e-baec-4045-bc57-2cb9d8d1aa61 processed in 2.246601 seconds
|
||||
2015-02-12 22:21:01,553 saved result of task 20a00e9e-baec-4045-bc57-2cb9d8d1aa61 to file /home/vagrant/20a00e9e-baec-4045-bc57-2cb9d8d1aa61.png
|
||||
2015-02-12 22:21:01,554 pushed result: {'duration': 2.246600866317749, 'checksum': 'faa0f00a72fac53e02c3eb392c5da8365139e509899e269227e5c27047af6c1f', 'uuid': UUID('20a00e9e-baec-4045-bc57-2cb9d8d1aa61')}
|
||||
|
|
@ -0,0 +1,18 @@
|
|||
Workflow
|
||||
--------
|
||||
|
||||
.. image:: images/diagram.png
|
||||
|
||||
FIXME(berendt): Add new API service and webinterface to the workflow description.
|
||||
|
||||
* The producer generates a random number of tasks with random parameters and a UUID as identifier.
|
||||
* The producer pushes the generated tasks into the exchange :code:`tasks`.
|
||||
* The producer inserts a new record for each task into the database (including all parameters and the UUID).
|
||||
* The producer sleeps for a random number of seconds and will generate more tasks after awakening.
|
||||
* All messages in the :code:`tasks` exchange will be routed into the :code:`tasks` queue.
|
||||
* The worker waits for new messages in the :code:`tasks` queue.
|
||||
* After receiving a message the worker generates an image based on the received parameters and writes the result into a local file (identified by the UUID).
|
||||
* After writing an image the worker pushes the result (the checksum of the generated image and the duration identified by the UUID) into the exchange :code:`results`.
|
||||
* All messages in the :code:`results` exchange will be routed into the :code:`results` queue.
|
||||
* The tracker waits for new messages in the :code:`results` queue.
|
||||
* After receiving a message the tracker updates the duration and checksum value of the corresponding database record (identified by the UUID).
|
||||
11
setup.cfg
11
setup.cfg
|
|
@ -31,5 +31,16 @@ console_scripts =
|
|||
faafo-worker = faafo.worker:main
|
||||
faafo-api = faafo.api:main
|
||||
|
||||
[build_sphinx]
|
||||
source-dir = doc/source
|
||||
build-dir = doc/build
|
||||
all_files = 1
|
||||
|
||||
[upload_sphinx]
|
||||
upload-dir = doc/build/html
|
||||
|
||||
[wheel]
|
||||
universal = 1
|
||||
|
||||
[pbr]
|
||||
warnerrors = true
|
||||
|
|
|
|||
|
|
@ -1 +1,2 @@
|
|||
hacking
|
||||
sphinx>=1.1.2,!=1.2.0,!=1.3b1,<1.3
|
||||
|
|
|
|||
Loading…
Reference in New Issue