diff --git a/doc/reference/index.rst b/doc/reference/index.rst index a470f2629a..e21c08b3b9 100644 --- a/doc/reference/index.rst +++ b/doc/reference/index.rst @@ -18,5 +18,6 @@ Reference ../dev_guide/internals/index ../book/box/limitations interactive_console + tt_cli/index tarantoolctl lua_tips diff --git a/doc/reference/tt_cli/arguments.rst b/doc/reference/tt_cli/arguments.rst new file mode 100644 index 0000000000..74790acd11 --- /dev/null +++ b/doc/reference/tt_cli/arguments.rst @@ -0,0 +1,35 @@ +Arguments +========= + +``tt`` has the following arguments: + +.. container:: table + + .. list-table:: + :widths: 40 60 + :header-rows: 0 + + * - ``--cfg=FILE`` + + ``-c=FILE`` + - Path to the :ref:`configuration file `. + * - ``--internal`` + + ``-i`` + - Force the use of an internal module even if there is an external module with the same name. + + .. // TODO: add link to external modules doc page when it's ready + * - ``--local=DIRECTORY`` + + ``-L=DIRECTORY`` + - Use the ``tt`` environment from the specified directory. + Learn more about the :ref:`local launch mode `. + * - ``--system`` + + ``-S`` + - Use the ``tt`` environment installed in the system. + Learn more about the :ref:`system launch mode `. + * - ``--help`` + + ``-h`` + - Display help. \ No newline at end of file diff --git a/doc/reference/tt_cli/commands.rst b/doc/reference/tt_cli/commands.rst new file mode 100644 index 0000000000..b99b83fe1e --- /dev/null +++ b/doc/reference/tt_cli/commands.rst @@ -0,0 +1,38 @@ +Commands +======== + +Below is a list of `tt` commands. Run ``tt COMMAND help`` to see the detailed +help for the given command. + +.. container:: table + + .. list-table:: + :widths: 30 70 + :header-rows: 0 + + * - ``start`` + - Start a Tarantool :ref:`instance ` + * - ``stop`` + - Stop a Tarantool instance + * - ``status`` + - Get the current status of a Tarantool instance + * - ``restart`` + - Restart a Tarantool instance + * - ``version`` + - Show the ``tt`` version information + * - ``completion`` + - Generate autocompletion for a specified shell + * - ``help`` + - Display help for ``tt`` or a specific command + * - ``logrotate`` + - :ref:`Rotate logs ` + * - ``check`` + - Check an application file for syntax errors + * - ``connect`` + - Connect to a Tarantool instance + * - ``rocks`` + - Use the LuaRocks package manager + * - ``cat`` + - Print the contents of ``.snap`` or ``.xlog`` files into stdout + * - ``play`` + - Play the contents of ``.snap`` or ``.xlog`` files to another Tarantool instance \ No newline at end of file diff --git a/doc/reference/tt_cli/configuration.rst b/doc/reference/tt_cli/configuration.rst new file mode 100644 index 0000000000..07aee78d71 --- /dev/null +++ b/doc/reference/tt_cli/configuration.rst @@ -0,0 +1,107 @@ +Configuration +============= + +.. _tt-config_file: + +Configuration file +------------------ + +The key artifact that defines the ``tt`` environment and various aspects of its +execution is its configuration file. + +By default, the configuration file is called ``tarantool.yaml``. The location +where ``tt`` searches for it depends on the :ref:`launch mode `. +You can also pass the configuration file explicitly in the ``--cfg`` +:doc:`argument `. + +The ``tt`` configuration file is a YAML file with the following content: + +.. code:: yaml + + tt: + modules: + directory: path/to/modules/dir + app: + instances_available: path/to/available/applications + run_dir: path/to/run_dir + log_dir: path/to/log_dir + log_maxsize: num (MB) + log_maxage: num (days) + log_maxbackups: num + restart_on_failure: bool + +modules section +~~~~~~~~~~~~~~~ + +* ``directory`` -- the directory where external modules are stored. +.. // TODO: add link to external modules doc page when it's ready + +app section +~~~~~~~~~~~ + +* ``instances_available`` -- the directory where :ref:`instances ` + are stored. +* ``run_dir``-- the directory for instance runtime artifacts, such as console + sockets or PID files. +* ``log_dir`` -- the directory where log files are stored. +* ``log_maxsize`` -- the maximum size of the log file before it gets rotated, + in megabytes. Default: 100. +* ``log_maxage`` -- the maximum age of log files in days. The age of a log + file is defined by the timestamp encoded in its name. Default: not defined + (log files aren't deleted based on their age). + + .. note:: + + A day is defined as exactly 24 hours. It may not exactly correspond to + calendar days due to daylight savings, leap seconds, and other time adjustments. + +* ``log_maxbackups`` -- the maximum number of stored log files. + Default: not defined (log files aren't deleted based on their count). +* ``restart_on_failure`` -- restart the instance on failure: ``true`` or ``false``. + Default: ``false``. + +.. _tt-config_modes: + +Launch modes +------------ + +``tt`` launch mode defines its working directory and the way it searches for the +configuration file. There are three launch modes: + +* default +* system +* local + +Default launch +~~~~~~~~~~~~~~ + +**Argument**: none + +**Configuration file**: searched from the current directory to the root. +Taken from ``/etc/tarantool`` if the file is not found. + +**Working directory**: The directory where the configuration file is found. + +.. _tt-config_modes-system: + +System launch +~~~~~~~~~~~~~ + +**Argument**: ``--system`` or ``-S`` + +**Configuration file**: Taken from ``/etc/tarantool``. + +**Working directory**: Current directory. + +.. _tt-config_modes-local: + +Local launch +~~~~~~~~~~~~ + +**Argument**: ``--local=DIRECTORY`` or ``-L=DIRECTORY`` + +**Configuration file**: Searched from the specified directory to the root. +Taken from ``/etc/tarantool`` if the file is not found. + +**Working directory**: The specified directory. If ``tarantool`` or ``tt`` +executable files are found in the working directory, they will be used. \ No newline at end of file diff --git a/doc/reference/tt_cli/index.rst b/doc/reference/tt_cli/index.rst new file mode 100644 index 0000000000..a7696350a7 --- /dev/null +++ b/doc/reference/tt_cli/index.rst @@ -0,0 +1,28 @@ +tt CLI utility +============== + +``tt`` is a utility that provides a unified command-line interface for managing +Tarantool-based applications. It covers a wide range of tasks -- from installing +a specific Tarantool version to managing remote instances and developing applications. + +A multi-purpose tool for working with Tarantool from the command line, ``tt`` is +a potential replacement for :doc:`tarantoolctl ` +and :doc:`Cartridge CLI `. + +.. warning:: + + As of Tarantool 2.10, ``tt`` is in the early development stage. It includes + only basic functionality and may be unstable. We don't recommend using it + in production environments. Check out the list of :doc:`supported commands `. + + To use ``tt``, you need to build it from sources. + See :doc:`Installation ` for details. + +.. toctree:: + :maxdepth: 1 + :numbered: 0 + + installation + configuration + arguments + commands \ No newline at end of file diff --git a/doc/reference/tt_cli/installation.rst b/doc/reference/tt_cli/installation.rst new file mode 100644 index 0000000000..6c50b46035 --- /dev/null +++ b/doc/reference/tt_cli/installation.rst @@ -0,0 +1,36 @@ +Installation +============ + +To install the ``tt`` command-line utility: + +1. Install third-party software required for building ``tt``: + + * `git `__, + the version control system. + * `Go language `__, version 1.18 or later. + * `mage `__ build tool. + +2. Clone the `tarantool/tt `_ repository: + + .. code-block:: bash + + git clone https://github.com/tarantool/tt --recursive + +3. Go to the ``tt/`` directory and build ``tt`` using mage: + + .. code-block:: bash + + cd tt + mage build + +``tt`` will appear in the current directory. + +Enabling shell completion +------------------------- + +To enable the completion for ``tt`` commands, run the following command specifying +the shell (``bash`` or ``zsh``): + +.. code-block:: bash + + . <(tt completion bash) \ No newline at end of file