doc/book/en/Z012-create-instance.en.txt
author Sandrine Ribeau <sandrine.ribeau@logilab.fr>
Thu, 23 Apr 2009 13:05:42 -0700
changeset 1464 09afa1f808c4
parent 575 437aacfc0d89
child 2175 16d3c37c5d28
permissions -rw-r--r--
[doc] Fix ReST pb.
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
1464
09afa1f808c4 [doc] Fix ReST pb.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 575
diff changeset
     3
===============================
575
437aacfc0d89 add files for a simple setup
Emile Anclin <emile.anclin@logilab.fr>
parents:
diff changeset
     4
Creation of your first instance
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
437aacfc0d89 add files for a simple setup
Emile Anclin <emile.anclin@logilab.fr>
parents:
diff changeset
     7
What is an instance?
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
437aacfc0d89 add files for a simple setup
Emile Anclin <emile.anclin@logilab.fr>
parents:
diff changeset
    10
A `CubicWeb` instance is a container that
437aacfc0d89 add files for a simple setup
Emile Anclin <emile.anclin@logilab.fr>
parents:
diff changeset
    11
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
    12
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
    13
us to run your application.
437aacfc0d89 add files for a simple setup
Emile Anclin <emile.anclin@logilab.fr>
parents:
diff changeset
    14
437aacfc0d89 add files for a simple setup
Emile Anclin <emile.anclin@logilab.fr>
parents:
diff changeset
    15
What is a cube?
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
437aacfc0d89 add files for a simple setup
Emile Anclin <emile.anclin@logilab.fr>
parents:
diff changeset
    18
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
    19
blogs, person, date, addressbook and a lot more.
437aacfc0d89 add files for a simple setup
Emile Anclin <emile.anclin@logilab.fr>
parents:
diff changeset
    20
437aacfc0d89 add files for a simple setup
Emile Anclin <emile.anclin@logilab.fr>
parents:
diff changeset
    21
.. 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
    22
437aacfc0d89 add files for a simple setup
Emile Anclin <emile.anclin@logilab.fr>
parents:
diff changeset
    23
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
    24
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
    25
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
    26
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
    27
blogs and blogentries.
437aacfc0d89 add files for a simple setup
Emile Anclin <emile.anclin@logilab.fr>
parents:
diff changeset
    28
437aacfc0d89 add files for a simple setup
Emile Anclin <emile.anclin@logilab.fr>
parents:
diff changeset
    29
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
    30
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
    31
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
    32
437aacfc0d89 add files for a simple setup
Emile Anclin <emile.anclin@logilab.fr>
parents:
diff changeset
    33
437aacfc0d89 add files for a simple setup
Emile Anclin <emile.anclin@logilab.fr>
parents:
diff changeset
    34
Creating a basic `CubicWeb` Instance 
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
437aacfc0d89 add files for a simple setup
Emile Anclin <emile.anclin@logilab.fr>
parents:
diff changeset
    37
We can create an instance to view our
437aacfc0d89 add files for a simple setup
Emile Anclin <emile.anclin@logilab.fr>
parents:
diff changeset
    38
application in a web browser. ::
437aacfc0d89 add files for a simple setup
Emile Anclin <emile.anclin@logilab.fr>
parents:
diff changeset
    39
437aacfc0d89 add files for a simple setup
Emile Anclin <emile.anclin@logilab.fr>
parents:
diff changeset
    40
  cubicweb-ctl create blog myblog
437aacfc0d89 add files for a simple setup
Emile Anclin <emile.anclin@logilab.fr>
parents:
diff changeset
    41
437aacfc0d89 add files for a simple setup
Emile Anclin <emile.anclin@logilab.fr>
parents:
diff changeset
    42
.. XXX or ::
437aacfc0d89 add files for a simple setup
Emile Anclin <emile.anclin@logilab.fr>
parents:
diff changeset
    43
  
437aacfc0d89 add files for a simple setup
Emile Anclin <emile.anclin@logilab.fr>
parents:
diff changeset
    44
.. XXX cubicweb-ctl create forge myforge
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
437aacfc0d89 add files for a simple setup
Emile Anclin <emile.anclin@logilab.fr>
parents:
diff changeset
    47
.. note::
437aacfc0d89 add files for a simple setup
Emile Anclin <emile.anclin@logilab.fr>
parents:
diff changeset
    48
   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
    49
   :ref:`cubicweb-ctl`.
437aacfc0d89 add files for a simple setup
Emile Anclin <emile.anclin@logilab.fr>
parents:
diff changeset
    50
437aacfc0d89 add files for a simple setup
Emile Anclin <emile.anclin@logilab.fr>
parents:
diff changeset
    51
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
    52
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
    53
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
    54
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
    55
(:ref:`ConfigurationPostgres`).
437aacfc0d89 add files for a simple setup
Emile Anclin <emile.anclin@logilab.fr>
parents:
diff changeset
    56
437aacfc0d89 add files for a simple setup
Emile Anclin <emile.anclin@logilab.fr>
parents:
diff changeset
    57
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
    58
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
    59
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
    60
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
    61
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
    62
to administrate your web application. 
437aacfc0d89 add files for a simple setup
Emile Anclin <emile.anclin@logilab.fr>
parents:
diff changeset
    63
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
    64
437aacfc0d89 add files for a simple setup
Emile Anclin <emile.anclin@logilab.fr>
parents:
diff changeset
    65
To launch the web application, you just type ::
437aacfc0d89 add files for a simple setup
Emile Anclin <emile.anclin@logilab.fr>
parents:
diff changeset
    66
437aacfc0d89 add files for a simple setup
Emile Anclin <emile.anclin@logilab.fr>
parents:
diff changeset
    67
  cubicweb-ctl start myblog
437aacfc0d89 add files for a simple setup
Emile Anclin <emile.anclin@logilab.fr>
parents:
diff changeset
    68
437aacfc0d89 add files for a simple setup
Emile Anclin <emile.anclin@logilab.fr>
parents:
diff changeset
    69
You can see how it looks by
437aacfc0d89 add files for a simple setup
Emile Anclin <emile.anclin@logilab.fr>
parents:
diff changeset
    70
visiting the URL `http://localhost:8080`. 
437aacfc0d89 add files for a simple setup
Emile Anclin <emile.anclin@logilab.fr>
parents:
diff changeset
    71
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
    72
defined when you created the instance.
437aacfc0d89 add files for a simple setup
Emile Anclin <emile.anclin@logilab.fr>
parents:
diff changeset
    73
437aacfc0d89 add files for a simple setup
Emile Anclin <emile.anclin@logilab.fr>
parents:
diff changeset
    74
To shutdown the instance ::
437aacfc0d89 add files for a simple setup
Emile Anclin <emile.anclin@logilab.fr>
parents:
diff changeset
    75
437aacfc0d89 add files for a simple setup
Emile Anclin <emile.anclin@logilab.fr>
parents:
diff changeset
    76
  cubicweb-ctl stop myinstance
437aacfc0d89 add files for a simple setup
Emile Anclin <emile.anclin@logilab.fr>
parents:
diff changeset
    77
437aacfc0d89 add files for a simple setup
Emile Anclin <emile.anclin@logilab.fr>
parents:
diff changeset
    78
.. 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
    79
437aacfc0d89 add files for a simple setup
Emile Anclin <emile.anclin@logilab.fr>
parents:
diff changeset
    80