3 ===================================

     3 ===============================

     4 Creation de votre premiere instance

     4 Creation of your first instance

     5 ===================================

     5 ===============================

     6 

     7 What is an instance?

     8 ====================

     9 

    10 A `CubicWeb` instance is a directory in ``~/etc/cubicweb.d``

    11 which enables us to run a web application. An instance is based on

    12 one or more cubes.

    13 

    14 An instance is a container that refers to cubes and configuration 

    15 parameters for your web application.

    16 

    17 We recommand not to define schema, entities or views in the instance

    18 file system itself but in the cube, in order to maintain re-usability of

    19 entities and their views. We strongly recommand to develop cubes which

    20 could be used in other instances (modular approach).

     8 Qu'est-ce qu'une instance?

    23 What is a cube?

     9 ==========================

    24 ===============

    11 Une instance CubicWeb consiste en un dossier situe dans ``~/etc/cubicweb.d``

    26 A cube defines entities, their views, their schems and workflows

    12 qui permettra de lancer une application web. Une instance est cree a partir

    27 in an independant directory located in ``/path/to/forest/cubicweb/cubes/``.

    13 d'un ou plusieurs cubes.

    15 Nous recommandons de ne pas definir de schema, entites ou vues dans l'instance 

    29 When an instance is created, you list one or more cubes that your instance

    16 meme si cela est possible dans un but de re-utilisabilite des entities et de leurs

    30 will use. Use a cube means having the entities defined in your cube's schema

    17 vues. Nous conseillons plutot de developper des cubes qui pourront par la suite

    31 available in your instance as well as their views and workflows.

    18 etre utilises dans d'autres instances (approche modulaire).

    20 L'instance n'est qu'un conteneur referrant a des cubes et a des parametres

    33 .. note::

    21 des configuration de l'application web.

    34    The commands used below are more detailled in the section dedicated to 

    22 

    35    :ref:`cubicweb-ctl`.

    23 Qu'est-ce qu'un cube?

    24 =====================

    25 

    26 Un cube definit des entities, leur vues, leur schemas et leur workflow 

    27 dans un repertoire independant situe dans ``/path/to/forest/cubicweb/cubes/``.

    28 

    29 Lors de la creation d'une instance, vous avez la possibilite de lister

    30 le ou les cubes que votre instance va utiliser. Utiliser un cube signifie

    31 avoir a disposition dans votre instance les entites definies dans le schema

    32 de votre cube ainsi que les vues et les workflows.

    35 .. note::

    38 Create a cube

    36    Les commandes utilisees ci-apres sont detaillees dans la section

    39 =============

    37    dediee a :ref:`cubicweb-ctl`.

    39 

    41 Let's start by creating the cube environment in which we will develop ::

    40 Création d'un cube

    41 ==================

    42 

    43 Commençons par créer un squelette qui nous servira de base au développement de

    44 notre cube ou application ::

    48   cubicweb-ctl newtemplate moncube

    45   cubicweb-ctl newcube mycube

    50   # répondre aux questions

    47   # answer questions 

    52   cd moncube

    49   cd mycube

    56 A partir de là si tout va bien, votre cube devrait être affiché par

    53 If all went well, you should see the cube you just create in the list

    57 `cubicweb-ctl list` dans la section *Available components*, si ce n'est pas le cas

    54 returned by `cubicweb-ctl list` in the section *Available components*,

    58 revoir la section :ref:`ConfigurationEnv`.

    55 and if it is not the case please refer to :ref:`ConfigurationEnv`.

    56 

    57 To use a cube, you have to list it in the variable ``__use__``

    58 of the file ``__pkginfo__.py`` of the instance.

    59 This variable is used for the instance packaging (dependencies

    60 handled by system utility tools such as APT) and the usable cubes

    61 at the time the base is created (import_erschema('MyCube') will

    62 not properly work otherwise).

    63 

    64 Instance creation

    65 =================

    66 

    67 Now that we created our cube, we can create an instance to view our

    68 application in a web browser. To do so we will use a `all-in-on` 

    69 configuration to simplify things ::

    70 

    71   cubicweb-ctl create -c all-in-one mycube myinstance

    72 

    73 .. note::

    74   Please note that we created a new cube for a demo purpose but

    75   you could have use an existing cube available in our standard library

    76   such as blog or person by example.

    77 

    78 A serie of questions will be prompted to you, the default answer is usually

    79 sufficient. You can anyway modify the configuration later on by editing

    80 configuration files. When a user/psswd is requested to access the database

    81 please use the login you create at the time you configured the database

    82 (:ref:`ConfigurationPostgres`).

    83 

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

    85 the user used to login to the cubicweb application. When a `CubicWeb` application

    86 starts, it uses the login/psswd for the database to get the schema and handle

    87 low transaction [FIXME - bas niveau]. But, when ``cubicweb-ctl create`` asks for

    88 a manager login/psswd of `CubicWeb`, it refers to an application user you will

    89 use during the development to administrate your web application. It will be 

    90 possible, later on, to create others users for your final web application.

    91 

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

    93 located in *~/etc/cubicweb.d/moninstance/*. To launch it, you just type ::

    94 

    95   cubicweb-ctl start -D myinstance

    96 

    97 The option `-D` specify the *debug mode* : the instance is not running in

    98 server mode and does not disconnect from the termnial, which simplifies debugging

    99 in case the instance is not properly launched. You can see how it looks by

   100 visiting the URL `http://localhost:8080` (the port number depends of your 

   101 configuration). To login, please use the cubicweb administrator login/psswd you 

   102 defined when you created the instance.

   103 

   104 To shutdown the instance, Crtl-C in the terminal window is enough.

   105 If you did not use the option `-D`, then type ::

   106 

   107   cubicweb-ctl stop myinstance

   108 

   109 This is it! All is settled down to start developping your data model...

    61 Pour utiliser un cube, il faut le mentionner dans la variable

   112 Usage of `cubicweb-liveserver`

    62 __use__ du fichier __pkginfo__ de l'application. Cette variable

   113 ------------------------------

    63 contrôle à la fois le packaging de l'application (dépendances gérées

    64 par les utilitaires système comme les outils APT) et les composants

    65 effectivement utilisables lors de la création de la base

    66 (import_erschema('Moncomposant') ne fonctionne pas sinon).

    68 Création d'une instance de développement

   115 To quickly test a new cube, you can also use the script `cubicweb-liveserver`

    69 ========================================

   116 which allows to create an application in memory (use of SQLite database by 

   117 default) and make it accessible through a web server ::

    71 Maintenant que nous avons notre squelette de modèle, on peut en créer une

   119   cubicweb-ctl live-server mycube

    72 instance afin de voir ce que tout ça donne dans un simple navigateur web.

    73 Nous allons utiliser une configuration `all-in-one` afin de simplifier les

    74 choses ::

    76   cubicweb-ctl create -c all-in-one moncube moninstance

   121 or by using an existing database (SQLite or Postgres)::

    78 Une série de questions vont être posées, la réponse par défaut est généralement

   123   cubicweb-ctl live-server -s myfile_sources mycube

    79 suffisante. Vous pourrez de toute façon modifier la configuration par la suite

    80 en éditant les fichiers générés. Lorsqu'un login/mot de passe d'accès au sgbd

    81 vous est demandé, il est recommandé d'utiliser l'utilisateur créé lors de la

    82 :ref:`ConfigurationPostgres`.