doc/book/en/C020-create-instance.en.txt
branchtls-sprint
changeset 1714 a721966779be
parent 1499 fd8751c3f3ee
child 1715 cba9f175da2d
equal deleted inserted replaced
1499:fd8751c3f3ee 1714:a721966779be
     1 .. -*- coding: utf-8 -*-
       
     2 
       
     3 Creation of your first instance
       
     4 ===============================
       
     5 
       
     6 What is an instance?
       
     7 --------------------
       
     8 
       
     9 A `CubicWeb` instance is a directory in ``~/etc/cubicweb.d``
       
    10 which enables us to run a web application. An instance is based on
       
    11 a cube.
       
    12 
       
    13 An instance is a container that refers to cubes and configuration 
       
    14 parameters for your web application.
       
    15 
       
    16 We recommand not to define schema, entities or views in the instance
       
    17 file system itself but in the cube, in order to maintain re-usability of
       
    18 entities and their views. We strongly recommand to develop cubes which
       
    19 could be used in other instances (modular approach).
       
    20 
       
    21 
       
    22 What is a cube?
       
    23 ---------------
       
    24 
       
    25 A cube defines entities, their views, their schemas and workflows
       
    26 in an independant directory located in ``/path/to/forest/cubicweb/cubes/``
       
    27 for a Mercurial installation or in ``/usr/share/cubicweb/cubes`` for
       
    28 a debian package installation.
       
    29 
       
    30 When an instance is created, you list one or more cubes that your instance
       
    31 will use. Using a cube means having the entities defined in your cube's schema
       
    32 available in your instance as well as their views and workflows.
       
    33 
       
    34 .. note::
       
    35    The commands used below are more detailled in the section dedicated to 
       
    36    :ref:`cubicweb-ctl`.
       
    37 
       
    38 
       
    39 Create a cube
       
    40 -------------
       
    41 
       
    42 Let's start by creating the cube environment in which we will develop ::
       
    43 
       
    44   cd ~/hg
       
    45 
       
    46   cubicweb-ctl newcube mycube
       
    47 
       
    48   # answer questions 
       
    49   hg init moncube
       
    50   cd mycube
       
    51   hg add .
       
    52   hg ci
       
    53 
       
    54 If all went well, you should see the cube you just create in the list
       
    55 returned by `cubicweb-ctl list` in the section *Available components*,
       
    56 and if it is not the case please refer to :ref:`ConfigurationEnv`.
       
    57 
       
    58 To use a cube, you have to list it in the variable ``__use__``
       
    59 of the file ``__pkginfo__.py`` of the instance.
       
    60 This variable is used for the instance packaging (dependencies
       
    61 handled by system utility tools such as APT) and the usable cubes
       
    62 at the time the base is created (import_erschema('MyCube') will
       
    63 not properly work otherwise).
       
    64 
       
    65 .. note::
       
    66     Please note that if you do not wish to use default directory
       
    67     for your cubes library, then you want to use the option
       
    68     --directory to specify where you would like to place
       
    69     the source code of your cube:
       
    70     ``cubicweb-ctl newcube --directory=/path/to/cubes/library cube_name``
       
    71 
       
    72 Instance creation
       
    73 -----------------
       
    74 
       
    75 Now that we created our cube, we can create an instance to view our
       
    76 application in a web browser. To do so we will use a `all-in-on` 
       
    77 configuration to simplify things ::
       
    78 
       
    79   cubicweb-ctl create -c all-in-one mycube myinstance
       
    80 
       
    81 .. note::
       
    82   Please note that we created a new cube for a demo purpose but
       
    83   you could have use an existing cube available in our standard library
       
    84   such as blog or person for example.
       
    85 
       
    86 A serie of questions will be prompted to you, the default answer is usually
       
    87 sufficient. You can anyway modify the configuration later on by editing
       
    88 configuration files. When a user/psswd is requested to access the database
       
    89 please use the login you create at the time you configured the database
       
    90 (:ref:`ConfigurationPostgres`).
       
    91 
       
    92 It is important to distinguish here the user used to access the database and
       
    93 the user used to login to the cubicweb application. When a `CubicWeb` application
       
    94 starts, it uses the login/psswd for the database to get the schema and handle
       
    95 low level transaction. But, when ``cubicweb-ctl create`` asks for
       
    96 a manager login/psswd of `CubicWeb`, it refers to an application user you will
       
    97 use during the development to administrate your web application. It will be 
       
    98 possible, later on, to create others users for your final web application.
       
    99 
       
   100 When this command is completed, the definition of your instance is
       
   101 located in *~/etc/cubicweb.d/myinstance/*. To launch it, you just type ::
       
   102 
       
   103   cubicweb-ctl start -D myinstance
       
   104 
       
   105 The option `-D` specify the *debug mode* : the instance is not running in
       
   106 server mode and does not disconnect from the termnial, which simplifies debugging
       
   107 in case the instance is not properly launched. You can see how it looks by
       
   108 visiting the URL `http://localhost:8080` (the port number depends of your 
       
   109 configuration). To login, please use the cubicweb administrator login/psswd you 
       
   110 defined when you created the instance.
       
   111 
       
   112 To shutdown the instance, Crtl-C in the terminal window is enough.
       
   113 If you did not use the option `-D`, then type ::
       
   114 
       
   115   cubicweb-ctl stop myinstance
       
   116 
       
   117 This is it! All is settled down to start developping your data model...
       
   118 
       
   119 
       
   120 Usage of `cubicweb-liveserver`
       
   121 ``````````````````````````````
       
   122 
       
   123 To quickly test a new cube, you can also use the script `cubicweb-liveserver`
       
   124 which allows to create an application in memory (use of SQLite database by 
       
   125 default) and make it accessible through a web server ::
       
   126 
       
   127   cubicweb-ctl live-server mycube
       
   128 
       
   129 or by using an existing database (SQLite or Postgres)::
       
   130 
       
   131   cubicweb-ctl live-server -s myfile_sources mycube
       
   132