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 (:ref:`CubicWebInstallation`). 

    19 

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

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

    22 

    23    cubicweb-ctl newgapp <myapp>

    24 

    25 This will create a directory containing ::

    26  

    27    `-- myapp/

    28        |-- app.conf

    29        |-- app.yaml

    30        |-- bin/

    31        |    `-- laxctl

    32        |-- boostrap_cubes

    33        |-- cubes/

    34        |    |-- addressbook/

    35        |    ..

    36        |    |-- comment

    37        |    ..

    38        |    `-- zone/

    39        |-- cubicweb/

    40        |-- custom.py

    41        |-- cw-cubes/

    42        |-- dateutil/

    43        |-- docutils/

    44        |-- fckeditor/

    45        |-- i18n/

    46        |-- index.yaml

    47        |-- loader.py

    48        |-- logilab/

    49        |-- main.py

    50        |-- migration.py

    51        |-- mx/

    52        |-- roman.py

    53        |-- rql/

    54        |-- schema.py

    55        |-- simplejson/

    56        |-- tools/

    57        |-- views.py

    58        |-- vobject/

    59        |-- yams/

    60        `-- yapps/

    61 

    62   

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

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

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

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

    67 

    68 The main directories that you should know about are:

    69 

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

    71     those cubes you will list them in the variable 

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

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

    74 

    75 Dependencies

    76 ------------

    77 

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

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

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

    81     and using python-yaml:

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

    83   - gettext

    84 

    85 Setup

    86 -----

    87 

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

    89 as an application directory and do as follows.

    90 

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

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

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

    94 `CubicWeb`.

    95 

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

    97 

    98    $ python myapp/bin/laxctl --help

    99 

   100 

   101 Generating translation files

   102 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

   103 

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

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

   106 or the ``laxctl`` command ::

   107 

   108   $ python myapp/bin/laxctl i18nupdate 

   109   $ python myapp/bin/laxctl i18ncompile 

   110 

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

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

   113 

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

   115    only if your application is using cubes from ginco-apps.

   116    Otherwise, please skip it.

   117 

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

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

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

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

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

   123 

   124 Generating the data directory

   125 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

   126 

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

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

   129 

   130   $ python myapp/bin/laxctl populatedata

   131 

   132 Generating the schema diagram

   133 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

   134 

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

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

   137 be generated from the command line::

   138 

   139   $ python myapp/bin/laxctl genschema

   140 

   141 Application configuration

   142 -------------------------

   143 

   144 Authentication

   145 ~~~~~~~~~~~~~~

   146 

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

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

   149 

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

   151  

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

   153   use-google-auth=no

   154  

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

   156 

   157   - url: .*

   158   script: main.py

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

   160   # google authentication service

   161   #login: required

   162 

   163 

   164 

   165 

   166 Quickstart : launch the application

   167 -----------------------------------

   168 

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

   170 `GoogleAppEngineLauncher`.

   171 

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

   173 

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

   175 

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

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

   178 the application and continue the installation.

   179 

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

   181 

   182 Initialize the datastore

   183 ~~~~~~~~~~~~~~~~~~~~~~~~

   184 

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

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

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

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

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

   190 

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

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

   193 

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

   195 in order to handle datastore administration requests.

   196 

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

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

   199 

   200 

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

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

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

   204 

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

   206  

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

   208 

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

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

   211    will look like :

   212    --cookie='__session=2b45d1a9c36c03d2a30cedb04bc37b6d'

   213 

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

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

   216 as a normal user.

   217 

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

   219 http://localhost:8080/

   220 

   221