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 

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

    16 (:ref:`CubicWebInstallation`). 

    17 

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

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

    20 

    21    cubicweb-ctl newgapp <myapp>

    22 

    23 This will create a directory containing ::

    24  

    25    `-- myapp/

    26        |-- app.conf

    27        |-- app.yaml

    28        |-- bin/

    29        |    `-- laxctl

    30        |-- boostrap_cubes

    31        |-- cubes/

    32        |    |-- addressbook/

    33        |    ..

    34        |    |-- comment

    35        |    ..

    36        |    `-- zone/

    37        |-- cubicweb/

    38        |-- custom.py

    39        |-- cw-cubes/

    40        |-- dateutil/

    41        |-- docutils/

    42        |-- fckeditor/

    43        |-- i18n/

    44        |-- index.yaml

    45        |-- loader.py

    46        |-- logilab/

    47        |-- main.py

    48        |-- migration.py

    49        |-- mx/

    50        |-- roman.py

    51        |-- rql/

    52        |-- schema.py

    53        |-- simplejson/

    54        |-- tools/

    55        |-- views.py

    56        |-- vobject/

    57        |-- yams/

    58        `-- yapps/

    59 

    60   

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

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

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

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

    65 

    66 The main directories that you should know about are:

    67 

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

    69     those cubes you will list them in the variable 

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

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

    72 

    73 Dependencies

    74 ------------

    75 

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

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

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

    79     and using python-yaml:

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

    81   - gettext

    82 

    83 Setup

    84 -----

    85 

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

    87 as an application directory and do as follows.

    88 

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

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

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

    92 `CubicWeb`.

    93 

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

    95 

    96    $ python myapp/bin/laxctl --help

    97 

    98 

    99 Generating translation files

   100 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

   101 

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

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

   104 or the ``laxctl`` command ::

   105 

   106   $ python myapp/bin/laxctl i18nupdate 

   107   $ python myapp/bin/laxctl i18ncompile 

   108 

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

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

   111 

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

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

   114    Otherwise, please skip it.

   115 

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

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

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

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

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

   121 

   122 Generating the data directory

   123 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

   124 

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

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

   127 

   128   $ python myapp/bin/laxctl populatedata

   129 

   130 Generating the schema diagram

   131 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

   132 

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

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

   135 be generated from the command line::

   136 

   137   $ python myapp/bin/laxctl genschema

   138 

   139 Application configuration

   140 -------------------------

   141 

   142 Authentication

   143 ~~~~~~~~~~~~~~

   144 

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

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

   147 

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

   149  

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

   151   use-google-auth=no

   152  

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

   154 

   155   - url: .*

   156   script: main.py

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

   158   # google authentication service

   159   #login: required

   160 

   161 

   162 

   163 

   164 Quickstart : launch the application

   165 -----------------------------------

   166 

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

   168 `GoogleAppEngineLauncher`.

   169 

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

   171 

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

   173 

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

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

   176 the application and continue the installation.

   177 

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

   179 

   180 Initialize the datastore

   181 ~~~~~~~~~~~~~~~~~~~~~~~~

   182 

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

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

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

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

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

   188 

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

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

   191 

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

   193 in order to handle datastore administration requests.

   194 

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

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

   197 

   198 

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

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

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

   202 

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

   204  

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

   206 

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

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

   209    will look like :

   210    --cookie='__session=2b45d1a9c36c03d2a30cedb04bc37b6d'

   211 

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

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

   214 as a normal user.

   215 

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

   217 http://localhost:8080/

   218 

   219