/docs/shabti_templates/shabti_moinmoin.rst

  1.. _shabti_moinmoin:
  2
  3|today|
  4
  5.. _shabti-moinmoin:
  6
  7**shabti_moinmoin** -- Shabti with integrated MoinMoin wiki
  8===========================================================
  9
 10
 11.. rubric :: This template is a basic :ref:`shabti_auth <shabti-auth>` setup to which has been added a controller and a corresponding configuration that integrates the `MoinMoin <http://moinmo.in/>`_ wikiengine. MoinMoin is an "advanced, easy to use and extensible WikiEngine with a large community of users". It provides a WSGI callable app and can be configured to use the Shabti basic auth'n'auth, so offering some nice low-hanging fruit in the form of an elementary "single sign-on" facility.
 12
 13About MoinMoin
 14--------------
 15
 16Because MoinMoin is a full-fledged application, it is amongst the few Python packages that are not easy_install-able. To install MoinMoin one must first download a tar.gz distro from the `MoinMoin Download page <http://moinmo.in/MoinMoinDownload>`_ and install it (there's `help <http://moinmo.in/HelpOnInstalling/BasicInstallation>`_), most preferably within a `virtualenv <http://pypi.python.org/pypi/virtualenv>`_ space --- and from here on, the narrative assumes that space.
 17
 18MoinMoin is a file-based wikiengine and is capable of running a "farm" of several otherwise-independent wikis. A single folder of resources (aka "moindir") is installed in a shared area. The copying of this folder and its contents (server stub code, styling themes, plugins, underlay pages, etc.) forms the basis for each new wiki instance.
 19
 20
 21Within each wiki instance's copied ``<moindir>``, user-generated wiki pages are stored as versions in the "<moindir>/data/pages" folder, each one in a subdirectory named for the page, i.e. the content and history of the page "MyWikiPage" is stored in the folder ``<moindir>/data/pages/MyWikiPage/``.
 22
 23Using this approach, MoinMoin installations can be configured to use shared or separate resources or a mix of both.
 24
 25In an ideal world, this Shabti template would simply re-use the installed MoinMoin resources. However, I haven't been able to make that work. Instead, two trivial copying tasks are required to be performed. 
 26
 27Using the template
 28------------------
 29
 30After successfully installing Shabti, additional paster templates will be available. Simply create a Shabti-configured project by specifying that paster should use the shabti_moinmoin template:
 31
 32.. code-block :: bash
 33
 34    $ paster create -t shabti_moinmoin myproj
 35
 36These are the option dialogue choices appropriate for the Shabti auth shabti_moinmoin template --- which uses mako templates and requires SQLAlchemy  ...
 37
 38.. code-block :: bash
 39
 40    (mako/genshi/jinja/etc: Template language) ['mako']: 
 41    (True/False: Include SQLAlchemy 0.4 configuration) [False]: True
 42    (True/False: Setup default appropriate for Google App Engine) [False]: 
 43
 44Once the project has been created, navigate to the project directory.
 45
 46The next step is to initialise the relational store by running the project setup script which will create an Admin user and corresponding Groups and Permissions.
 47
 48.. code-block :: bash
 49
 50    $ paster setup-app development.ini
 51
 52The next (optional) step after initialising the relational store is to run the tests.
 53
 54.. code-block :: bash
 55    
 56    $ nosetests myproj/tests
 57    
 58MoinMoin's warnings about logging configuration are ignorable.
 59
 60Copying and pasting resources
 61-----------------------------
 62
 63On creating a Pylons project with the ``shabti_moinmoin`` template, a ``<moindir>`` folder is prepared in ``MYPROJ/data/moin``, pre-populated with the completed configuration, a starter page, a SysAdmin account, a theme and a couple of useful macros (e.g. Import HTML).
 64
 65What's missing from this picture are two things: 
 66
 671. the ``<moindir>/underlay`` folder which needs to be copied and pasted to create ``MYPROJ/data/moin/underlay`` and 
 68
 692. the resource files in ``<moindir>/htdocs/*`` (CSS files, etc.) need to be copied into the directory ``MYPROJ/MYPROJ/public/moin_static181/`` alongside the pre-existing ``plsavez`` theme folder.
 70
 71
 72Template details
 73----------------
 74
 75This template is an extension of the standard :ref:`shabti_auth <shabti-auth>` template that uses Elixir to create a basic identity model in SQL store. A ``login`` controller performs basic sign in and sign out facilities, mediated by session storage and temporary cookies. 
 76
 77
 78A system of modular authentication has been developed for MoinMoin and the value of the ``auth`` configuration variable is used to set up a list of authenticators that are processed in the given order.
 79
 80When an external user database is used, recreating all the users in moin is undesirable. For this case the authenticator objects which support user profile creation/updating have a parameter ``autocreate`` which, if set to ``True``, causes a new user profile to be created/updated automatically when a (new) user has passed authentication.
 81
 82By defining and adding a simple external authentication, MoinMoin can use the shabti_auth identity stored in the session. The added code is in the MoinMoin configuration file ``<moindir>/config/wikiconfig.py``
 83
 84.. code-block:: python
 85
 86    from MoinMoin.auth import BaseAuth
 87    from MoinMoin.config.multiconfig import DefaultConfig
 88    from myproj import model
 89    import pylons
 90
 91    class PylonsAuth(BaseAuth):
 92        """ handle login from moin login form """
 93        def __init__(self, verbose=False):
 94            BaseAuth.__init__(self)
 95            self.verbose = verbose
 96    
 97        name = 'pylons_auth'
 98        logout_possible = False
 99    
100        def request(self, req, user_obj, **kw):
101        
102            user = None
103            try_next = True # if True, moin tries the next auth method
104            auth_user_id = req.env.get(
105                        'beaker.session', {}).get('AUTH_USER_ID', 0)
106            if auth_user_id:
107                user_obj = model.Session.query(model.User).get(auth_user_id)
108                auth_username = user_obj.firstname + user_obj.lastname
109                from MoinMoin.user import User as MoinUser
110                # giving auth_username to User constructor 
111                # means that authentication has already been done.
112                user = MoinUser(req, name=auth_username, 
113                            auth_username=auth_username, 
114                            auth_method='pylons_auth')        
115            changed = False
116            if user:
117                user.create_or_update(changed)
118            if user and user.valid: # did we succeed making up a valid user?
119                try_next = False # stop processing auth method list
120            return user, try_next
121    
122    class Config(DefaultConfig):
123
124        #from MoinMoin.auth import moin_cookie, http
125        # # first try the external_cookie, then http basic auth, then
126        # # the usual moin_cookie
127        # auth = [external_cookie, http, moin_cookie]
128        auth = [PylonsAuth()]
129
130
131Note, an alternate auth solution based on external cookies is also available ("external_cookie", above). Detailed instructions on authenticating by `external cookie <http://moinmo.in/HelpOnAuthentication/ExternalCookie>`_ are on the MoinMoin web site as well as more general information on `authentication in MoinMoin <http://moinmo.in/HelpOnAuthentication>`_.
132
133Running the generated app
134-------------------------
135
136After the graph has been initialised, start the Pylons web app with:
137
138.. code-block :: bash
139
140    $ paster serve --reload development.ini
141
142The Shabti MoinMoin template's variant on the standard Pylons welcome screen is browsable at at ``http://localhost:5000/`` ...
143
144Welcome screen
145^^^^^^^^^^^^^^
146
147.. image :: images/shabti_moinmoin_welcome.jpg
148   :align: center
149
150Wiki page, anonymous user
151^^^^^^^^^^^^^^^^^^^^^^^^^^
152The ``MoinMoin`` link to the wiki, shown above on the welcome screen above, leads to the default page of the wiki:
153
154.. code-block:: text
155    
156    http://localhost:5000/wiki/ShabtiWiki
157
158as presented to an anonymous user:
159
160.. image :: images/shabti_moinmoin_wikipage.jpg
161   :align: center
162
163To sign in to the site, go to:
164
165.. code-block:: text
166
167    http://localhost:5000/login/signin
168    
169and login with user = admin, password = admin
170
171Wiki page, signed-in user
172^^^^^^^^^^^^^^^^^^^^^^^^^^
173
174Then navigate back to the wiki page, which will now include the standard editing bar and user-specific account and preference links (top right):
175
176.. image :: images/shabti_moinmoin_wikipage_signedin.jpg
177   :align: center
178
179Wiki page, editing
180^^^^^^^^^^^^^^^^^^
181
182After clicking on the ``Edit`` tab:
183
184.. image :: images/shabti_moinmoin_wikipage_editing.jpg
185   :align: center
186
187Wiki page, edited
188^^^^^^^^^^^^^^^^^
189
190After saving:
191
192.. image :: images/shabti_moinmoin_wikipage_edited.jpg
193   :align: center
194
195
196Wiki page, preferences
197^^^^^^^^^^^^^^^^^^^^^^
198
199There's more to single sign-on than just ``username`` and ``password``. Whilst MoinMoin can make use of external authentication to map a shabti_auth identity to a MoinMoin user, that is the limit of the interconnectivity.
200
201For example, email setting in this page will be completely unconnected to the email setting for the corresponding separate :ref:`shabti_auth <shabti-auth>` identity record held in relational store.
202
203So, further interoperability is rather more than just "an exercise for the reader".
204
205.. image :: images/shabti_moinmoin_editing_preferences.jpg
206   :align: center
207
208Wiki page, attachment
209^^^^^^^^^^^^^^^^^^^^^^
210
211In the past, some code adjustments were necessary in order to get attachments to work in MoinMoin. This is no longer the case, attachments simply work "out of the box" ...
212
213.. image :: images/shabti_moinmoin_attachment.jpg
214   :align: center
215
216Xapian search configuration settings
217^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
218
219In case you were wondering ...
220
221.. code-block:: python
222
223    xapian_search = True
224    xapian_index_dir = '<moindir>/data/cache/xapian'
225    search_results_per_page = 5
226    show_timings = 1
227
228
229:author: Graham Higgins <gjh@bel-epa.com>
230
231|today|
232
233
234
235
236
237
238
239