1 .. -*- coding: utf-8 -*-

     2 

     3 CubicWeb in Google AppEngine

     4 ============================

     5 

     6 What is  `Google AppEngine` ?

     7 ------------------------------

     8 

     9 `Google AppEngine`_ is provided with a partial port of the `Django`

    10 framework, but Google stated at Google IO 2008 that it would not

    11 support a specific Python web framework and that all

    12 community-supported frameworks would be more than welcome [1]_. 

    13 

    14 Therefore `Logilab`_ ported `CubicWeb` to run on top of `Google AppEngine`'s

    15 datastore.

    16 

    17 .. _`Google AppEngine`: http://code.google.com/appengine/docs/whatisgoogleappengine.html

    18 .. _Logilab: http://www.logilab.fr/

    19 .. [1] for more on this matter, read our blog at http://www.logilab.org/blogentry/5216

    20 

    21 Download the source

    22 -------------------

    23 

    24 - The `Google AppEngine SDK` can be downloaded from:

    25   http://code.google.com/appengine/downloads.html

    26 

    27 

    28 Please follow instructions on how to install `CubicWeb` framework

    29 (:ref:`CubicWebInstallation`). 

    30 

    31 Installation

    32 ------------

    33 

    34 Once ``cubicweb-ctl`` is installed, then you can create a Google

    35 App Engine extension of our framework by running the command ::

    36 

    37    cubicweb-ctl newgapp <myapp>

    38 

    39 This will create a directory containing ::

    40  

    41    `-- myapp/

    42        |-- app.conf

    43        |-- app.yaml

    44        |-- bin/

    45        |    `-- laxctl

    46        |-- boostrap_cubes

    47        |-- cubes/

    48        |    |-- addressbook/

    49        |    ..

    50        |    |-- comment

    51        |    ..

    52        |    `-- zone/

    53        |-- cubicweb/

    54        |-- custom.py

    55        |-- cw-cubes/

    56        |-- dateutil/

    57        |-- docutils/

    58        |-- fckeditor/

    59        |-- i18n/

    60        |-- index.yaml

    61        |-- loader.py

    62        |-- logilab/

    63        |-- main.py

    64        |-- migration.py

    65        |-- mx/

    66        |-- roman.py

    67        |-- rql/

    68        |-- schema.py

    69        |-- simplejson/

    70        |-- tools/

    71        |-- views.py

    72        |-- vobject/

    73        |-- yams/

    74        `-- yapps/

    75 

    76   

    77 This skeleton directory is a working `AppEngine` application. You will

    78 recognize the files ``app.yaml`` and ``main.py``. All the rest is the

    79 `CubicWeb` framework and its third-party libraries. You will notice that 

    80 the directory ``cubes`` is a library of reusable cubes.

    81 

    82 The main directories that you should know about are:

    83 

    84   - ``cubes`` : this is a library of reusable yams cubes. To use 

    85     those cubes you will list them in the variable 

    86     `included-yams-cubes` of ``app.conf``. See also :ref:`cubes`. 

    87   - [WHICH OTHER ONES SHOULD BE LISTED HERE?]

    88 

    89 Dependencies

    90 ~~~~~~~~~~~~

    91 

    92 Before starting anything, please make sure the following packages are installed:

    93   - yaml : by default google appengine is providing yaml; make sure you can

    94     import it. We recommend you create a symbolic link yaml instead of installing 

    95     and using python-yaml:

    96     yaml -> full/path/to/google_appengine/lib/yaml/lib/yaml/

    97   - gettext

    98 

    99 Setup

   100 ~~~~~

   101 

   102 Once you executed ``cubicweb-ctl newgapp <myapp>``, you can use that ``myapp/`` 

   103 as an application directory and do as follows.

   104 

   105 This installation directory provides a configuration for an instance of `CubicWeb`

   106 ported for Google App Engine. It is installed with its own command ``laxctl`` 

   107 which is a port of the command tool ``cubicweb-ctl`` originally developped for 

   108 `CubicWeb`.

   109 

   110 You can have the details of available commands by running ::

   111 

   112    $ python myapp/bin/laxctl --help

   113 

   114 

   115 Generating translation files

   116 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

   117 

   118 `CubicWeb` is fully internationalized. Translation catalogs are found in

   119 ``myapp/i18n``. To compile the translation files, use the `gettext` tools

   120 or the ``laxctl`` command ::

   121 

   122   $ python myapp/bin/laxctl i18nupdate 

   123   $ python myapp/bin/laxctl i18ncompile 

   124 

   125 Ignore the errors that print "No translation file found for domain

   126 'cubicweb'". They disappear after the first run of i18ncompile.

   127 

   128 .. note:: The command  myapp/bin/laxctl i18nupdate needs to be executed

   129    only if your application is using cubes from cubicweb-apps.

   130    Otherwise, please skip it.

   131 

   132 You will never need to add new entries in the translation catalog. Instead we would

   133 recommand you to use ``self.req._("msgId")`` in your application code

   134 to flag new message id to add to the catalog, where ``_`` refers to

   135 xgettext that is used to collect new strings to translate. 

   136 While running ``laxctl i18nupdate``, new string will be added to the catalogs.

   137 

   138 Generating the data directory

   139 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

   140 

   141 In order to generate the ``myapp/data`` directory that holds the static

   142 files like stylesheets and icons, you need to run the command::

   143 

   144   $ python myapp/bin/laxctl populatedata

   145 

   146 Generating the schema diagram

   147 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

   148 

   149 There is a view named ``schema`` that displays a diagram of the

   150 entity-relationship graph defined by the schema. This diagram has to

   151 be generated from the command line::

   152 

   153   $ python myapp/bin/laxctl genschema

   154 

   155 Application configuration

   156 -------------------------

   157 

   158 Authentication

   159 ~~~~~~~~~~~~~~

   160 

   161 You have the option of using or not google authentication for your application.

   162 This has to be define in ``app.conf`` and ``app.yaml``.

   163 

   164 In ``app.conf`` modify the following variable::

   165  

   166   # does this application rely on google authentication service or not.

   167   use-google-auth=no

   168  

   169 In ``app.yaml`` comment the `login: required` set by default in the handler::

   170 

   171   - url: .*

   172   script: main.py

   173   # comment the line below to allow anonymous access or if you don't want to use

   174   # google authentication service

   175   #login: required

   176 

   177 

   178 

   179 

   180 Quickstart : launch the application

   181 -----------------------------------

   182 

   183 On Mac OS X platforms, drag that directory on the

   184 `GoogleAppEngineLauncher`.

   185 

   186 On Unix and Windows platforms, run it with the dev_appserver::

   187 

   188   $ python /path/to/google_appengine/dev_appserver.py /path/to/myapp/

   189 

   190 Once the local server is started, visit `http://MYAPP_URL/_load <http://localhost:8080/_load>`_ and sign in as administrator. 

   191 This will initialize the repository and enable you to log in into 

   192 the application and continue the installation.

   193 

   194 You should be redirected to a page displaying a message `content initialized`.

   195 

   196 Initialize the datastore

   197 ~~~~~~~~~~~~~~~~~~~~~~~~

   198 

   199 You, then, want to visit  `http://MYAPP_URL/?vid=authinfo <http://localhost:8080/?vid=authinfo>`_ .

   200 If you selected not  to use google authentication, you will be prompted to a 

   201 login form where you should initialize the administrator login (recommended

   202 to use admin/admin at first). You will then be redirected to a page providing

   203 you the value to provide to ``./bin/laxctl --cookie``.

   204 

   205 If you choosed to use google authentication, then you will not need to set up

   206 and administrator login but you will get the cookie value as well.

   207 

   208 This cookie values needs to be provided to ``laxctl`` commands

   209 in order to handle datastore administration requests.

   210 

   211 .. image:: ../images/lax-book.02-cookie-values.en.png

   212    :alt: displaying the detailed view of the cookie values returned

   213 

   214 

   215 .. note:: In case you are not redirected to a page providing the 

   216    option --cookie value, please visit one more time  

   217    `http://MYAPP_URL/?vid=authinfo <http://localhost:8080/?vid=authinfo>`_ .

   218 

   219 Once, you have this value, then return to the shell and execute ::

   220  

   221   $ python myapp/bin/laxctl db-init --cookie='dev_appserver_login=test@example.com:True; __session=7bbe973a6705bc5773a640f8cf4326cc' localhost:8080

   222 

   223 .. note:: In the case you are not using google authentication, the value returned

   224    by `http://MYAPP_URL/?vid=authinfo <http://localhost:8080/?vid=authinfo>`_ 

   225    will look like :

   226    --cookie='__session=2b45d1a9c36c03d2a30cedb04bc37b6d'

   227 

   228 Log out by clicking in the menu at the top right corner

   229 and restart browsing from `http://MYAPP_URL/ <http://localhost:8080>`_ 

   230 as a normal user.

   231 

   232 Unless you did something to change it, http://MYAPP_URL should be

   233 http://localhost:8080/