.. -*- coding: utf-8 -*-

===============================
Creation of your first instance
===============================

What is an instance?
--------------------

A *CubicWeb* instance is a container that
refers to cubes and configuration parameters for your web instance.
Each instance is stored as a directory in ``~/etc/cubicweb.d`` which enables 
us to run your instance.

What is a cube?
---------------

Cubes represent data and basic building bricks of your web instances :
blogs, person, date, addressbook and a lot more.

.. XXX They related to each other by a 'Schema' which is also the PostGres representation.

Each 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. For example, the 'blog' cube defines the entities 
blogs and blogentries.

When an *CubicWeb* instance is created, you list the cubes that you want to 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.


Creating a basic *CubicWeb* Instance 
------------------------------------

We can create an instance to view our
instance in a web browser. ::

  cubicweb-ctl create blog myblog

.. XXX or ::
  
.. XXX cubicweb-ctl create forge myforge


.. note::
   The commands used below are more detailled in the section dedicated to 
   :ref:`cubicweb-ctl`.

A series of questions will be prompted to you, the default answer is usually
sufficient. You can allways modify the parameters later 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:`ConfigurationPostgresql`).

It is important to distinguish here the user used to access the database and
the user used to login to the cubicweb instance. When a *CubicWeb* instance
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 instance user
to administrate your web instance. 
The configuration files are stored in *~/etc/cubicweb.d/myblog/*. 

To launch the web instance, you just type ::

  cubicweb-ctl start myblog

You can see how it looks by
visiting the URL `http://localhost:8080`. 
To login, please use the cubicweb administrator login/psswd you 
defined when you created the instance.

To shutdown the instance ::

  cubicweb-ctl stop myinstance

.. XXX something like `cubicweb-ctl live-server intra` would be nice