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