.. -*- 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 application.
Each instance is stored as a directory in ``~/etc/cubicweb.d`` which enables 
us to run your application.

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

Cubes represent data and basic building bricks of your web applications :
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
application 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:`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
to administrate your web application. 
The configuration files are stored in *~/etc/cubicweb.d/myblog/*. 

To launch the web application, 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