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 |
|