docs/main/HelloWorld.rst | 6 docs/main/IntegratingWithTG2.rst | 199 ++++++++++++--------------- docs/main/MokshaHub.rst | 6 docs/main/PluginEntryPoints.rst | 40 ++++- docs/main/RPMInstallation.rst | 66 +++----- docs/main/Security.rst | 9 + docs/main/UsingLiveSocketOutsideOfMoksha.rst | 15 +- docs/main/VirtualenvInstallation.rst | 10 + 8 files changed, 188 insertions(+), 163 deletions(-)
New commits: commit aa6d45b6c07701b97f07312ebea4f1536f4cc2d3 Author: Luke Macken lmacken@redhat.com Date: Mon Dec 20 19:06:51 2010 -0500
A ton of documentation improvements...
diff --git a/docs/main/HelloWorld.rst b/docs/main/HelloWorld.rst index 19c058a..7372a1b 100644 --- a/docs/main/HelloWorld.rst +++ b/docs/main/HelloWorld.rst @@ -6,7 +6,11 @@ The goal of this tutorial is to show the simplicity of Moksha's API by creating basic "Hello World" components in one demo.
:Download: https://fedorahosted.org/releases/m/o/moksha/moksha-helloworld.tar.bz2 -:Demo Source: https://fedorahosted.org/moksha/browser/moksha/apps/helloworld +:Browse Source: https://fedorahosted.org/moksha/browser/moksha/apps/helloworld + +.. note:: + + You can easily run this demo by extracting the above tarball, and running ``moksha start`` within it.
The Controller -------------- diff --git a/docs/main/IntegratingWithTG2.rst b/docs/main/IntegratingWithTG2.rst index b7c0d30..5eaff7a 100644 --- a/docs/main/IntegratingWithTG2.rst +++ b/docs/main/IntegratingWithTG2.rst @@ -7,6 +7,7 @@ The best way to learn how to use Moksha within TurboGears2 by example. .. image:: ../_static/jqplotdemo.png
:Running demo: http://moksha.csh.rit.edu/apps/jqplotdemo +:Source code: http://lmacken.fedorapeople.org/JQPlotDemo-0.1dev.tar.gz
We'll take a demo written to show off the :mod:`tw.jquery.jqplot` module for example. This demo shows off the JQPlotWidget, which queries the server every @@ -16,9 +17,6 @@ Porting this app to use Moksha's LiveWidget would allow us to create a much more efficient version of this demo, as it would receive data from the server asynchronously, instead of polling for it.
-The source code for the original JQPlotDemo can be found here: -http://lmacken.fedorapeople.org/JQPlotDemo-0.1dev.tar.gz - Now we'll go over and explain each patch required to utilize Moksha within this TurboGears2 application.
@@ -213,106 +211,99 @@ all of the widgets can share. )
-.. note:: - - The source code for the MokshaJQPlotDemo can be found here: - - http://lmacken.fedorapeople.org/MokshaJQPlotDemo.tar.bz2 - - -At this point, you're all set to run `paster serve development.ini` and enjoy +At this point, you're all set to run ``paster serve development.ini`` and enjoy your shiny new live web app.
-You are now free to go and deploy your application however you please. -However, Moksha can run it for you if you wish... - --------------------------------------------------------------------------------- - -Running your app inside of Moksha ---------------------------------- - -The above example shows how you can easily use Moksha within your existing app. -Moksha also allows lets you run your app inside of it. Moksha is preconfigured -to run in an Apache & mod_wsgi environment, which will handle loading and -mounting your apps within itself. - - -.. warning:: - - If you're running your app inside of Moksha, you must ensure that you - are not running the MokshaMiddleware inside of your app first. This - currently leads to a fun infinite WSGI middleware loop :) - - So if you're creating a new app, don't worry about this, but for the above - example, just remove the `wrap_app=make_moksha_middleware` from your - `jqplotdemo/config/middleware.py` - - -Create your WSGI app -~~~~~~~~~~~~~~~~~~~~ - -If your app is already WSGI-mountable, then don't worry about this. For a TurboGears2 app, it's as easy as: - -.. code-block:: diff - - --- /dev/null - +++ b/jqplotdemo/wsgi.py - @@ -0,0 +1,2 @@ - +from paste.deploy import loadapp - +application = loadapp('config:/etc/moksha/conf.d/jqplotdemo/production.ini') - - -Make a production configuration -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -In production we want to make sure any caches are setup in the right spot. -We base the `production.ini` on our existing `development.ini`, and make a tiny tweak. - -.. code-block:: diff - - --- development.ini - +++ production.in - @@ -23,7 +23,7 @@ - use = egg:JQPlotDemo - lang = en - -cache_dir = %(here)s/data - +cache_dir = /var/cache/moksha/jqplotdemo/data - beaker.session.key = jqplotdemo - -.. code-block:: diff - - --- a/ MANIFEST.in - +++ b/ MANIFEST.in - @@ -2,3 +2,4 @@ recursive-include jqplotdemo/public * - include jqplotdemo/public/favicon.ico - recursive-include jqplotdemo/i18n * - recursive-include jqplotdemo/templates * - +include production.ini - - -Integrate your TG2/WSGI app into Moksha -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -You can plug your WSGI application into Moksha by using the `moksha.wsgiapp` -entry-point. - -.. code-block:: diff - - --- a/ setup.py - +++ b/ setup.py - @@ -47,6 +47,9 @@ setup( - [moksha.stream] - jqplot_stream = jqplotdemo.streams:JQPlotDemoStream - - + [moksha.wsgiapp] - + jqplotdemo = jqplotdemo.wsgi:application - + - [moksha.global] - moksha_socket = moksha.api.widgets:moksha_socket - - -.. seealso:: - - :doc:`PluginEntryPoints` - - +To start the message producing data stream, you will need to run the ``moksha-hub``. + + +.. -------------------------------------------------------------------------------- + + Running your app inside of Moksha + --------------------------------- + + The above example shows how you can easily use Moksha within your existing app. + Moksha also allows lets you run your app inside of it. Moksha is preconfigured + to run in an Apache & mod_wsgi environment, which will handle loading and + mounting your apps within itself. + + + .. warning:: + + If you're running your app inside of Moksha, you must ensure that you + are not running the MokshaMiddleware inside of your app first. This + currently leads to a fun infinite WSGI middleware loop :) + + So if you're creating a new app, don't worry about this, but for the above + example, just remove the `wrap_app=make_moksha_middleware` from your + `jqplotdemo/config/middleware.py` + + + Create your WSGI app + ~~~~~~~~~~~~~~~~~~~~ + + If your app is already WSGI-mountable, then don't worry about this. For a TurboGears2 app, it's as easy as: + + .. code-block:: diff + + --- /dev/null + +++ b/jqplotdemo/wsgi.py + @@ -0,0 +1,2 @@ + +from paste.deploy import loadapp + +application = loadapp('config:/etc/moksha/conf.d/jqplotdemo/production.ini') + + + Make a production configuration + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + In production we want to make sure any caches are setup in the right spot. + We base the `production.ini` on our existing `development.ini`, and make a tiny tweak. + + .. code-block:: diff + + --- development.ini + +++ production.in + @@ -23,7 +23,7 @@ + use = egg:JQPlotDemo + lang = en + -cache_dir = %(here)s/data + +cache_dir = /var/cache/moksha/jqplotdemo/data + beaker.session.key = jqplotdemo + + .. code-block:: diff + + --- a/ MANIFEST.in + +++ b/ MANIFEST.in + @@ -2,3 +2,4 @@ recursive-include jqplotdemo/public * + include jqplotdemo/public/favicon.ico + recursive-include jqplotdemo/i18n * + recursive-include jqplotdemo/templates * + +include production.ini + + + Integrate your TG2/WSGI app into Moksha + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + You can plug your WSGI application into Moksha by using the `moksha.wsgiapp` + entry-point. + + .. code-block:: diff + + --- a/ setup.py + +++ b/ setup.py + @@ -47,6 +47,9 @@ setup( + [moksha.stream] + jqplot_stream = jqplotdemo.streams:JQPlotDemoStream + + + [moksha.wsgiapp] + + jqplotdemo = jqplotdemo.wsgi:application + + + [moksha.global] + moksha_socket = moksha.api.widgets:moksha_socket + + + .. seealso:: + + :doc:`PluginEntryPoints` + + diff --git a/docs/main/MokshaHub.rst b/docs/main/MokshaHub.rst index 1886cb3..1003e71 100644 --- a/docs/main/MokshaHub.rst +++ b/docs/main/MokshaHub.rst @@ -19,15 +19,15 @@ applications to send messages to a given topic. Behind the scenes, the :class:`MokshaHub` will automatically connect up to whatever message brokers are configured, and create a new session. The :meth:`send_message` method will automatically handle encoding your message to -JSON (unless you pass `jsonify=False`), and sending it to the appropriate +JSON (unless you pass ``jsonify=False``), and sending it to the appropriate message broker.
CentralMokshaHub ----------------
-The :class:`CentralMokshaHub` is the primary consumer of all message `topics`. +The :class:`CentralMokshaHub` is the primary consumer of all message ``topics``. It runs outside of the Moksha WSGI application stack, and is automatically -started by the `start-moksha` script (and can be started manually by running `moksha-hub`. +started by the ``start-moksha`` script (and can be started manually by running ``moksha-hub``).
The :class:`CentralMokshaHub` currently handles the following tasks:
diff --git a/docs/main/PluginEntryPoints.rst b/docs/main/PluginEntryPoints.rst index 210e0b0..17b2e1b 100644 --- a/docs/main/PluginEntryPoints.rst +++ b/docs/main/PluginEntryPoints.rst @@ -7,18 +7,24 @@ and store them in ``moksha.apps`` and ``moksha._widgets`` dictionaries. These can then be accessed at any time by any application or widget during any request.
-Mounting a WSGI application ---------------------------- +What is an Entry Point? +-----------------------
-You can mount an existing WSGI application by pointing to it -in the ``setup.py`` on the ``[moksha.wsgiapp]`` entry-point. +Entry points are a Python setuptools/distribute feature that allows packages to +register something under a specific key that other packages can query for. +This is how you make Moksha aware of your widgets/apps/producers/consumers. + +Entry points are defined in your projects ``setup.py`` like so:
.. code-block:: python
- [moksha.wsgiapp] - mywsgiapp = mywsgiapp.wsgiapp:MyWSGIApplication + setup(name='moksha.helloworld', + ... + entry_points=""" + [moksha.widget] + hellowidget = helloworld.widgets:HelloWorldWidget + """
-Your WSGI application will then be accessable via ``/apps/mywsgiapp`` in Moksha.
Mounting a TurboGears application ---------------------------------- @@ -48,6 +54,26 @@ You can plug an existing ToscaWidget into Moksha by adding it to the ``[moksha.w
Your Widget will then be accessable via ``/widgets/mywidget`` in Moksha.
+Mounting a WSGI application +--------------------------- + +You can mount an existing WSGI application by pointing to it +in the ``setup.py`` on the ``[moksha.wsgiapp]`` entry-point. + +.. code-block:: python + + [moksha.wsgiapp] + mywsgiapp = mywsgiapp.wsgiapp:MyWSGIApplication + +Your WSGI application will then be accessable via ``/apps/mywsgiapp`` in Moksha. + +.. warning:: + + At the moment it is not recommened that you mount a TurboGears/Pylons app as + a WSGI application inside of Moksha, since the ``pylons.config`` objects + will conflict. This issue will be addressed in the future. Instead, you can + simply mount a Controller as a ``moksha.application``. + Configuration -------------
diff --git a/docs/main/RPMInstallation.rst b/docs/main/RPMInstallation.rst index 6f004eb..7903970 100644 --- a/docs/main/RPMInstallation.rst +++ b/docs/main/RPMInstallation.rst @@ -2,41 +2,6 @@ Setting up a Moksha RPM & mod_wsgi environment ==============================================
-Setup the TurboGears2/Moksha yum repo -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -At the moment, all of Moksha's dependencies are not all in Fedora. They are -all currently under review, but in the mean time these instructions will run -Moksha within a virtual Python environment, without changing your global -site-packages. - -You can track the progress of getting TurboGears2 into Fedora `here http://fedoraproject.org/wiki/TurboGears2`_. - -To setup Luke Macken's TurboGears2 yum repository, run the following commands -as root, replacing `$DISTRO` with either `fedora-rawhide`, `fedora-11`, -`fedora-10`, or `epel-5`. - -.. code-block:: bash - - cd /etc/yum.repos.d/ - curl -O http://lmacken.fedorapeople.org/rpms/tg2/$DISTRO/tg2.repo - yum -y install TurboGears2 python-tg-devtools - -.. note:: - - It is recommended that you perform a `yum update` after installing - the Moksha/TurboGears2 stack, to ensure that you have the latest - versions of all the dependencies. - -.. note:: - - At the moment the full TurboGears2 stack is not yet fully in - Fedora/EPEL, so you'll have to hook up a third party repository. You - can track the status of TurboGears2 in Fedora here: - - http://fedoraproject.org/wiki/TurboGears2 - - Installing the Moksha Apache/mod_wsgi server ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -60,9 +25,29 @@ Running Moksha Running Orbited ~~~~~~~~~~~~~~~
+Out of the box Orbited comes with a very minimal configuration + +Copy over Moksha's Orbited configuration: + +.. code-block:: bash + + # cp /etc/moksha/orbited.cfg /etc/orbited.cfg + +.. note:: + + Moksha's Orbited configuration enables the MorbidQ STOMP message broker by default, + for ease of development. This can be disabled by commenting out the line ``stomp://:61613`` + and the line under the ``[access]`` section. + +Starting the Orbited daemon + .. code-block:: bash
- $ orbited -c /etc/moksha/orbited.cfg + # service orbited start + +.. note:: + + You can also start orbited by hand by running ``orbited -c /etc/moksha/orbited.cfg``
Running the Moksha Hub @@ -70,7 +55,7 @@ Running the Moksha Hub
.. code-block:: bash
- $ sudo /sbin/service moksha-hub restart + # service moksha-hub start
Install the dependencies and setup your RPM tree @@ -85,9 +70,10 @@ This step is only necessary if you plan on building moksha apps. $ sudo yum-builddep -y moksha
-Watching the Error Log -~~~~~~~~~~~~~~~~~~~~~~ +Watching the logs +~~~~~~~~~~~~~~~~~
.. code-block:: bash
- $ sudo tail -f /var/log/httpd/moksha_error_log + # tail -f /var/log/httpd/moksha_{access,error}_log + # tail -f /var/log/moksha/moksha-hub.log diff --git a/docs/main/Security.rst b/docs/main/Security.rst index af6eb12..0932a74 100644 --- a/docs/main/Security.rst +++ b/docs/main/Security.rst @@ -4,10 +4,17 @@ Security Cross-site Request Forgery Protection -------------------------------------
-Moksha offers CSRF protection for authenticated users by default. +Moksha offers a layer of CSRF protection for authenticated users. For more information on `CSRF`, see the `Wikipedia entry http://en.wikipedia.org/wiki/Cross-site_request_forgery`_
+You can enable/disable this middleware by using the following configuration +option in your ``production.ini`` file: + +.. code-block:: python + + moksha.csrf_protection = True + WSGI Middleware ~~~~~~~~~~~~~~~
diff --git a/docs/main/UsingLiveSocketOutsideOfMoksha.rst b/docs/main/UsingLiveSocketOutsideOfMoksha.rst index 37dc9ed..daa193c 100644 --- a/docs/main/UsingLiveSocketOutsideOfMoksha.rst +++ b/docs/main/UsingLiveSocketOutsideOfMoksha.rst @@ -7,9 +7,12 @@ have to learn Python or TurboGears? Thankfully, Moksha allows you to leverage it's realtime pipes on any existing web page without having to write a line of Python code.
-Add code snippet to your web page -Configure your message broker -Start Moksha +This means that you can have your web site listen to topics from your message +broker, and run javascript when new messages arrive. + +All you need to do is add a single ``<script>`` tag to your web site that +specifies the topic that you wish to listen to, and the javascript function +that should be called with each new message as they arrive.
.. code-block:: html
@@ -28,7 +31,7 @@ Start Moksha <script type="text/javascript" src="http://localhost:8080/livesocket?topic=helloworld&callback=consume_message"></script> </html>
-Caveats -------- +.. note::
-Must be under the same domain name. + In order for the live sockets to work properly, Moksha (specifically Orbited) must be running + under the same domain as your web site. diff --git a/docs/main/VirtualenvInstallation.rst b/docs/main/VirtualenvInstallation.rst index 7d9d282..23b9fdb 100644 --- a/docs/main/VirtualenvInstallation.rst +++ b/docs/main/VirtualenvInstallation.rst @@ -3,7 +3,7 @@ Virtualenv installation
This guide will help quickly get you up and running with a local copy of Moksha. It will run the Moksha WSGI application using the Paste threaded http -server, a single orbited daemon with an embeded MorbidQ stomp message broker, +server, a single Orbited socket-proxy daemon with an embeded MorbidQ stomp message broker, SQLite SQLAlchemy and Feed databases, and an in-memory cache. This setup is meant to be dead-simple to get up and running, and is not designed for production deployments. @@ -16,11 +16,19 @@ Installing the necessary dependencies
You'll need the `virtualenv http://pypi.python.org/pypi/virtualenv`_ package.
+For Fedora/Red Hat/CentOS based environments: + .. code-block:: bash
# yum -y install python-virtualenv gcc openssl-devel # yum-builddep -y python-lxml pyOpenSSL python-sqlite2
+On Ubuntu/Debian: + +.. code-block:: bash + + # apt-get install git python-dev python-virtualenv +
Getting the code ~~~~~~~~~~~~~~~~