Remove Twisted web server
Twisted web server is not used anymore and has been superseded by
pyramid many years ago. Furthermore, our usage is not compatible with
Python 3. So we drop the "etwist" sub-package.
As a consequence, "all-in-one" configuration type gets dropped as it was
Twisted-specific. We resurrect it in cubicweb/pyramid/config.py by only
keeping options used by the "pyramid". Similarly, we introduce a
AllInOneCreateHandler in cubicweb/pyramid/pyramidctl.py that is
basically the one that lived in cubicweb/etwist/twctl.py and is used to
create the "all-in-one" instance. Added a TODO here about "pyramid.ini"
that could be generated at the end of bootstrap() method.
In cubicweb/devtools/httptest.py, CubicWebServerTC is now equivalent to
CubicWebWsgiTC and the latter is dropped.
.. -*- coding: utf-8 -*-
.. _cubicweb-ctl:
``cubicweb-ctl`` tool
=====================
`cubicweb-ctl` is the swiss knife to manage *CubicWeb* instances.
The general syntax is ::
cubicweb-ctl <command> [options command] <arguments commands>
To view available commands ::
cubicweb-ctl
cubicweb-ctl --help
Please note that the commands available depends on the *CubicWeb* packages
and cubes that have been installed.
To view the help menu on specific command ::
cubicweb-ctl <command> --help
Listing available cubes and instance
-------------------------------------
* ``list``, provides a list of the available configuration, cubes
and instances.
Creation of a new cube
-----------------------
Create your new cube cube ::
cubicweb-ctl newcube -d <target directory>
This will create a new cube ``<target directory>``.
Create an instance
-------------------
You must ensure `~/etc/cubicweb.d/` exists prior to this. On windows, the
'~' part will probably expand to 'Documents and Settings/user'.
To create an instance from an existing cube, execute the following
command ::
cubicweb-ctl create <cube_name> <instance_name>
This command will create the configuration files of an instance in
``~/etc/cubicweb.d/<instance_name>``.
The tool ``cubicweb-ctl`` executes the command ``db-create`` and
``db-init`` when you run ``create`` so that you can complete an
instance creation in a single command. But of course it is possible
to issue these separate commands separately, at a later stage.
Command to create/initialize an instance database
-------------------------------------------------
* ``db-create``, creates the system database of an instance (tables and
extensions only)
* ``db-init``, initializes the system database of an instance
(schema, groups, users, workflows...)
Run an instance
---------------
To start an instance during development, use ::
cubicweb-ctl pyramid [-D] [-l <log-level>] <instance-id>
without ``-D``, the instance will be start in the background, as a daemon.
See :ref:`cubicweb-ctl_pyramid` for more details.
In production, it is recommended to run CubicWeb through a WSGI server like
uWSGI or Gunicorn. See :mod:`cubicweb.pyramid` more details.
Commands to maintain instances
------------------------------
* ``upgrade``, launches the existing instances migration when a new version
of *CubicWeb* or the cubes installed is available
* ``shell``, opens a (Python based) migration shell for manual maintenance of the instance
* ``db-dump``, creates a dump of the system database
* ``db-restore``, restores a dump of the system database
* ``db-check``, checks data integrity of an instance. If the automatic correction
is activated, it is recommanded to create a dump before this operation.
* ``schema-sync``, synchronizes the persistent schema of an instance with
the instance schema. It is recommanded to create a dump before this operation.
Commands to maintain i18n catalogs
----------------------------------
* ``i18ncubicweb``, regenerates messages catalogs of the *CubicWeb* library
* ``i18ncube``, regenerates the messages catalogs of a cube
* ``i18ninstance``, recompiles the messages catalogs of an instance.
This is automatically done while upgrading.
See also chapter :ref:`internationalization`.
Other commands
--------------
* ``delete``, deletes an instance (configuration files and database)