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

Creation of your first instance

===============================

Instance creation

-----------------

Now that we created a cube, we can create an instance and access it via a web

browser. We will use a `all-in-one` 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 purposes but

  you could have used an existing cube available in our standard library

  such as blog or person for example.

A series 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 login/password are requested to access the database

please use the credentials you created at the time you configured the database

(:ref:`PostgresqlConfiguration`).

It is important to distinguish here the user used to access the database and the

user used to login to the cubicweb instance. When an instance starts, it uses

the login/password for the database to get the schema and handle low level

transaction. But, when :command:`cubicweb-ctl create` asks for a manager

login/psswd of *CubicWeb*, it refers to the user you will use during the

development to administrate your web instance. It will be possible, later on,

to use this user to create other users for your final web instance.

Instance administration

-----------------------

start / stop

~~~~~~~~~~~~

When this command is completed, the definition of your instance is

located in :file:`~/etc/cubicweb.d/myinstance/*`. To launch it, you

just type ::

  cubicweb-ctl start -D myinstance

The option `-D` specifies the *debug mode* : the instance is not

running in server mode and does not disconnect from the terminal,

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/password 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...

.. note::

  The output of `cubicweb-ctl start -D myinstance` can be

  overwhelming. It is possible to reduce the log level with the

  `--loglevel` parameter as in `cubicweb-ctl start -D myinstance -l

  info` to filter out all logs under `info` gravity.

upgrade

~~~~~~~

A manual upgrade step is necessary whenever a new version of CubicWeb or

a cube is installed, in order to synchronise the instance's

configuration and schema with the new code.  The command is::

  cubicweb-ctl upgrade myinstance

A series of questions will be asked. It always starts with a proposal

to make a backup of your sources (where it applies). Unless you know

exactly what you are doing (i.e. typically fiddling in debug mode, but

definitely NOT migrating a production instance), you should answer YES

to that.

The remaining questions concern the migration steps of |cubicweb|,

then of the cubes that form the whole application, in reverse

dependency order.

In principle, if the migration scripts have been properly written and

tested, you should answer YES to all questions.

Somtimes, typically while debugging a migration script, something goes

wrong and the migration fails. Unfortunately the databse may be in an

incoherent state. You have two options here:

* fix the bug, restore the database and restart the migration process

  from scratch (quite recommended in a production environement)

* try to replay the migration up to the last successful commit, that

  is answering NO to all questions up to the step that failed, and

  finish by answering YES to the remaining questions.