doc/book/en/admin/create-instance.rst
author Sylvain Thénault <sylvain.thenault@logilab.fr>
Fri, 10 Jun 2011 16:54:20 +0200
changeset 7493 3c46b9390871
parent 5317 ab757d9be796
child 10111 99863d0cbb10
permissions -rw-r--r--
[rql2sql] fix for some queries where eid variable used and entities picked as variable's table
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
93
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
     1
.. -*- coding: utf-8 -*-
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
     2
98
f756ead5746a [doc] Initial translation of first two section in installation chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
     3
Creation of your first instance
f756ead5746a [doc] Initial translation of first two section in installation chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
     4
===============================
f756ead5746a [doc] Initial translation of first two section in installation chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
     5
f756ead5746a [doc] Initial translation of first two section in installation chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
     6
Instance creation
106
fa179de1a787 [doc] Adjust TOC for this particular chapter to get the content and not list of links.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 98
diff changeset
     7
-----------------
98
f756ead5746a [doc] Initial translation of first two section in installation chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
     8
2539
0f26a76b0348 [doc] some more rewriting
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 2476
diff changeset
     9
Now that we created a cube, we can create an instance and access it via a web
0f26a76b0348 [doc] some more rewriting
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 2476
diff changeset
    10
browser. We will use a `all-in-one` configuration to simplify things ::
98
f756ead5746a [doc] Initial translation of first two section in installation chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
    11
f756ead5746a [doc] Initial translation of first two section in installation chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
    12
  cubicweb-ctl create -c all-in-one mycube myinstance
f756ead5746a [doc] Initial translation of first two section in installation chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
    13
f756ead5746a [doc] Initial translation of first two section in installation chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
    14
.. note::
f756ead5746a [doc] Initial translation of first two section in installation chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
    15
  Please note that we created a new cube for a demo purpose but
f756ead5746a [doc] Initial translation of first two section in installation chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
    16
  you could have use an existing cube available in our standard library
229
767ff7f5d5a7 [doc] Replace all : s/by example/for example/
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 127
diff changeset
    17
  such as blog or person for example.
98
f756ead5746a [doc] Initial translation of first two section in installation chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
    18
f756ead5746a [doc] Initial translation of first two section in installation chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
    19
A serie of questions will be prompted to you, the default answer is usually
f756ead5746a [doc] Initial translation of first two section in installation chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
    20
sufficient. You can anyway modify the configuration later on by editing
f756ead5746a [doc] Initial translation of first two section in installation chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
    21
configuration files. When a user/psswd is requested to access the database
f756ead5746a [doc] Initial translation of first two section in installation chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
    22
please use the login you create at the time you configured the database
5306
763319a51e72 [doc/book] some fixes for vregistry, selectors & appobjects
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 2544
diff changeset
    23
(:ref:`PostgresqlConfiguration`).
98
f756ead5746a [doc] Initial translation of first two section in installation chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
    24
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents: 1461
diff changeset
    25
It is important to distinguish here the user used to access the database and the
2476
1294a6bdf3bf application -> instance where it makes sense
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 2175
diff changeset
    26
user used to login to the cubicweb instance. When an instance starts, it uses
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents: 1461
diff changeset
    27
the login/psswd for the database to get the schema and handle low level
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents: 1461
diff changeset
    28
transaction. But, when :command:`cubicweb-ctl create` asks for a manager
2175
16d3c37c5d28 [doc] improvements
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 2173
diff changeset
    29
login/psswd of *CubicWeb*, it refers to the user you will use during the
2476
1294a6bdf3bf application -> instance where it makes sense
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 2175
diff changeset
    30
development to administrate your web instance. It will be possible, later on,
1294a6bdf3bf application -> instance where it makes sense
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 2175
diff changeset
    31
to use this user to create others users for your final web instance.
98
f756ead5746a [doc] Initial translation of first two section in installation chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
    32
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents: 1461
diff changeset
    33
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents: 1461
diff changeset
    34
Instance administration
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents: 1461
diff changeset
    35
-----------------------
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents: 1461
diff changeset
    36
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents: 1461
diff changeset
    37
start / stop
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents: 1461
diff changeset
    38
~~~~~~~~~~~~
5316
2b61c6d0f492 [doc/book] note about reducing log level
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5306
diff changeset
    39
98
f756ead5746a [doc] Initial translation of first two section in installation chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
    40
When this command is completed, the definition of your instance is
5316
2b61c6d0f492 [doc/book] note about reducing log level
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5306
diff changeset
    41
located in :file:`~/etc/cubicweb.d/myinstance/*`. To launch it, you
2b61c6d0f492 [doc/book] note about reducing log level
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5306
diff changeset
    42
just type ::
98
f756ead5746a [doc] Initial translation of first two section in installation chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
    43
f756ead5746a [doc] Initial translation of first two section in installation chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
    44
  cubicweb-ctl start -D myinstance
f756ead5746a [doc] Initial translation of first two section in installation chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
    45
5317
ab757d9be796 [doc/book] explain what happens/to do when issuing upgrade command
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5316
diff changeset
    46
The option `-D` specifies the *debug mode* : the instance is not
ab757d9be796 [doc/book] explain what happens/to do when issuing upgrade command
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5316
diff changeset
    47
running in server mode and does not disconnect from the terminal,
ab757d9be796 [doc/book] explain what happens/to do when issuing upgrade command
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5316
diff changeset
    48
which simplifies debugging in case the instance is not properly
ab757d9be796 [doc/book] explain what happens/to do when issuing upgrade command
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5316
diff changeset
    49
launched. You can see how it looks by visiting the URL
ab757d9be796 [doc/book] explain what happens/to do when issuing upgrade command
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5316
diff changeset
    50
`http://localhost:8080` (the port number depends of your
ab757d9be796 [doc/book] explain what happens/to do when issuing upgrade command
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5316
diff changeset
    51
configuration). To login, please use the cubicweb administrator
ab757d9be796 [doc/book] explain what happens/to do when issuing upgrade command
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5316
diff changeset
    52
login/psswd you defined when you created the instance.
98
f756ead5746a [doc] Initial translation of first two section in installation chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
    53
f756ead5746a [doc] Initial translation of first two section in installation chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
    54
To shutdown the instance, Crtl-C in the terminal window is enough.
f756ead5746a [doc] Initial translation of first two section in installation chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
    55
If you did not use the option `-D`, then type ::
f756ead5746a [doc] Initial translation of first two section in installation chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
    56
f756ead5746a [doc] Initial translation of first two section in installation chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
    57
  cubicweb-ctl stop myinstance
f756ead5746a [doc] Initial translation of first two section in installation chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
    58
f756ead5746a [doc] Initial translation of first two section in installation chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
    59
This is it! All is settled down to start developping your data model...
93
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    60
5316
2b61c6d0f492 [doc/book] note about reducing log level
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5306
diff changeset
    61
.. note::
2b61c6d0f492 [doc/book] note about reducing log level
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5306
diff changeset
    62
2b61c6d0f492 [doc/book] note about reducing log level
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5306
diff changeset
    63
  The output of `cubicweb-ctl start -D myinstance` can be
2b61c6d0f492 [doc/book] note about reducing log level
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5306
diff changeset
    64
  overwhelming. It is possible to reduce the log level with the
2b61c6d0f492 [doc/book] note about reducing log level
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5306
diff changeset
    65
  `--loglevel` parameter as in `cubicweb-ctl start -D myinstance -l
2b61c6d0f492 [doc/book] note about reducing log level
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5306
diff changeset
    66
  info` to filter out all logs under `info` gravity.
93
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    67
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents: 1461
diff changeset
    68
upgrade
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents: 1461
diff changeset
    69
~~~~~~~
93
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    70
2539
0f26a76b0348 [doc] some more rewriting
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 2476
diff changeset
    71
The command is::
0f26a76b0348 [doc] some more rewriting
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 2476
diff changeset
    72
0f26a76b0348 [doc] some more rewriting
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 2476
diff changeset
    73
  cubicweb-ctl upgrade myinstance
0f26a76b0348 [doc] some more rewriting
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 2476
diff changeset
    74
5317
ab757d9be796 [doc/book] explain what happens/to do when issuing upgrade command
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5316
diff changeset
    75
A series of questions will be asked. It always starts with a proposal
ab757d9be796 [doc/book] explain what happens/to do when issuing upgrade command
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5316
diff changeset
    76
to make a backup of your sources (where it applies). Unless you know
ab757d9be796 [doc/book] explain what happens/to do when issuing upgrade command
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5316
diff changeset
    77
exactly what you are doing (i.e. typically fiddling in debug mode, but
ab757d9be796 [doc/book] explain what happens/to do when issuing upgrade command
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5316
diff changeset
    78
definitely NOT migrating a production instance), you should answer YES
ab757d9be796 [doc/book] explain what happens/to do when issuing upgrade command
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5316
diff changeset
    79
to that.
ab757d9be796 [doc/book] explain what happens/to do when issuing upgrade command
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5316
diff changeset
    80
ab757d9be796 [doc/book] explain what happens/to do when issuing upgrade command
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5316
diff changeset
    81
The remaining questions concern the migration steps of |cubicweb|,
ab757d9be796 [doc/book] explain what happens/to do when issuing upgrade command
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5316
diff changeset
    82
then of the cubes that form the whole application, in reverse
ab757d9be796 [doc/book] explain what happens/to do when issuing upgrade command
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5316
diff changeset
    83
dependency order.
2173
7fae9300b9f9 [doc] improvements
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 2172
diff changeset
    84
5317
ab757d9be796 [doc/book] explain what happens/to do when issuing upgrade command
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5316
diff changeset
    85
In principle, if the migration scripts have been properly written and
ab757d9be796 [doc/book] explain what happens/to do when issuing upgrade command
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5316
diff changeset
    86
tested, you should answer YES to all questions.
ab757d9be796 [doc/book] explain what happens/to do when issuing upgrade command
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5316
diff changeset
    87
ab757d9be796 [doc/book] explain what happens/to do when issuing upgrade command
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5316
diff changeset
    88
Somtimes, typically while debugging a migration script, something goes
ab757d9be796 [doc/book] explain what happens/to do when issuing upgrade command
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5316
diff changeset
    89
wrong and the migration fails. Unfortunately the databse may be in an
ab757d9be796 [doc/book] explain what happens/to do when issuing upgrade command
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5316
diff changeset
    90
incoherent state. You have two options here:
ab757d9be796 [doc/book] explain what happens/to do when issuing upgrade command
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5316
diff changeset
    91
ab757d9be796 [doc/book] explain what happens/to do when issuing upgrade command
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5316
diff changeset
    92
* fix the bug, restore the database and restart the migration process
ab757d9be796 [doc/book] explain what happens/to do when issuing upgrade command
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5316
diff changeset
    93
  from scratch (quite recommended in a production environement)
ab757d9be796 [doc/book] explain what happens/to do when issuing upgrade command
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5316
diff changeset
    94
ab757d9be796 [doc/book] explain what happens/to do when issuing upgrade command
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5316
diff changeset
    95
* try to replay the migration up to the last successful commit, that
ab757d9be796 [doc/book] explain what happens/to do when issuing upgrade command
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5316
diff changeset
    96
  is answering NO to all question up to the step that failed, and
ab757d9be796 [doc/book] explain what happens/to do when issuing upgrade command
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5316
diff changeset
    97
  finish by answering YES to the remaining questions.
ab757d9be796 [doc/book] explain what happens/to do when issuing upgrade command
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5316
diff changeset
    98