.. -*- 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 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