doc/book/admin/cubicweb-ctl.rst
author Laurent Peuch <cortex@worlddomination.be>
Fri, 12 Apr 2019 11:54:42 +0200
changeset 12573 9b883489279f
parent 12522 fd64e424fba5
permissions -rw-r--r--
DeprecationWarning: Please use assertEqual instead.
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
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
     3
.. _cubicweb-ctl:
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
     4
100
e4d0fd06da7f [doc] Initial translation of cubicweb-tool section.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
     5
``cubicweb-ctl`` tool
e4d0fd06da7f [doc] Initial translation of cubicweb-tool section.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
     6
=====================
93
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
     7
2175
16d3c37c5d28 [doc] improvements
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 2172
diff changeset
     8
`cubicweb-ctl` is the swiss knife to manage *CubicWeb* instances.
100
e4d0fd06da7f [doc] Initial translation of cubicweb-tool section.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
     9
The general syntax is ::
93
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    10
100
e4d0fd06da7f [doc] Initial translation of cubicweb-tool section.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
    11
  cubicweb-ctl <command> [options command] <arguments commands>
e4d0fd06da7f [doc] Initial translation of cubicweb-tool section.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
    12
e4d0fd06da7f [doc] Initial translation of cubicweb-tool section.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
    13
To view available commands ::
93
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    14
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    15
  cubicweb-ctl
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    16
  cubicweb-ctl --help
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    17
2175
16d3c37c5d28 [doc] improvements
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 2172
diff changeset
    18
Please note that the commands available depends on the *CubicWeb* packages
100
e4d0fd06da7f [doc] Initial translation of cubicweb-tool section.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
    19
and cubes that have been installed.
93
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    20
100
e4d0fd06da7f [doc] Initial translation of cubicweb-tool section.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
    21
To view the help menu on specific command ::
93
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    22
100
e4d0fd06da7f [doc] Initial translation of cubicweb-tool section.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
    23
  cubicweb-ctl <command> --help
93
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    24
4752
2c2a9c53aea3 [book/cwctl] reorganize a bit this page (very messy)
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 2476
diff changeset
    25
Listing available cubes and instance
2c2a9c53aea3 [book/cwctl] reorganize a bit this page (very messy)
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 2476
diff changeset
    26
-------------------------------------
100
e4d0fd06da7f [doc] Initial translation of cubicweb-tool section.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
    27
4752
2c2a9c53aea3 [book/cwctl] reorganize a bit this page (very messy)
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 2476
diff changeset
    28
* ``list``, provides a list of the available configuration, cubes
2c2a9c53aea3 [book/cwctl] reorganize a bit this page (very messy)
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 2476
diff changeset
    29
  and instances.
2172
cf8f9180e63e delete-trailing-whitespace
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 1898
diff changeset
    30
93
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    31
4752
2c2a9c53aea3 [book/cwctl] reorganize a bit this page (very messy)
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 2476
diff changeset
    32
Creation of a new cube
2c2a9c53aea3 [book/cwctl] reorganize a bit this page (very messy)
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 2476
diff changeset
    33
-----------------------
2c2a9c53aea3 [book/cwctl] reorganize a bit this page (very messy)
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 2476
diff changeset
    34
2c2a9c53aea3 [book/cwctl] reorganize a bit this page (very messy)
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 2476
diff changeset
    35
Create your new cube cube ::
2c2a9c53aea3 [book/cwctl] reorganize a bit this page (very messy)
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 2476
diff changeset
    36
11689
213f60272d49 [doc] Update book sections about cubes being Python packages
Denis Laxalde <denis.laxalde@logilab.fr>
parents: 10491
diff changeset
    37
   cubicweb-ctl newcube -d <target directory>
4752
2c2a9c53aea3 [book/cwctl] reorganize a bit this page (very messy)
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 2476
diff changeset
    38
11689
213f60272d49 [doc] Update book sections about cubes being Python packages
Denis Laxalde <denis.laxalde@logilab.fr>
parents: 10491
diff changeset
    39
This will create a new cube ``<target directory>``.
4752
2c2a9c53aea3 [book/cwctl] reorganize a bit this page (very messy)
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 2476
diff changeset
    40
2c2a9c53aea3 [book/cwctl] reorganize a bit this page (very messy)
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 2476
diff changeset
    41
Create an instance
2c2a9c53aea3 [book/cwctl] reorganize a bit this page (very messy)
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 2476
diff changeset
    42
-------------------
2c2a9c53aea3 [book/cwctl] reorganize a bit this page (very messy)
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 2476
diff changeset
    43
8603
544ce5dd863c [doc] fix of personnal etc directory in book
Arthur Lutz <arthur.lutz@logilab.fr>
parents: 8032
diff changeset
    44
You must ensure `~/etc/cubicweb.d/` exists prior to this. On windows, the
4752
2c2a9c53aea3 [book/cwctl] reorganize a bit this page (very messy)
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 2476
diff changeset
    45
'~' part will probably expand to 'Documents and Settings/user'.
2c2a9c53aea3 [book/cwctl] reorganize a bit this page (very messy)
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 2476
diff changeset
    46
2c2a9c53aea3 [book/cwctl] reorganize a bit this page (very messy)
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 2476
diff changeset
    47
To create an instance from an existing cube, execute the following
2c2a9c53aea3 [book/cwctl] reorganize a bit this page (very messy)
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 2476
diff changeset
    48
command ::
2c2a9c53aea3 [book/cwctl] reorganize a bit this page (very messy)
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 2476
diff changeset
    49
2c2a9c53aea3 [book/cwctl] reorganize a bit this page (very messy)
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 2476
diff changeset
    50
   cubicweb-ctl create <cube_name> <instance_name>
2c2a9c53aea3 [book/cwctl] reorganize a bit this page (very messy)
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 2476
diff changeset
    51
2c2a9c53aea3 [book/cwctl] reorganize a bit this page (very messy)
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 2476
diff changeset
    52
This command will create the configuration files of an instance in
2c2a9c53aea3 [book/cwctl] reorganize a bit this page (very messy)
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 2476
diff changeset
    53
``~/etc/cubicweb.d/<instance_name>``.
2c2a9c53aea3 [book/cwctl] reorganize a bit this page (very messy)
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 2476
diff changeset
    54
2c2a9c53aea3 [book/cwctl] reorganize a bit this page (very messy)
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 2476
diff changeset
    55
The tool ``cubicweb-ctl`` executes the command ``db-create`` and
2c2a9c53aea3 [book/cwctl] reorganize a bit this page (very messy)
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 2476
diff changeset
    56
``db-init`` when you run ``create`` so that you can complete an
2c2a9c53aea3 [book/cwctl] reorganize a bit this page (very messy)
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 2476
diff changeset
    57
instance creation in a single command. But of course it is possible
2c2a9c53aea3 [book/cwctl] reorganize a bit this page (very messy)
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 2476
diff changeset
    58
to issue these separate commands separately, at a later stage.
2c2a9c53aea3 [book/cwctl] reorganize a bit this page (very messy)
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 2476
diff changeset
    59
2c2a9c53aea3 [book/cwctl] reorganize a bit this page (very messy)
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 2476
diff changeset
    60
Command to create/initialize an instance database
2c2a9c53aea3 [book/cwctl] reorganize a bit this page (very messy)
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 2476
diff changeset
    61
-------------------------------------------------
2c2a9c53aea3 [book/cwctl] reorganize a bit this page (very messy)
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 2476
diff changeset
    62
100
e4d0fd06da7f [doc] Initial translation of cubicweb-tool section.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
    63
* ``db-create``, creates the system database of an instance (tables and
e4d0fd06da7f [doc] Initial translation of cubicweb-tool section.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
    64
  extensions only)
e4d0fd06da7f [doc] Initial translation of cubicweb-tool section.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
    65
* ``db-init``, initializes the system database of an instance
e4d0fd06da7f [doc] Initial translation of cubicweb-tool section.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
    66
  (schema, groups, users, workflows...)
93
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    67
12522
fd64e424fba5 [doc] Update cubicweb-ctl page about how to run an instance
Denis Laxalde <denis.laxalde@logilab.fr>
parents: 11689
diff changeset
    68
Run an instance
fd64e424fba5 [doc] Update cubicweb-ctl page about how to run an instance
Denis Laxalde <denis.laxalde@logilab.fr>
parents: 11689
diff changeset
    69
---------------
4752
2c2a9c53aea3 [book/cwctl] reorganize a bit this page (very messy)
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 2476
diff changeset
    70
12522
fd64e424fba5 [doc] Update cubicweb-ctl page about how to run an instance
Denis Laxalde <denis.laxalde@logilab.fr>
parents: 11689
diff changeset
    71
To start an instance during development, use ::
4752
2c2a9c53aea3 [book/cwctl] reorganize a bit this page (very messy)
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 2476
diff changeset
    72
12522
fd64e424fba5 [doc] Update cubicweb-ctl page about how to run an instance
Denis Laxalde <denis.laxalde@logilab.fr>
parents: 11689
diff changeset
    73
   cubicweb-ctl pyramid [-D] [-l <log-level>] <instance-id>
4752
2c2a9c53aea3 [book/cwctl] reorganize a bit this page (very messy)
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 2476
diff changeset
    74
12522
fd64e424fba5 [doc] Update cubicweb-ctl page about how to run an instance
Denis Laxalde <denis.laxalde@logilab.fr>
parents: 11689
diff changeset
    75
without ``-D``, the instance will be start in the background, as a daemon.
4752
2c2a9c53aea3 [book/cwctl] reorganize a bit this page (very messy)
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 2476
diff changeset
    76
12522
fd64e424fba5 [doc] Update cubicweb-ctl page about how to run an instance
Denis Laxalde <denis.laxalde@logilab.fr>
parents: 11689
diff changeset
    77
See :ref:`cubicweb-ctl_pyramid` for more details.
4752
2c2a9c53aea3 [book/cwctl] reorganize a bit this page (very messy)
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 2476
diff changeset
    78
12522
fd64e424fba5 [doc] Update cubicweb-ctl page about how to run an instance
Denis Laxalde <denis.laxalde@logilab.fr>
parents: 11689
diff changeset
    79
In production, it is recommended to run CubicWeb through a WSGI server like
fd64e424fba5 [doc] Update cubicweb-ctl page about how to run an instance
Denis Laxalde <denis.laxalde@logilab.fr>
parents: 11689
diff changeset
    80
uWSGI or Gunicorn. See :mod:`cubicweb.pyramid` more details.
93
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    81
100
e4d0fd06da7f [doc] Initial translation of cubicweb-tool section.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
    82
Commands to maintain instances
e4d0fd06da7f [doc] Initial translation of cubicweb-tool section.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
    83
------------------------------
4752
2c2a9c53aea3 [book/cwctl] reorganize a bit this page (very messy)
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 2476
diff changeset
    84
100
e4d0fd06da7f [doc] Initial translation of cubicweb-tool section.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
    85
* ``upgrade``, launches the existing instances migration when a new version
2175
16d3c37c5d28 [doc] improvements
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 2172
diff changeset
    86
  of *CubicWeb* or the cubes installed is available
6744
db1e9e733a16 [doc/book] mention that the shell is a python shell
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4936
diff changeset
    87
* ``shell``, opens a (Python based) migration shell for manual maintenance of the instance
100
e4d0fd06da7f [doc] Initial translation of cubicweb-tool section.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
    88
* ``db-dump``, creates a dump of the system database
e4d0fd06da7f [doc] Initial translation of cubicweb-tool section.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
    89
* ``db-restore``, restores a dump of the system database
e4d0fd06da7f [doc] Initial translation of cubicweb-tool section.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
    90
* ``db-check``, checks data integrity of an instance. If the automatic correction
e4d0fd06da7f [doc] Initial translation of cubicweb-tool section.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
    91
  is activated, it is recommanded to create a dump before this operation.
e4d0fd06da7f [doc] Initial translation of cubicweb-tool section.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
    92
* ``schema-sync``, synchronizes the persistent schema of an instance with
2476
1294a6bdf3bf application -> instance where it makes sense
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 2175
diff changeset
    93
  the instance schema. It is recommanded to create a dump before this operation.
93
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    94
100
e4d0fd06da7f [doc] Initial translation of cubicweb-tool section.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
    95
Commands to maintain i18n catalogs
e4d0fd06da7f [doc] Initial translation of cubicweb-tool section.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
    96
----------------------------------
2175
16d3c37c5d28 [doc] improvements
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 2172
diff changeset
    97
* ``i18ncubicweb``, regenerates messages catalogs of the *CubicWeb* library
1898
39b37f90a8a4 [cw-ctl] rename i18n commands (see #342889)
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 1714
diff changeset
    98
* ``i18ncube``, regenerates the messages catalogs of a cube
2172
cf8f9180e63e delete-trailing-whitespace
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 1898
diff changeset
    99
* ``i18ninstance``, recompiles the messages catalogs of an instance.
100
e4d0fd06da7f [doc] Initial translation of cubicweb-tool section.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
   100
  This is automatically done while upgrading.
93
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   101
4936
a4b772a0d801 Fixed some of the documentation warnings when building the book with sphinx.
Adrien Chauve <adrien.chauve@logilab.fr>
parents: 4752
diff changeset
   102
See also chapter :ref:`internationalization`.
93
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   103
100
e4d0fd06da7f [doc] Initial translation of cubicweb-tool section.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
   104
Other commands
e4d0fd06da7f [doc] Initial translation of cubicweb-tool section.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
   105
--------------
e4d0fd06da7f [doc] Initial translation of cubicweb-tool section.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
   106
* ``delete``, deletes an instance (configuration files and database)