doc/book/en/B2052-install.en.txt
changeset 292 2d9e83c34b23
parent 261 20d5eae54d57
child 306 1ed1da008e50
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/book/en/B2052-install.en.txt	Tue Dec 23 13:50:56 2008 -0800
@@ -0,0 +1,221 @@
+.. -*- coding: utf-8 -*-
+
+.. _installation:
+
+Installation
+============
+
+Download the source
+-------------------
+
+- The `Google AppEngine SDK` can be downloaded from:
+  http://code.google.com/appengine/downloads.html
+
+- `LAX` is available as an extension of `CubicWeb` under the GPLv2
+  license which can be downloaded from : http://cubicweb.org/
+
+Please follow instructions on how to install `CubicWeb` framework
+(:ref:`CubicWebInstallation`). 
+
+Once ``cubicweb-ctl`` is installed, then you can create a Google
+App Engine extension of our framework by running the command ::
+
+   cubicweb-ctl newgapp <myapp>
+
+This will create a directory containing ::
+ 
+   `-- myapp/
+       |-- app.conf
+       |-- app.yaml
+       |-- bin/
+       |    `-- laxctl
+       |-- boostrap_cubes
+       |-- cubes/
+       |    |-- addressbook/
+       |    ..
+       |    |-- comment
+       |    ..
+       |    `-- zone/
+       |-- cubicweb/
+       |-- custom.py
+       |-- cw-cubes/
+       |-- dateutil/
+       |-- docutils/
+       |-- fckeditor/
+       |-- i18n/
+       |-- index.yaml
+       |-- loader.py
+       |-- logilab/
+       |-- main.py
+       |-- migration.py
+       |-- mx/
+       |-- roman.py
+       |-- rql/
+       |-- schema.py
+       |-- simplejson/
+       |-- tools/
+       |-- views.py
+       |-- vobject/
+       |-- yams/
+       `-- yapps/
+
+  
+This skeleton directory is a working `AppEngine` application. You will
+recognize the files ``app.yaml`` and ``main.py``. All the rest is the
+`LAX` framework and its third-party libraries. You will notice that 
+the directory ``cubes`` is a library of reusable cubes.
+
+The main directories that you should know about are:
+
+  - ``cubes`` : this is a library of reusable yams cubes. To use 
+    those cubes you will list them in the variable 
+    `included-yams-cubes` of ``app.conf``. See also :ref:`cubes`. 
+  - [WHICH OTHER ONES SHOULD BE LISTED HERE?]
+
+Dependencies
+------------
+
+Before starting anything, please make sure the following packages are installed:
+  - yaml : by default google appengine is providing yaml; make sure you can
+    import it. We recommend you create a symbolic link yaml instead of installing 
+    and using python-yaml:
+    yaml -> full/path/to/google_appengine/lib/yaml/lib/yaml/
+  - gettext
+
+Setup
+-----
+
+Once you executed ``cubicweb-ctl newgapp <myapp>``, you can use that ``myapp/`` 
+as an application directory and do as follows.
+
+This installation directory provides a configuration for an instance of `CubicWeb`
+ported for Google App Engine. It is installed with its own command ``laxctl`` 
+which is a port of the command tool ``cubicweb-ctl`` originally developped for 
+`CubicWeb`.
+
+You can have the details of available commands by running ::
+
+   $ python myapp/bin/laxctl --help
+
+
+Generating translation files
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+`LAX` is fully internationalized. Translation catalogs are found in
+``myapp/i18n``. To compile the translation files, use the `gettext` tools
+or the ``laxctl`` command ::
+
+  $ python myapp/bin/laxctl i18nupdate 
+  $ python myapp/bin/laxctl i18ncompile 
+
+Ignore the errors that print "No translation file found for domain
+'erudi'". They disappear after the first run of i18ncompile.
+
+.. note:: The command  myapp/bin/laxctl i18nupdate needs to be executed
+   only if your application is using cubes from ginco-apps.
+   Otherwise, please skip it.
+
+You will never need to add new entries in the translation catalog. Instead we would
+recommand you to use ``self.req._("msgId")`` in your application code
+to flag new message id to add to the catalog, where ``_`` refers to
+xgettext that is used to collect new strings to translate. 
+While running ``laxctl i18nupdate``, new string will be added to the catalogs.
+
+Generating the data directory
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+In order to generate the ``myapp/data`` directory that holds the static
+files like stylesheets and icons, you need to run the command::
+
+  $ python myapp/bin/laxctl populatedata
+
+Generating the schema diagram
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+There is a view named ``schema`` that displays a diagram of the
+entity-relationship graph defined by the schema. This diagram has to
+be generated from the command line::
+
+  $ python myapp/bin/laxctl genschema
+
+Application configuration
+-------------------------
+
+Authentication
+~~~~~~~~~~~~~~
+
+You have the option of using or not google authentication for your application.
+This has to be define in ``app.conf`` and ``app.yaml``.
+
+In ``app.conf`` modify the following variable::

+  # does this application rely on google authentication service or not.
+  use-google-auth=no
+ 
+In ``app.yaml`` comment the `login: required` set by default in the handler::
+
+  - url: .*
+  script: main.py
+  # comment the line below to allow anonymous access or if you don't want to use
+  # google authentication service
+  #login: required
+
+
+
+
+Quickstart : launch the application
+-----------------------------------
+
+On Mac OS X platforms, drag that directory on the
+`GoogleAppEngineLauncher`.
+
+On Unix and Windows platforms, run it with the dev_appserver::
+
+  $ python /path/to/google_appengine/dev_appserver.py /path/to/myapp/
+
+Once the local server is started, visit `http://MYAPP_URL/_load <http://localhost:8080/_load>`_ and sign in as administrator. 
+This will initialize the repository and enable you to log in into 
+the application and continue the installation.
+
+You should be redirected to a page displaying a message `content initialized`.
+
+Initialize the datastore
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+You, then, want to visit  `http://MYAPP_URL/?vid=authinfo <http://localhost:8080/?vid=authinfo>`_ .
+If you selected not  to use google authentication, you will be prompted to a 
+login form where you should initialize the administrator login (recommended
+to use admin/admin at first). You will then be redirected to a page providing
+you the value to provide to ``./bin/laxctl --cookie``.
+
+If you choosed to use google authentication, then you will not need to set up
+and administrator login but you will get the cookie value as well.
+
+This cookie values needs to be provided to ``laxctl`` commands
+in order to handle datastore administration requests.
+
+.. image:: images/lax-book.02-cookie-values.en.png
+   :alt: displaying the detailed view of the cookie values returned
+
+
+.. note:: In case you are not redirected to a page providing the 
+   option --cookie value, please visit one more time  
+   `http://MYAPP_URL/?vid=authinfo <http://localhost:8080/?vid=authinfo>`_ .
+
+Once, you have this value, then return to the shell and execute ::
+ 
+  $ python myapp/bin/laxctl db-init --cookie='dev_appserver_login=test@example.com:True; __session=7bbe973a6705bc5773a640f8cf4326cc' localhost:8080
+
+.. note:: In the case you are not using google authentication, the value returned
+   by `http://MYAPP_URL/?vid=authinfo <http://localhost:8080/?vid=authinfo>`_ 
+   will look like :
+   --cookie='__session=2b45d1a9c36c03d2a30cedb04bc37b6d'
+
+Log out by clicking in the menu at the top right corner
+and restart browsing from `http://MYAPP_URL/ <http://localhost:8080>`_ 
+as a normal user.
+
+Unless you did something to change it, http://MYAPP_URL should be
+http://localhost:8080/
+
+