doc/book/en/Z012-create-instance.en.txt
author Emile Anclin <emile.anclin@logilab.fr>
Wed, 11 Feb 2009 14:20:07 +0100
changeset 575 437aacfc0d89
child 1464 09afa1f808c4
permissions -rw-r--r--
add files for a simple setup
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
575
437aacfc0d89 add files for a simple setup
Emile Anclin <emile.anclin@logilab.fr>
parents:
diff changeset
     1
.. -*- coding: utf-8 -*-
437aacfc0d89 add files for a simple setup
Emile Anclin <emile.anclin@logilab.fr>
parents:
diff changeset
     2
437aacfc0d89 add files for a simple setup
Emile Anclin <emile.anclin@logilab.fr>
parents:
diff changeset
     3
Creation of your first instance
437aacfc0d89 add files for a simple setup
Emile Anclin <emile.anclin@logilab.fr>
parents:
diff changeset
     4
===============================
437aacfc0d89 add files for a simple setup
Emile Anclin <emile.anclin@logilab.fr>
parents:
diff changeset
     5
437aacfc0d89 add files for a simple setup
Emile Anclin <emile.anclin@logilab.fr>
parents:
diff changeset
     6
What is an instance?
437aacfc0d89 add files for a simple setup
Emile Anclin <emile.anclin@logilab.fr>
parents:
diff changeset
     7
--------------------
437aacfc0d89 add files for a simple setup
Emile Anclin <emile.anclin@logilab.fr>
parents:
diff changeset
     8
437aacfc0d89 add files for a simple setup
Emile Anclin <emile.anclin@logilab.fr>
parents:
diff changeset
     9
A `CubicWeb` instance is a container that
437aacfc0d89 add files for a simple setup
Emile Anclin <emile.anclin@logilab.fr>
parents:
diff changeset
    10
refers to cubes and configuration parameters for your web application.
437aacfc0d89 add files for a simple setup
Emile Anclin <emile.anclin@logilab.fr>
parents:
diff changeset
    11
Each instance is stored as a directory in ``~/etc/cubicweb.d`` which enables 
437aacfc0d89 add files for a simple setup
Emile Anclin <emile.anclin@logilab.fr>
parents:
diff changeset
    12
us to run your application.
437aacfc0d89 add files for a simple setup
Emile Anclin <emile.anclin@logilab.fr>
parents:
diff changeset
    13
437aacfc0d89 add files for a simple setup
Emile Anclin <emile.anclin@logilab.fr>
parents:
diff changeset
    14
What is a cube?
437aacfc0d89 add files for a simple setup
Emile Anclin <emile.anclin@logilab.fr>
parents:
diff changeset
    15
---------------
437aacfc0d89 add files for a simple setup
Emile Anclin <emile.anclin@logilab.fr>
parents:
diff changeset
    16
437aacfc0d89 add files for a simple setup
Emile Anclin <emile.anclin@logilab.fr>
parents:
diff changeset
    17
Cubes represent data and basic building bricks of your web applications :
437aacfc0d89 add files for a simple setup
Emile Anclin <emile.anclin@logilab.fr>
parents:
diff changeset
    18
blogs, person, date, addressbook and a lot more.
437aacfc0d89 add files for a simple setup
Emile Anclin <emile.anclin@logilab.fr>
parents:
diff changeset
    19
437aacfc0d89 add files for a simple setup
Emile Anclin <emile.anclin@logilab.fr>
parents:
diff changeset
    20
.. XXX They related to each other by a 'Schema' which is also the PostGres representation.
437aacfc0d89 add files for a simple setup
Emile Anclin <emile.anclin@logilab.fr>
parents:
diff changeset
    21
437aacfc0d89 add files for a simple setup
Emile Anclin <emile.anclin@logilab.fr>
parents:
diff changeset
    22
Each cube defines entities, their views, their schemas and workflows
437aacfc0d89 add files for a simple setup
Emile Anclin <emile.anclin@logilab.fr>
parents:
diff changeset
    23
in an independant directory located in ``/path/to/forest/cubicweb/cubes/``
437aacfc0d89 add files for a simple setup
Emile Anclin <emile.anclin@logilab.fr>
parents:
diff changeset
    24
for a Mercurial installation or in ``/usr/share/cubicweb/cubes`` for
437aacfc0d89 add files for a simple setup
Emile Anclin <emile.anclin@logilab.fr>
parents:
diff changeset
    25
a debian package installation. For example, the 'blog' cube defines the entities 
437aacfc0d89 add files for a simple setup
Emile Anclin <emile.anclin@logilab.fr>
parents:
diff changeset
    26
blogs and blogentries.
437aacfc0d89 add files for a simple setup
Emile Anclin <emile.anclin@logilab.fr>
parents:
diff changeset
    27
437aacfc0d89 add files for a simple setup
Emile Anclin <emile.anclin@logilab.fr>
parents:
diff changeset
    28
When an `CubicWeb` instance is created, you list the cubes that you want to use. 
437aacfc0d89 add files for a simple setup
Emile Anclin <emile.anclin@logilab.fr>
parents:
diff changeset
    29
Using a cube means having the entities defined in your cube's schema
437aacfc0d89 add files for a simple setup
Emile Anclin <emile.anclin@logilab.fr>
parents:
diff changeset
    30
available in your instance as well as their views and workflows.
437aacfc0d89 add files for a simple setup
Emile Anclin <emile.anclin@logilab.fr>
parents:
diff changeset
    31
437aacfc0d89 add files for a simple setup
Emile Anclin <emile.anclin@logilab.fr>
parents:
diff changeset
    32
437aacfc0d89 add files for a simple setup
Emile Anclin <emile.anclin@logilab.fr>
parents:
diff changeset
    33
Creating a basic `CubicWeb` Instance 
437aacfc0d89 add files for a simple setup
Emile Anclin <emile.anclin@logilab.fr>
parents:
diff changeset
    34
------------------------------------
437aacfc0d89 add files for a simple setup
Emile Anclin <emile.anclin@logilab.fr>
parents:
diff changeset
    35
437aacfc0d89 add files for a simple setup
Emile Anclin <emile.anclin@logilab.fr>
parents:
diff changeset
    36
We can create an instance to view our
437aacfc0d89 add files for a simple setup
Emile Anclin <emile.anclin@logilab.fr>
parents:
diff changeset
    37
application in a web browser. ::
437aacfc0d89 add files for a simple setup
Emile Anclin <emile.anclin@logilab.fr>
parents:
diff changeset
    38
437aacfc0d89 add files for a simple setup
Emile Anclin <emile.anclin@logilab.fr>
parents:
diff changeset
    39
  cubicweb-ctl create blog myblog
437aacfc0d89 add files for a simple setup
Emile Anclin <emile.anclin@logilab.fr>
parents:
diff changeset
    40
437aacfc0d89 add files for a simple setup
Emile Anclin <emile.anclin@logilab.fr>
parents:
diff changeset
    41
.. XXX or ::
437aacfc0d89 add files for a simple setup
Emile Anclin <emile.anclin@logilab.fr>
parents:
diff changeset
    42
  
437aacfc0d89 add files for a simple setup
Emile Anclin <emile.anclin@logilab.fr>
parents:
diff changeset
    43
.. XXX cubicweb-ctl create forge myforge
437aacfc0d89 add files for a simple setup
Emile Anclin <emile.anclin@logilab.fr>
parents:
diff changeset
    44
437aacfc0d89 add files for a simple setup
Emile Anclin <emile.anclin@logilab.fr>
parents:
diff changeset
    45
437aacfc0d89 add files for a simple setup
Emile Anclin <emile.anclin@logilab.fr>
parents:
diff changeset
    46
.. note::
437aacfc0d89 add files for a simple setup
Emile Anclin <emile.anclin@logilab.fr>
parents:
diff changeset
    47
   The commands used below are more detailled in the section dedicated to 
437aacfc0d89 add files for a simple setup
Emile Anclin <emile.anclin@logilab.fr>
parents:
diff changeset
    48
   :ref:`cubicweb-ctl`.
437aacfc0d89 add files for a simple setup
Emile Anclin <emile.anclin@logilab.fr>
parents:
diff changeset
    49
437aacfc0d89 add files for a simple setup
Emile Anclin <emile.anclin@logilab.fr>
parents:
diff changeset
    50
A series of questions will be prompted to you, the default answer is usually
437aacfc0d89 add files for a simple setup
Emile Anclin <emile.anclin@logilab.fr>
parents:
diff changeset
    51
sufficient. You can allways modify the parameters later by editing
437aacfc0d89 add files for a simple setup
Emile Anclin <emile.anclin@logilab.fr>
parents:
diff changeset
    52
configuration files. When a user/psswd is requested to access the database
437aacfc0d89 add files for a simple setup
Emile Anclin <emile.anclin@logilab.fr>
parents:
diff changeset
    53
please use the login you create at the time you configured the database
437aacfc0d89 add files for a simple setup
Emile Anclin <emile.anclin@logilab.fr>
parents:
diff changeset
    54
(:ref:`ConfigurationPostgres`).
437aacfc0d89 add files for a simple setup
Emile Anclin <emile.anclin@logilab.fr>
parents:
diff changeset
    55
437aacfc0d89 add files for a simple setup
Emile Anclin <emile.anclin@logilab.fr>
parents:
diff changeset
    56
It is important to distinguish here the user used to access the database and
437aacfc0d89 add files for a simple setup
Emile Anclin <emile.anclin@logilab.fr>
parents:
diff changeset
    57
the user used to login to the cubicweb application. When a `CubicWeb` application
437aacfc0d89 add files for a simple setup
Emile Anclin <emile.anclin@logilab.fr>
parents:
diff changeset
    58
starts, it uses the login/psswd for the database to get the schema and handle
437aacfc0d89 add files for a simple setup
Emile Anclin <emile.anclin@logilab.fr>
parents:
diff changeset
    59
low level transaction. But, when ``cubicweb-ctl create`` asks for
437aacfc0d89 add files for a simple setup
Emile Anclin <emile.anclin@logilab.fr>
parents:
diff changeset
    60
a manager login/psswd of `CubicWeb`, it refers to an application user
437aacfc0d89 add files for a simple setup
Emile Anclin <emile.anclin@logilab.fr>
parents:
diff changeset
    61
to administrate your web application. 
437aacfc0d89 add files for a simple setup
Emile Anclin <emile.anclin@logilab.fr>
parents:
diff changeset
    62
The configuration files are stored in *~/etc/cubicweb.d/myblog/*. 
437aacfc0d89 add files for a simple setup
Emile Anclin <emile.anclin@logilab.fr>
parents:
diff changeset
    63
437aacfc0d89 add files for a simple setup
Emile Anclin <emile.anclin@logilab.fr>
parents:
diff changeset
    64
To launch the web application, you just type ::
437aacfc0d89 add files for a simple setup
Emile Anclin <emile.anclin@logilab.fr>
parents:
diff changeset
    65
437aacfc0d89 add files for a simple setup
Emile Anclin <emile.anclin@logilab.fr>
parents:
diff changeset
    66
  cubicweb-ctl start myblog
437aacfc0d89 add files for a simple setup
Emile Anclin <emile.anclin@logilab.fr>
parents:
diff changeset
    67
437aacfc0d89 add files for a simple setup
Emile Anclin <emile.anclin@logilab.fr>
parents:
diff changeset
    68
You can see how it looks by
437aacfc0d89 add files for a simple setup
Emile Anclin <emile.anclin@logilab.fr>
parents:
diff changeset
    69
visiting the URL `http://localhost:8080`. 
437aacfc0d89 add files for a simple setup
Emile Anclin <emile.anclin@logilab.fr>
parents:
diff changeset
    70
To login, please use the cubicweb administrator login/psswd you 
437aacfc0d89 add files for a simple setup
Emile Anclin <emile.anclin@logilab.fr>
parents:
diff changeset
    71
defined when you created the instance.
437aacfc0d89 add files for a simple setup
Emile Anclin <emile.anclin@logilab.fr>
parents:
diff changeset
    72
437aacfc0d89 add files for a simple setup
Emile Anclin <emile.anclin@logilab.fr>
parents:
diff changeset
    73
To shutdown the instance ::
437aacfc0d89 add files for a simple setup
Emile Anclin <emile.anclin@logilab.fr>
parents:
diff changeset
    74
437aacfc0d89 add files for a simple setup
Emile Anclin <emile.anclin@logilab.fr>
parents:
diff changeset
    75
  cubicweb-ctl stop myinstance
437aacfc0d89 add files for a simple setup
Emile Anclin <emile.anclin@logilab.fr>
parents:
diff changeset
    76
437aacfc0d89 add files for a simple setup
Emile Anclin <emile.anclin@logilab.fr>
parents:
diff changeset
    77
.. XXX something like `cubicweb-ctl live-server intra` would be nice
437aacfc0d89 add files for a simple setup
Emile Anclin <emile.anclin@logilab.fr>
parents:
diff changeset
    78
437aacfc0d89 add files for a simple setup
Emile Anclin <emile.anclin@logilab.fr>
parents:
diff changeset
    79