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