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

     2 

     3 .. _GoogleAppEngineSource:

     4 

     5 CubicWeb in Google AppEngine

     6 ============================

     7 

     8 What is  `Google AppEngine` ?

     9 ------------------------------

    10 

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

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

    13 support a specific Python web framework and that all

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

    15 

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

    17 datastore.

    18 

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

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

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

    22 

    23 Download the source

    24 -------------------

    25 

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

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

    28 

    29 

    30 Please follow instructions on how to install *CubicWeb* framework

    31 (:ref:`SetUpEnv`).

    32 

    33 Installation

    34 ------------

    35 

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

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

    38 

    39    cubicweb-ctl newgapp <myapp>

    40 

    41 This will create a directory containing ::

    42 

    43    `-- myapp/

    44        |-- app.conf

    45        |-- app.yaml

    46        |-- bin/

    47        |    `-- laxctl

    48        |-- boostrap_cubes

    49        |-- cubes/

    50        |    |-- addressbook/

    51        |    ..

    52        |    |-- comment

    53        |    ..

    54        |    `-- zone/

    55        |-- cubicweb/

    56        |-- custom.py

    57        |-- cw-cubes/

    58        |-- dateutil/

    59        |-- docutils/

    60        |-- fckeditor/

    61        |-- i18n/

    62        |-- index.yaml

    63        |-- loader.py

    64        |-- logilab/

    65        |-- main.py

    66        |-- migration.py

    67        |-- mx/

    68        |-- roman.py

    69        |-- rql/

    70        |-- schema.py

    71        |-- simplejson/

    72        |-- tools/

    73        |-- views.py

    74        |-- vobject/

    75        |-- yams/

    76        `-- yapps/

    77 

    78 

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

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

    81 *CubicWeb* framework and its third-party libraries. You will notice that

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

    83 

    84 The main directories that you should know about are:

    85 

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

    87     those cubes you will list them in the variable

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

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

    90 

    91 Dependencies

    92 ~~~~~~~~~~~~

    93 

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

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

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

    97     and using python-yaml:

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

    99   - gettext

   100 

   101 Setup

   102 ~~~~~

   103 

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

   105 as an application directory and do as follows.

   106 

   107 This installation directory provides a configuration for an instance of *CubicWeb*

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

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

   110 *CubicWeb*.

   111 

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

   113 

   114    $ python myapp/bin/laxctl --help

   115 

   116 

   117 Generating translation files

   118 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

   119 

   120 *CubicWeb* is fully internationalized. Translation catalogs are found in

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

   122 or the ``laxctl`` command ::

   123 

   124   $ python myapp/bin/laxctl i18ncube

   125   $ python myapp/bin/laxctl i18ninstance

   126 

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

   128 'cubicweb'". They disappear after the first run of i18ninstance.

   129 

   130 .. note:: The command  myapp/bin/laxctl i18ncube needs to be executed

   131    only if your instance is using cubes from cubicweb-apps.

   132    Otherwise, please skip it.

   133 

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

   135 would recommand you to use ``self._cw._("msgId")`` in your code to flag new

   136 message id to add to the catalog, where ``_`` refers to xgettext that is used to

   137 collect new strings to translate.  While running ``laxctl i18ncube``, new string

   138 will be added to the catalogs.

   139 

   140 Generating the data directory

   141 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

   142 

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

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

   145 

   146   $ python myapp/bin/laxctl populatedata

   147 

   148 Generating the schema diagram

   149 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

   150 

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

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

   153 be generated from the command line::

   154 

   155   $ python myapp/bin/laxctl genschema

   156 

   157 Instance configuration

   158 -------------------------

   159 

   160 Authentication

   161 ~~~~~~~~~~~~~~

   162 

   163 You have the option of using or not google authentication for your instance.

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

   165 

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

   167  

   168   # does this instance rely on google authentication service or not.

   169   use-google-auth=no

   170 

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

   172 

   173   - url: .*

   174   script: main.py

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

   176   # google authentication service

   177   #login: required

   178 

   179 

   180 

   181 

   182 Quickstart : launch the instance

   183 -----------------------------------

   184 

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

   186 `GoogleAppEngineLauncher`.

   187 

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

   189 

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

   191 

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

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

   194 the instance and continue the installation.

   195 

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

   197 

   198 Initialize the datastore

   199 ~~~~~~~~~~~~~~~~~~~~~~~~

   200 

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

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

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

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

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

   206 

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

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

   209 

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

   211 in order to handle datastore administration requests.

   212 

   213 .. image:: ../images/lax-book_02-cookie-values_en.png

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

   215 

   216 

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

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

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

   220 

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

   222 

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

   224 

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

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

   227    will look like :

   228    --cookie='__session=2b45d1a9c36c03d2a30cedb04bc37b6d'

   229 

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

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

   232 as a normal user.

   233 

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

   235 http://localhost:8080/