--- a/doc/book/en/C020-create-instance.en.txt Tue May 05 17:18:49 2009 +0200
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,132 +0,0 @@
-.. -*- 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
-a cube.
-
-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 schemas and workflows
-in an independant directory located in ``/path/to/forest/cubicweb/cubes/``
-for a Mercurial installation or in ``/usr/share/cubicweb/cubes`` for
-a debian package installation.
-
-When an instance is created, you list one or more cubes that your instance
-will use. Using 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).
-
-.. note::
- Please note that if you do not wish to use default directory
- for your cubes library, then you want to use the option
- --directory to specify where you would like to place
- the source code of your cube:
- ``cubicweb-ctl newcube --directory=/path/to/cubes/library cube_name``
-
-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 for 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 level transaction. 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/myinstance/*. 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
-