--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/book/en/C012-create-instance.en.txt	Sat Nov 22 23:59:42 2008 +0100
@@ -0,0 +1,123 @@
+.. -*- coding: utf-8 -*-
+
+Creation of your first instance
+===============================
+
+What is an instance?
+--------------------
+
+A `CubicWeb` instance is a directory in ``~/etc/cubicweb.d``
+which enables us to run a web application. An instance is based on
+one or more cubes.
+
+An instance is a container that refers to cubes and configuration 
+parameters for your web application.
+
+We recommand not to define schema, entities or views in the instance
+file system itself but in the cube, in order to maintain re-usability of
+entities and their views. We strongly recommand to develop cubes which
+could be used in other instances (modular approach).
+
+
+What is a cube?
+---------------
+
+A cube defines entities, their views, their schems and workflows
+in an independant directory located in ``/path/to/forest/cubicweb/cubes/``.
+
+When an instance is created, you list one or more cubes that your instance
+will use. Use a cube means having the entities defined in your cube's schema
+available in your instance as well as their views and workflows.
+
+.. note::
+   The commands used below are more detailled in the section dedicated to 
+   :ref:`cubicweb-ctl`.
+
+
+Create a cube
+-------------
+
+Let's start by creating the cube environment in which we will develop ::
+
+  cd ~/hg
+
+  cubicweb-ctl newcube mycube
+
+  # answer questions 
+  hg init moncube
+  cd mycube
+  hg add .
+  hg ci
+
+If all went well, you should see the cube you just create in the list
+returned by `cubicweb-ctl list` in the section *Available components*,
+and if it is not the case please refer to :ref:`ConfigurationEnv`.
+
+To use a cube, you have to list it in the variable ``__use__``
+of the file ``__pkginfo__.py`` of the instance.
+This variable is used for the instance packaging (dependencies
+handled by system utility tools such as APT) and the usable cubes
+at the time the base is created (import_erschema('MyCube') will
+not properly work otherwise).
+
+Instance creation
+-----------------
+
+Now that we created our cube, we can create an instance to view our
+application in a web browser. To do so we will use a `all-in-on` 
+configuration to simplify things ::
+
+  cubicweb-ctl create -c all-in-one mycube myinstance
+
+.. note::
+  Please note that we created a new cube for a demo purpose but
+  you could have use an existing cube available in our standard library
+  such as blog or person by example.
+
+A serie of questions will be prompted to you, the default answer is usually
+sufficient. You can anyway modify the configuration later on by editing
+configuration files. When a user/psswd is requested to access the database
+please use the login you create at the time you configured the database
+(:ref:`ConfigurationPostgres`).
+
+It is important to distinguish here the user used to access the database and
+the user used to login to the cubicweb application. When a `CubicWeb` application
+starts, it uses the login/psswd for the database to get the schema and handle
+low transaction [FIXME - bas niveau]. But, when ``cubicweb-ctl create`` asks for
+a manager login/psswd of `CubicWeb`, it refers to an application user you will
+use during the development to administrate your web application. It will be 
+possible, later on, to create others users for your final web application.
+
+When this command is completed, the definition of your instance is
+located in *~/etc/cubicweb.d/moninstance/*. To launch it, you just type ::
+
+  cubicweb-ctl start -D myinstance
+
+The option `-D` specify the *debug mode* : the instance is not running in
+server mode and does not disconnect from the termnial, which simplifies debugging
+in case the instance is not properly launched. You can see how it looks by
+visiting the URL `http://localhost:8080` (the port number depends of your 
+configuration). To login, please use the cubicweb administrator login/psswd you 
+defined when you created the instance.
+
+To shutdown the instance, Crtl-C in the terminal window is enough.
+If you did not use the option `-D`, then type ::
+
+  cubicweb-ctl stop myinstance
+
+This is it! All is settled down to start developping your data model...
+
+
+Usage of `cubicweb-liveserver`
+``````````````````````````````
+
+To quickly test a new cube, you can also use the script `cubicweb-liveserver`
+which allows to create an application in memory (use of SQLite database by 
+default) and make it accessible through a web server ::
+
+  cubicweb-ctl live-server mycube
+
+or by using an existing database (SQLite or Postgres)::
+
+  cubicweb-ctl live-server -s myfile_sources mycube
+