|
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 one or more cubes. |
|
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 schems and workflows |
|
26 in an independant directory located in ``/path/to/forest/cubicweb/cubes/``. |
|
27 |
|
28 When an instance is created, you list one or more cubes that your instance |
|
29 will use. Use a cube means having the entities defined in your cube's schema |
|
30 available in your instance as well as their views and workflows. |
|
31 |
|
32 .. note:: |
|
33 The commands used below are more detailled in the section dedicated to |
|
34 :ref:`cubicweb-ctl`. |
|
35 |
|
36 |
|
37 Create a cube |
|
38 ------------- |
|
39 |
|
40 Let's start by creating the cube environment in which we will develop :: |
|
41 |
|
42 cd ~/hg |
|
43 |
|
44 cubicweb-ctl newcube mycube |
|
45 |
|
46 # answer questions |
|
47 hg init moncube |
|
48 cd mycube |
|
49 hg add . |
|
50 hg ci |
|
51 |
|
52 If all went well, you should see the cube you just create in the list |
|
53 returned by `cubicweb-ctl list` in the section *Available components*, |
|
54 and if it is not the case please refer to :ref:`ConfigurationEnv`. |
|
55 |
|
56 To use a cube, you have to list it in the variable ``__use__`` |
|
57 of the file ``__pkginfo__.py`` of the instance. |
|
58 This variable is used for the instance packaging (dependencies |
|
59 handled by system utility tools such as APT) and the usable cubes |
|
60 at the time the base is created (import_erschema('MyCube') will |
|
61 not properly work otherwise). |
|
62 |
|
63 Instance creation |
|
64 ----------------- |
|
65 |
|
66 Now that we created our cube, we can create an instance to view our |
|
67 application in a web browser. To do so we will use a `all-in-on` |
|
68 configuration to simplify things :: |
|
69 |
|
70 cubicweb-ctl create -c all-in-one mycube myinstance |
|
71 |
|
72 .. note:: |
|
73 Please note that we created a new cube for a demo purpose but |
|
74 you could have use an existing cube available in our standard library |
|
75 such as blog or person by example. |
|
76 |
|
77 A serie of questions will be prompted to you, the default answer is usually |
|
78 sufficient. You can anyway modify the configuration later on by editing |
|
79 configuration files. When a user/psswd is requested to access the database |
|
80 please use the login you create at the time you configured the database |
|
81 (:ref:`ConfigurationPostgres`). |
|
82 |
|
83 It is important to distinguish here the user used to access the database and |
|
84 the user used to login to the cubicweb application. When a `CubicWeb` application |
|
85 starts, it uses the login/psswd for the database to get the schema and handle |
|
86 low transaction [FIXME - bas niveau]. But, when ``cubicweb-ctl create`` asks for |
|
87 a manager login/psswd of `CubicWeb`, it refers to an application user you will |
|
88 use during the development to administrate your web application. It will be |
|
89 possible, later on, to create others users for your final web application. |
|
90 |
|
91 When this command is completed, the definition of your instance is |
|
92 located in *~/etc/cubicweb.d/moninstance/*. To launch it, you just type :: |
|
93 |
|
94 cubicweb-ctl start -D myinstance |
|
95 |
|
96 The option `-D` specify the *debug mode* : the instance is not running in |
|
97 server mode and does not disconnect from the termnial, which simplifies debugging |
|
98 in case the instance is not properly launched. You can see how it looks by |
|
99 visiting the URL `http://localhost:8080` (the port number depends of your |
|
100 configuration). To login, please use the cubicweb administrator login/psswd you |
|
101 defined when you created the instance. |
|
102 |
|
103 To shutdown the instance, Crtl-C in the terminal window is enough. |
|
104 If you did not use the option `-D`, then type :: |
|
105 |
|
106 cubicweb-ctl stop myinstance |
|
107 |
|
108 This is it! All is settled down to start developping your data model... |
|
109 |
|
110 |
|
111 Usage of `cubicweb-liveserver` |
|
112 `````````````````````````````` |
|
113 |
|
114 To quickly test a new cube, you can also use the script `cubicweb-liveserver` |
|
115 which allows to create an application in memory (use of SQLite database by |
|
116 default) and make it accessible through a web server :: |
|
117 |
|
118 cubicweb-ctl live-server mycube |
|
119 |
|
120 or by using an existing database (SQLite or Postgres):: |
|
121 |
|
122 cubicweb-ctl live-server -s myfile_sources mycube |
|
123 |