doc/book/en/annexes/cubicweb-ctl.rst
branchtls-sprint
changeset 1714 a721966779be
parent 1444 ad182c8e14f7
child 1898 39b37f90a8a4
equal deleted inserted replaced
1499:fd8751c3f3ee 1714:a721966779be
       
     1 .. -*- coding: utf-8 -*-
       
     2 
       
     3 .. _cubicweb-ctl:
       
     4 
       
     5 ``cubicweb-ctl`` tool
       
     6 =====================
       
     7 
       
     8 `cubicweb-ctl` is the swiss knife to manage `CubicWeb` instances.
       
     9 The general syntax is ::
       
    10 
       
    11   cubicweb-ctl <command> [options command] <arguments commands>
       
    12 
       
    13 To view available commands ::
       
    14 
       
    15   cubicweb-ctl
       
    16   cubicweb-ctl --help
       
    17 
       
    18 Please note that the commands available depends on the `CubicWeb` packages
       
    19 and cubes that have been installed.
       
    20 
       
    21 To view the help menu on specific command ::
       
    22 
       
    23   cubicweb-ctl <command> --help
       
    24 
       
    25 Command to create a cube
       
    26 ------------------------
       
    27 
       
    28 * ``newcube``, create a new cube on the file system based on the name
       
    29   given in the parameters. This command create a cube from an application
       
    30   skeleton that includes default files required for debian packaging.
       
    31   
       
    32 
       
    33 Command to create an instance
       
    34 -----------------------------
       
    35 * ``create``, creates the files for the instance configuration
       
    36 * ``db-create``, creates the system database of an instance (tables and
       
    37   extensions only)
       
    38 * ``db-init``, initializes the system database of an instance
       
    39   (schema, groups, users, workflows...)
       
    40 
       
    41 By default, those three commandes are encapsulated in ``create`` so
       
    42 that they can be executed consecutively.
       
    43 
       
    44 Command to create an instance for Google AppEngine datastore source
       
    45 -------------------------------------------------------------------
       
    46 * ``newgapp``, creates the configuration files for an instance
       
    47 
       
    48 This command needs to be followed by the commands responsible for
       
    49 the database initialization. As those are specific to the `datastore`,
       
    50 specific Google AppEgine database, they are not available for now
       
    51 in cubicweb-ctl, but they are available in the instance created.
       
    52 
       
    53 For more details, please see :ref:`gaecontents` .
       
    54 
       
    55 Commands to control instances
       
    56 -----------------------------
       
    57 * ``start``, starts one or more or all instances
       
    58 * ``stop``, stops one or more or all instances
       
    59 * ``restart``, restarts one or more or all instances
       
    60 * ``status``, returns the status of the instance
       
    61 
       
    62 Commands to maintain instances
       
    63 ------------------------------
       
    64 * ``upgrade``, launches the existing instances migration when a new version
       
    65   of `CubicWeb` or the cubes installed is available
       
    66 * ``shell``, opens a migration shell for manual maintenance of the instance
       
    67 * ``db-dump``, creates a dump of the system database
       
    68 * ``db-restore``, restores a dump of the system database
       
    69 * ``db-check``, checks data integrity of an instance. If the automatic correction
       
    70   is activated, it is recommanded to create a dump before this operation.
       
    71 * ``schema-sync``, synchronizes the persistent schema of an instance with
       
    72   the application schema. It is recommanded to create a dump before this operation.
       
    73 
       
    74 Commands to maintain i18n catalogs
       
    75 ----------------------------------
       
    76 * ``i18nlibupdate``, regenerates messages catalogs of the `CubicWeb` library
       
    77 * ``i18nupdate``, regenerates the messages catalogs of a cube
       
    78 * ``i18ncompile``, recompiles the messages catalogs of an instance. 
       
    79   This is automatically done while upgrading.
       
    80 
       
    81 See also chapter :ref:`internationalisation`.
       
    82 
       
    83 Other commands
       
    84 --------------
       
    85 * ``list``, provides a list of the available configuration, cubes
       
    86   and instances.
       
    87 * ``delete``, deletes an instance (configuration files and database)
       
    88 
       
    89 
       
    90 Create an instance from an existing cube
       
    91 ````````````````````````````````````````
       
    92 
       
    93 To create an instance from an existing cube, execute the following
       
    94 command ::
       
    95 
       
    96    cubicweb-ctl create <cube_name> <instance_name>
       
    97 
       
    98 This command will create the configuration files of an instance in
       
    99 ``~/etc/cubicweb.d/<instance_name>``.
       
   100 The tool ``cubicweb-ctl`` allows you to execute the command ``db-create``
       
   101 and ``db-init`` when you run ``create`` so that you can complete an
       
   102 instance creation in a single command.
       
   103 
       
   104 If you decide not to execut those commands while ``cubicweb-ctl create``,
       
   105 then you will have to execute them seperately(``cubicweb-ctl db-create``,
       
   106 ``cubicweb-ctl db-init`` ) otherwise your installation will not be complete
       
   107 and you will not be able to launch your instance.
       
   108 
       
   109 
       
   110 Creation of an instance from a new cube
       
   111 ```````````````````````````````````````
       
   112 
       
   113 Create first your new cube cube ::
       
   114 
       
   115    cubicweb-ctl newcube <mycube>
       
   116 
       
   117 This will create a new cube in ``/path/to/forest/cubicweb/cubes/<mycube>``
       
   118 for a Mercurial forest installation, or in ``/usr/share/cubicweb/cubes``
       
   119 for a debian packages installation, and then create an instance as 
       
   120 explained just above.
       
   121 
       
   122