doc/book/admin/create-instance.rst
author Denis Laxalde <denis.laxalde@logilab.fr>
Tue, 12 Sep 2017 15:05:22 +0200
changeset 12208 159dce89a145
parent 10491 c67bcee93248
child 12534 e0e7d8ca051f
permissions -rw-r--r--
[views] Respond with 400 Bad Request in case of validation error in ajax request Previously, we raised a plain RemoteCallFailed without a status code, in which case it defaults to "500 Internal Server Error". Now, for validation errors, we issue a 400 Bad Request since these are clearly client errors.
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::
10111
99863d0cbb10 [book] typos / clarifications in create-instance section
Julien Cristau <julien.cristau@logilab.fr>
parents: 5317
diff changeset
    15
  Please note that we created a new cube for a demo purposes but
99863d0cbb10 [book] typos / clarifications in create-instance section
Julien Cristau <julien.cristau@logilab.fr>
parents: 5317
diff changeset
    16
  you could have used 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
10111
99863d0cbb10 [book] typos / clarifications in create-instance section
Julien Cristau <julien.cristau@logilab.fr>
parents: 5317
diff changeset
    19
A series of questions will be prompted to you, the default answer is usually
98
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
10111
99863d0cbb10 [book] typos / clarifications in create-instance section
Julien Cristau <julien.cristau@logilab.fr>
parents: 5317
diff changeset
    21
configuration files. When a login/password are requested to access the database
99863d0cbb10 [book] typos / clarifications in create-instance section
Julien Cristau <julien.cristau@logilab.fr>
parents: 5317
diff changeset
    22
please use the credentials you created 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
10111
99863d0cbb10 [book] typos / clarifications in create-instance section
Julien Cristau <julien.cristau@logilab.fr>
parents: 5317
diff changeset
    27
the login/password for the database to get the schema and handle low level
1714
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,
10111
99863d0cbb10 [book] typos / clarifications in create-instance section
Julien Cristau <julien.cristau@logilab.fr>
parents: 5317
diff changeset
    31
to use this user to create other 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
10111
99863d0cbb10 [book] typos / clarifications in create-instance section
Julien Cristau <julien.cristau@logilab.fr>
parents: 5317
diff changeset
    52
login/password 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
10111
99863d0cbb10 [book] typos / clarifications in create-instance section
Julien Cristau <julien.cristau@logilab.fr>
parents: 5317
diff changeset
    71
A manual upgrade step is necessary whenever a new version of CubicWeb or
99863d0cbb10 [book] typos / clarifications in create-instance section
Julien Cristau <julien.cristau@logilab.fr>
parents: 5317
diff changeset
    72
a cube is installed, in order to synchronise the instance's
99863d0cbb10 [book] typos / clarifications in create-instance section
Julien Cristau <julien.cristau@logilab.fr>
parents: 5317
diff changeset
    73
configuration and schema with the new code.  The command is::
2539
0f26a76b0348 [doc] some more rewriting
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 2476
diff changeset
    74
0f26a76b0348 [doc] some more rewriting
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 2476
diff changeset
    75
  cubicweb-ctl upgrade myinstance
0f26a76b0348 [doc] some more rewriting
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 2476
diff changeset
    76
5317
ab757d9be796 [doc/book] explain what happens/to do when issuing upgrade command
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5316
diff changeset
    77
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
    78
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
    79
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
    80
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
    81
to that.
ab757d9be796 [doc/book] explain what happens/to do when issuing upgrade command
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5316
diff changeset
    82
ab757d9be796 [doc/book] explain what happens/to do when issuing upgrade command
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5316
diff changeset
    83
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
    84
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
    85
dependency order.
2173
7fae9300b9f9 [doc] improvements
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 2172
diff changeset
    86
5317
ab757d9be796 [doc/book] explain what happens/to do when issuing upgrade command
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5316
diff changeset
    87
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
    88
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
    89
ab757d9be796 [doc/book] explain what happens/to do when issuing upgrade command
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5316
diff changeset
    90
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
    91
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
    92
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
    93
ab757d9be796 [doc/book] explain what happens/to do when issuing upgrade command
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5316
diff changeset
    94
* 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
    95
  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
    96
ab757d9be796 [doc/book] explain what happens/to do when issuing upgrade command
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5316
diff changeset
    97
* try to replay the migration up to the last successful commit, that
10111
99863d0cbb10 [book] typos / clarifications in create-instance section
Julien Cristau <julien.cristau@logilab.fr>
parents: 5317
diff changeset
    98
  is answering NO to all questions up to the step that failed, and
5317
ab757d9be796 [doc/book] explain what happens/to do when issuing upgrade command
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5316
diff changeset
    99
  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
   100