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

     2 

     3 .. _installation:

     4 

     5 Installation

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

     7 

     8 Download the source

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

    10 

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

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

    13 

    14 - `LAX` is available as an extension of `CubicWeb` under the GPLv2

    15   license which can be downloaded from : http://cubicweb.org/

    16 

    17 Please follow instructions on how to install `CubicWeb` framework. 

    18 

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

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

    21 

    22    cubicweb-ctl newgapp <myapp>

    23 

    24 This will create a directory containing ::

    25  

    26    `-- myapp/

    27        |-- app.conf

    28        |-- app.yaml

    29        |-- bin/

    30        |    `-- laxctl

    31        |-- boostrap_cubes

    32        |-- cubes/

    33        |    |-- addressbook/

    34        |    ..

    35        |    |-- comment

    36        |    ..

    37        |    `-- zone/

    38        |-- cubicweb/

    39        |-- custom.py

    40        |-- cw-cubes/

    41        |-- dateutil/

    42        |-- docutils/

    43        |-- fckeditor/

    44        |-- i18n/

    45        |-- index.yaml

    46        |-- loader.py

    47        |-- logilab/

    48        |-- main.py

    49        |-- migration.py

    50        |-- mx/

    51        |-- roman.py

    52        |-- rql/

    53        |-- schema.py

    54        |-- simplejson/

    55        |-- tools/

    56        |-- views.py

    57        |-- vobject/

    58        |-- yams/

    59        `-- yapps/

    60 

    61   

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

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

    64 `LAX` framework and its third-party libraries. You will notice that 

    65 the directory ``cubes`` is a library of reusable components.

    66 

    67 The main directories that you should know about are:

    68 

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

    70     those components you will list them in the variable 

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

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

    73 

    74 Dependencies

    75 ------------

    76 

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

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

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

    80     and using python-yaml:

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

    82   - gettext

    83 

    84 Setup

    85 -----

    86 

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

    88 as an application directory and do as follows.

    89 

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

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

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

    93 `CubicWeb`.

    94 

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

    96 

    97    $ python myapp/bin/laxctl --help

    98 

    99 

   100 Generating translation files

   101 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

   102 

   103 `LAX` is fully internationalized. Translation catalogs are found in

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

   105 or the ``laxctl`` command ::

   106 

   107   $ python myapp/bin/laxctl i18nupdate 

   108   $ python myapp/bin/laxctl i18ncompile 

   109 

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

   111 'erudi'". They disappear after the first run of i18ncompile.

   112 

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

   114    only if your application is using components from ginco-apps.

   115    Otherwise, please skip it.

   116 

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

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

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

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

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

   122 

   123 Generating the data directory

   124 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

   125 

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

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

   128 

   129   $ python myapp/bin/laxctl populatedata

   130 

   131 Generating the schema diagram

   132 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

   133 

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

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

   136 be generated from the command line::

   137 

   138   $ python myapp/bin/laxctl genschema

   139 

   140 Application configuration

   141 -------------------------

   142 

   143 Authentication

   144 ~~~~~~~~~~~~~~

   145 

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

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

   148 

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

   150  

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

   152   use-google-auth=no

   153  

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

   155 

   156   - url: .*

   157   script: main.py

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

   159   # google authentication service

   160   #login: required

   161 

   162 

   163 

   164 

   165 Quickstart : launch the application

   166 -----------------------------------

   167 

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

   169 `GoogleAppEngineLauncher`.

   170 

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

   172 

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

   174 

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

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

   177 the application and continue the installation.

   178 

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

   180 

   181 Initialize the datastore

   182 ~~~~~~~~~~~~~~~~~~~~~~~~

   183 

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

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

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

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

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

   189 

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

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

   192 

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

   194 in order to handle datastore administration requests.

   195 

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

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

   198 

   199 

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

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

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

   203 

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

   205  

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

   207 

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

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

   210    will look like :

   211    --cookie='__session=2b45d1a9c36c03d2a30cedb04bc37b6d'

   212 

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

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

   215 as a normal user.

   216 

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

   218 http://localhost:8080/

   219 

   220