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