From a3bfea2a8754b033da3f7d61b992ba769965a635 Mon Sep 17 00:00:00 2001 From: Pavel Semyonov Date: Wed, 27 Sep 2023 16:53:27 +0700 Subject: [PATCH 1/8] Use tt in start_stop_instance.rst --- doc/book/admin/start_stop_instance.rst | 250 +++++++++-------------- doc/reference/tooling/tarantoolctl.rst | 216 +++++++++++++++++++- doc/reference/tooling/tt_cli/index.rst | 2 + doc/reference/tooling/tt_cli/restart.rst | 11 +- 4 files changed, 316 insertions(+), 163 deletions(-) diff --git a/doc/book/admin/start_stop_instance.rst b/doc/book/admin/start_stop_instance.rst index 6e0dfbdf07..14112cbcc9 100644 --- a/doc/book/admin/start_stop_instance.rst +++ b/doc/book/admin/start_stop_instance.rst @@ -1,214 +1,146 @@ .. _admin-start_stop_instance: -================================================================================ -Starting/stopping an instance -================================================================================ +Starting and stopping instances +=============================== -While a Lua application is executed by Tarantool, an instance file is executed -by ``tarantoolctl`` which is a Tarantool script. +Starting an instance +-------------------- -Here is what ``tarantoolctl`` does when you issue the command: +To start a Tarantool instance from an :ref:`instance file ` +using the :ref:`tt ` utility: -.. code-block:: console - - $ tarantoolctl start - -1. Read and parse the command line arguments. The last argument, in our case, - contains an instance name. - -2. Read and parse its own configuration file. This file contains ``tarantoolctl`` - defaults, like the path to the directory where instances should be searched - for. +1. Place the instance file into ``/etc/tarantool/instances.enabled/``. This is + the default location where ``tt`` searches for instance files. - When ``tarantool`` is invoked by root, it looks for a configuration file in - ``/etc/default/tarantool``. When ``tarantool`` is invoked by a local (non-root) - user, it looks for a configuration file first in the current directory - (``$PWD/.tarantoolctl``), and then in the current user's home directory - (``$HOME/.config/tarantool/tarantool``). If no configuration file is found - there, or in the ``/usr/local/etc/default/tarantool`` file, - then ``tarantoolctl`` falls back to - :ref:`built-in defaults `. +2. Run ``tt start``: -3. Look up the instance file in the instance directory, for example - ``/etc/tarantool/instances.enabled``. To build the instance file path, - ``tarantoolctl`` takes the instance name, prepends the instance directory and - appends ".lua" extension to the instance file. + .. code-block:: console -4. Override :doc:`box.cfg{} ` function to pre-process - its parameters and ensure that instance paths are pointing to the paths - defined in the ``tarantoolctl`` configuration file. For example, if the - configuration file specifies that instance work directory must be in - ``/var/tarantool``, then the new implementation of ``box.cfg{}`` ensures that - :ref:`work_dir ` parameter in ``box.cfg{}`` is set to - ``/var/tarantool/``, regardless of what the path is set to in - the instance file itself. + $ tt start + • Starting an instance [my_app]... -5. Create a so-called "instance control file". This is a Unix socket with Lua - console attached to it. This file is used later by ``tarantoolctl`` to query - the instance state, send commands to the instance and so on. +In this case, ``tt`` starts an instance from any ``*.lua`` file it finds in ``/etc/tarantool/instances.enabled/``. +If there are several Lua files, ``tt`` starts a separate instance for each of them. +Learn more about working with multiple Tarantool instances in +:ref:`Managing multiple instances `. -6. Set the TARANTOOLCTL environment variable to 'true'. This allows the user to - know that the instance was started by ``tarantoolctl``. - -7. Finally, use Lua ``dofile`` command to execute the instance file. - -If you start an instance using ``systemd`` tools, like this (the instance name -is ``my_app``): +To select a specific instance to start, specify its name in the ``tt start`` argument: .. code-block:: console - $ systemctl start tarantool@my_app - $ ps axuf|grep my_app - taranto+ 5350 1.3 0.3 1448872 7736 ? Ssl 20:05 0:28 tarantool my_app.lua + $ tt start my_app + • Starting an instance [my_app]... -... this actually calls ``tarantoolctl`` like in case of -``tarantoolctl start my_app``. +When starting an instance, ``tt`` uses its :ref:`configuration file ` +``tt.yaml`` to set up a :ref:`tt environment ` in which the instance runs. +The default ``tt`` configuration file is created automatically in ``/etc/tarantool/`. +Learn how to set up a ``tt`` environment in a directory of your choice in +:ref:`Running Tarantool locally `. -To check the instance file for syntax errors prior to starting ``my_app`` -instance, say: +After the instance has started and worked for some time, you can find its artifacts +in the directories specified in the ``tt`` configuration. These are the default +locations: -.. code-block:: console +* ``/var/log/tarantool/.log`` -- instance :ref:`logs ` +* ``/var/lib/tarantool//`` -- snapshots and write-ahead logs +* ``/var/run/tarantool/.control`` and ``/var/run/tarantool/.pid`` + -- control socket and PID file - $ tarantoolctl check my_app +Basic instance management +------------------------- -To enable ``my_app`` instance for auto-load during system startup, say: +``tt`` provides a set of commands for performing basic operations over instances: -.. code-block:: console +* ``tt check`` -- check the instance file for syntax errors: - $ systemctl enable tarantool@my_app + .. code-block:: console -To stop a running ``my_app`` instance, say: + $ tt check my_app + • Result of check: syntax of file '/etc/tarantool/instances.enabled/my_app.lua' is OK -.. code-block:: console +* ``tt status`` -- check the instance's status: - $ tarantoolctl stop my_app - $ # - OR - - $ systemctl stop tarantool@my_app + .. code-block:: console -To restart (i.e. stop and start) a running ``my_app`` instance, say: + $ tt status my_app + INSTANCE STATUS PID + my_app NOT RUNNING -.. code-block:: console +* ``tt restart`` -- restart the instance (the ``-y`` option responds "yes" + to confirmation prompt automatically): - $ tarantoolctl restart my_app - $ # - OR - - $ systemctl restart tarantool@my_app + .. code-block:: console -.. _admin-start_stop_instance-running_locally: + $ tt restart my_app -y + • The Instance my_app (PID = 729) has been terminated. + • Starting an instance [my_app]... --------------------------------------------------------------------------------- -Running Tarantool locally --------------------------------------------------------------------------------- +* ``tt stop`` -- stop the instance: -Sometimes you may need to run a Tarantool instance locally, e.g. for test -purposes. Let's configure a local instance, then start and monitor it with -``tarantoolctl``. - -First, we create a sandbox directory on the user's path: - -.. code-block:: console + .. code-block:: console - $ mkdir ~/tarantool_test + $ tt stop my_app + • The Instance my_app (PID = 639) has been terminated. -... and set default ``tarantoolctl`` configuration in -``$HOME/.config/tarantool/tarantool``. Let the file contents be: +* ``tt clean`` -- remove instance artifacts: logs, snapshots, an other files. -.. code-block:: lua + .. code-block:: console - default_cfg = { - pid_file = "/home/user/tarantool_test/my_app.pid", - wal_dir = "/home/user/tarantool_test", - snap_dir = "/home/user/tarantool_test", - vinyl_dir = "/home/user/tarantool_test", - log = "/home/user/tarantool_test/log", - } - instance_dir = "/home/user/tarantool_test" + $ tt clean my_app -f + • List of files to delete: -.. NOTE:: + • /var/log/tarantool/my_app.log + • /var/lib/tarantool/my_app/00000000000000000000.snap + • /var/lib/tarantool/my_app/00000000000000000000.xlog - * Specify a full path to the user's home directory instead of "~/". - * Omit ``username`` parameter. ``tarantoolctl`` normally doesn't have - permissions to switch current user when invoked by a local user. The - instance will be running under 'admin'. +These commands can be called without an instance name. In this case, they are +executed for all instances from ``instances.enabled``. -Next, we create the instance file ``~/tarantool_test/my_app.lua``. Let the file -contents be: - -.. code-block:: lua - - box.cfg{listen = 3301} - box.schema.user.passwd('Gx5!') - box.schema.user.grant('guest','read,write,execute','universe') - fiber = require('fiber') - box.schema.space.create('tester') - box.space.tester:create_index('primary',{}) - i = 0 - while 0 == 0 do - fiber.sleep(5) - i = i + 1 - print('insert ' .. i) - box.space.tester:insert{i, 'my_app tuple'} - end - -Let’s verify our instance file by starting it without ``tarantoolctl`` first: - -.. code-block:: console - - $ cd ~/tarantool_test - $ tarantool my_app.lua - 2017-04-06 10:42:15.762 [54085] main/101/my_app.lua C> version 1.7.3-489-gd86e36d5b - 2017-04-06 10:42:15.763 [54085] main/101/my_app.lua C> log level 5 - 2017-04-06 10:42:15.764 [54085] main/101/my_app.lua I> mapping 268435456 bytes for tuple arena... - 2017-04-06 10:42:15.774 [54085] iproto/101/main I> binary: bound to [::]:3301 - 2017-04-06 10:42:15.774 [54085] main/101/my_app.lua I> initializing an empty data directory - 2017-04-06 10:42:15.789 [54085] snapshot/101/main I> saving snapshot `./00000000000000000000.snap.inprogress' - 2017-04-06 10:42:15.790 [54085] snapshot/101/main I> done - 2017-04-06 10:42:15.791 [54085] main/101/my_app.lua I> vinyl checkpoint done - 2017-04-06 10:42:15.791 [54085] main/101/my_app.lua I> ready to accept requests - insert 1 - insert 2 - insert 3 - <...> - -Now we tell ``tarantoolctl`` to start the Tarantool instance: - -.. code-block:: console +.. _admin-start_stop_instance-running_locally: - $ tarantoolctl start my_app +Running Tarantool locally +------------------------- -Expect to see messages indicating that the instance has started. Then: +Sometimes you may need to run a Tarantool instance locally,for example, for test +purposes. ``tt`` runs in a local environment if it finds a ``tt.yaml`` configuration +file in the current directory or any of its enclosing directories. +To force ``tt`` into the local mode, add the ``-L`` or ``--local`` argument. -.. code-block:: console +To set up a local environment for ``tt``: - $ ls -l ~/tarantool_test/my_app +1. Create a home directory for the environment. -Expect to see the .snap file and the .xlog file. Then: +2. Run ``tt init`` in this directory: -.. code-block:: console + .. code-block:: console - $ less ~/tarantool_test/log/my_app.log + $ tt init + • Environment config is written to 'tt.yaml' -Expect to see the contents of ``my_app``‘s log, including error messages, if -any. Then: +This command creates a default ``tt`` configuration file ``tt.yaml`` and the +required directories for instance files, control sockets, logs, and other Tarantool +artifacts: .. code-block:: console - $ tarantoolctl enter my_app - tarantool> box.cfg{} - tarantool> console = require('console') - tarantool> console.connect('localhost:3301') - tarantool> box.space.tester:select({0}, {iterator = 'GE'}) + $ ls + bin distfiles include instances.enabled modules templates tt.yaml -Expect to see several tuples that ``my_app`` has created. +To run a Tarantool instance in the local environment: -Stop now. A polite way to stop ``my_app`` is with ``tarantoolctl``, thus we say: +1. Place the instance file into the ``instances.enabled/`` directory inside the + current directory. -.. code-block:: console +2. Run ``tt start``: - $ tarantoolctl stop my_app + .. code-block:: console -Finally, we make a cleanup. + $ tt start -.. code-block:: console +After the instance is started, you can find its artifacts in their locations inside +the current directory: - $ rm -R tarantool_test +* logs in ``var/log/`` +* snapshots and write-ahead logs in ``var/lib/`` +* control sockets in ``var/run/`` \ No newline at end of file diff --git a/doc/reference/tooling/tarantoolctl.rst b/doc/reference/tooling/tarantoolctl.rst index 19da71f1b2..5580024d4a 100644 --- a/doc/reference/tooling/tarantoolctl.rst +++ b/doc/reference/tooling/tarantoolctl.rst @@ -1,6 +1,6 @@ .. _tarantoolctl: -Utility tarantoolctl (deprecated) +tarantoolctl utility (deprecated) ================================= .. important:: @@ -320,7 +320,6 @@ files after they were moved by the program of your choice. Using tarantooctl on FreeBSD ---------------------------- - To make ``tarantoolctl`` work along with ``init.d`` utilities on FreeBSD, use paths other than those suggested in :ref:`Instance configuration `. Instead of @@ -348,6 +347,219 @@ Here is an example of ``tarantoolctl`` defaults on FreeBSD: -- instances.enabled - instances to autostart by sysvinit instance_dir = "/usr/local/etc/tarantool/instances.available" +.. _tarantooctl-start_stop_instance: + +Starting and stopping instances +------------------------------- + +While a Lua application is executed by Tarantool, an instance file is executed +by ``tarantoolctl`` which is a Tarantool script. + +Here is what ``tarantoolctl`` does when you issue the command: + +.. code-block:: console + + $ tarantoolctl start + +1. Read and parse the command line arguments. The last argument, in our case, + contains an instance name. + +2. Read and parse its own configuration file. This file contains ``tarantoolctl`` + defaults, like the path to the directory where instances should be searched + for. + + When ``tarantool`` is invoked by root, it looks for a configuration file in + ``/etc/default/tarantool``. When ``tarantool`` is invoked by a local (non-root) + user, it looks for a configuration file first in the current directory + (``$PWD/.tarantoolctl``), and then in the current user's home directory + (``$HOME/.config/tarantool/tarantool``). If no configuration file is found + there, or in the ``/usr/local/etc/default/tarantool`` file, + then ``tarantoolctl`` falls back to + :ref:`built-in defaults `. + +3. Look up the instance file in the instance directory, for example + ``/etc/tarantool/instances.enabled``. To build the instance file path, + ``tarantoolctl`` takes the instance name, prepends the instance directory and + appends ".lua" extension to the instance file. + +4. Override :doc:`box.cfg{} ` function to pre-process + its parameters and ensure that instance paths are pointing to the paths + defined in the ``tarantoolctl`` configuration file. For example, if the + configuration file specifies that instance work directory must be in + ``/var/tarantool``, then the new implementation of ``box.cfg{}`` ensures that + :ref:`work_dir ` parameter in ``box.cfg{}`` is set to + ``/var/tarantool/``, regardless of what the path is set to in + the instance file itself. + +5. Create a so-called "instance control file". This is a Unix socket with Lua + console attached to it. This file is used later by ``tarantoolctl`` to query + the instance state, send commands to the instance and so on. + +6. Set the TARANTOOLCTL environment variable to 'true'. This allows the user to + know that the instance was started by ``tarantoolctl``. + +7. Finally, use Lua ``dofile`` command to execute the instance file. + +If you start an instance using ``systemd`` tools, like this (the instance name +is ``my_app``): + +.. code-block:: console + + $ systemctl start tarantool@my_app + $ ps axuf|grep my_app + taranto+ 5350 1.3 0.3 1448872 7736 ? Ssl 20:05 0:28 tarantool my_app.lua + +... this actually calls ``tarantoolctl`` like in case of +``tarantoolctl start my_app``. + +To check the instance file for syntax errors prior to starting ``my_app`` +instance, say: + +.. code-block:: console + + $ tarantoolctl check my_app + +To enable ``my_app`` instance for auto-load during system startup, say: + +.. code-block:: console + + $ systemctl enable tarantool@my_app + +To stop a running ``my_app`` instance, say: + +.. code-block:: console + + $ tarantoolctl stop my_app + $ # - OR - + $ systemctl stop tarantool@my_app + +To restart (i.e. stop and start) a running ``my_app`` instance, say: + +.. code-block:: console + + $ tarantoolctl restart my_app + $ # - OR - + $ systemctl restart tarantool@my_app + +.. _tarantoolctl-start_stop_instance-running_locally: + +Running Tarantool locally +~~~~~~~~~~~~~~~~~~~~~~~~~ + +Sometimes you may need to run a Tarantool instance locally, e.g. for test +purposes. Let's configure a local instance, then start and monitor it with +``tarantoolctl``. + +First, we create a sandbox directory on the user's path: + +.. code-block:: console + + $ mkdir ~/tarantool_test + +... and set default ``tarantoolctl`` configuration in +``$HOME/.config/tarantool/tarantool``. Let the file contents be: + +.. code-block:: lua + + default_cfg = { + pid_file = "/home/user/tarantool_test/my_app.pid", + wal_dir = "/home/user/tarantool_test", + snap_dir = "/home/user/tarantool_test", + vinyl_dir = "/home/user/tarantool_test", + log = "/home/user/tarantool_test/log", + } + instance_dir = "/home/user/tarantool_test" + +.. NOTE:: + + * Specify a full path to the user's home directory instead of "~/". + + * Omit ``username`` parameter. ``tarantoolctl`` normally doesn't have + permissions to switch current user when invoked by a local user. The + instance will be running under 'admin'. + +Next, we create the instance file ``~/tarantool_test/my_app.lua``. Let the file +contents be: + +.. code-block:: lua + + box.cfg{listen = 3301} + box.schema.user.passwd('Gx5!') + box.schema.user.grant('guest','read,write,execute','universe') + fiber = require('fiber') + box.schema.space.create('tester') + box.space.tester:create_index('primary',{}) + i = 0 + while 0 == 0 do + fiber.sleep(5) + i = i + 1 + print('insert ' .. i) + box.space.tester:insert{i, 'my_app tuple'} + end + +Let’s verify our instance file by starting it without ``tarantoolctl`` first: + +.. code-block:: console + + $ cd ~/tarantool_test + $ tarantool my_app.lua + 2017-04-06 10:42:15.762 [54085] main/101/my_app.lua C> version 1.7.3-489-gd86e36d5b + 2017-04-06 10:42:15.763 [54085] main/101/my_app.lua C> log level 5 + 2017-04-06 10:42:15.764 [54085] main/101/my_app.lua I> mapping 268435456 bytes for tuple arena... + 2017-04-06 10:42:15.774 [54085] iproto/101/main I> binary: bound to [::]:3301 + 2017-04-06 10:42:15.774 [54085] main/101/my_app.lua I> initializing an empty data directory + 2017-04-06 10:42:15.789 [54085] snapshot/101/main I> saving snapshot `./00000000000000000000.snap.inprogress' + 2017-04-06 10:42:15.790 [54085] snapshot/101/main I> done + 2017-04-06 10:42:15.791 [54085] main/101/my_app.lua I> vinyl checkpoint done + 2017-04-06 10:42:15.791 [54085] main/101/my_app.lua I> ready to accept requests + insert 1 + insert 2 + insert 3 + <...> + +Now we tell ``tarantoolctl`` to start the Tarantool instance: + +.. code-block:: console + + $ tarantoolctl start my_app + +Expect to see messages indicating that the instance has started. Then: + +.. code-block:: console + + $ ls -l ~/tarantool_test/my_app + +Expect to see the .snap file and the .xlog file. Then: + +.. code-block:: console + + $ less ~/tarantool_test/log/my_app.log + +Expect to see the contents of ``my_app``‘s log, including error messages, if +any. Then: + +.. code-block:: console + + $ tarantoolctl enter my_app + tarantool> box.cfg{} + tarantool> console = require('console') + tarantool> console.connect('localhost:3301') + tarantool> box.space.tester:select({0}, {iterator = 'GE'}) + +Expect to see several tuples that ``my_app`` has created. + +Stop now. A polite way to stop ``my_app`` is with ``tarantoolctl``, thus we say: + +.. code-block:: console + + $ tarantoolctl stop my_app + +Finally, we make a cleanup. + +.. code-block:: console + + $ rm -R tarantool_test + .. _tarantoolctl-migration-to-tt: Migration from tarantoolctl to tt diff --git a/doc/reference/tooling/tt_cli/index.rst b/doc/reference/tooling/tt_cli/index.rst index e79e38a9b8..23f7b285bf 100644 --- a/doc/reference/tooling/tt_cli/index.rst +++ b/doc/reference/tooling/tt_cli/index.rst @@ -24,6 +24,8 @@ concept explanation, and the ``tt`` command reference. external_modules multiple_instances +.. _tt-cli-environments: + tt environments --------------- diff --git a/doc/reference/tooling/tt_cli/restart.rst b/doc/reference/tooling/tt_cli/restart.rst index 0000137561..418958bf5f 100644 --- a/doc/reference/tooling/tt_cli/restart.rst +++ b/doc/reference/tooling/tt_cli/restart.rst @@ -11,12 +11,19 @@ Restarting a Tarantool instance A ``tt restart`` call is equivalent to consecutive calls of :doc:`tt stop ` and :doc:`tt start `. +Options +------- + +.. option:: -y, --yes + + Automatic "Yes" to confirmation prompt. + Examples -------- -Restart the ``app`` instance: +Restart the ``app`` instance with automatic confirmation: .. code-block:: bash - tt restart app + tt restart app -y From d947a49005394b2dbf9a8844d49cc6830fc5323f Mon Sep 17 00:00:00 2001 From: Pavel Semyonov Date: Wed, 27 Sep 2023 17:29:33 +0700 Subject: [PATCH 2/8] Use tt in start_stop_instance.rst --- doc/book/admin/start_stop_instance.rst | 88 +++++++++++++++++++------- doc/reference/tooling/tarantoolctl.rst | 22 ------- 2 files changed, 66 insertions(+), 44 deletions(-) diff --git a/doc/book/admin/start_stop_instance.rst b/doc/book/admin/start_stop_instance.rst index 14112cbcc9..e4ae3b8125 100644 --- a/doc/book/admin/start_stop_instance.rst +++ b/doc/book/admin/start_stop_instance.rst @@ -3,14 +3,11 @@ Starting and stopping instances =============================== -Starting an instance --------------------- - To start a Tarantool instance from an :ref:`instance file ` using the :ref:`tt ` utility: -1. Place the instance file into ``/etc/tarantool/instances.enabled/``. This is - the default location where ``tt`` searches for instance files. +1. Place the instance file (for example, ``my_app.lua``) into ``/etc/tarantool/instances.enabled/``. + This is the default location where ``tt`` searches for instance files. 2. Run ``tt start``: @@ -21,10 +18,12 @@ using the :ref:`tt ` utility: In this case, ``tt`` starts an instance from any ``*.lua`` file it finds in ``/etc/tarantool/instances.enabled/``. If there are several Lua files, ``tt`` starts a separate instance for each of them. +All the instance files or directories placed in this directory are called +*enabled instances*. Learn more about working with multiple Tarantool instances in :ref:`Managing multiple instances `. -To select a specific instance to start, specify its name in the ``tt start`` argument: +To start a specific enabled instance to start, specify its name in the ``tt start`` argument: .. code-block:: console @@ -33,18 +32,22 @@ To select a specific instance to start, specify its name in the ``tt start`` arg When starting an instance, ``tt`` uses its :ref:`configuration file ` ``tt.yaml`` to set up a :ref:`tt environment ` in which the instance runs. -The default ``tt`` configuration file is created automatically in ``/etc/tarantool/`. +The default ``tt`` configuration file is created automatically in ``/etc/tarantool/``. Learn how to set up a ``tt`` environment in a directory of your choice in :ref:`Running Tarantool locally `. + After the instance has started and worked for some time, you can find its artifacts in the directories specified in the ``tt`` configuration. These are the default locations: * ``/var/log/tarantool/.log`` -- instance :ref:`logs ` * ``/var/lib/tarantool//`` -- snapshots and write-ahead logs -* ``/var/run/tarantool/.control`` and ``/var/run/tarantool/.pid`` - -- control socket and PID file +* ``/var/run/tarantool/.control`` -- control socket. This is + a Unix socket with Lua console attached to it. This file is used to connect + to the instance console. +* ``/var/run/tarantool/.pid`` -- PID file that ``tt`` uses to + check the instance status and send control commands. Basic instance management ------------------------- @@ -66,23 +69,26 @@ Basic instance management INSTANCE STATUS PID my_app NOT RUNNING -* ``tt restart`` -- restart the instance (the ``-y`` option responds "yes" - to confirmation prompt automatically): +* ``tt restart`` -- restart the instance: .. code-block:: console - $ tt restart my_app -y - • The Instance my_app (PID = 729) has been terminated. - • Starting an instance [my_app]... + $ tt restart my_app -y + • The Instance my_app (PID = 729) has been terminated. + • Starting an instance [my_app]... + + .. note:: + + The ``-y`` option responds "yes" to confirmation prompt automatically. * ``tt stop`` -- stop the instance: .. code-block:: console - $ tt stop my_app - • The Instance my_app (PID = 639) has been terminated. + $ tt stop my_app + • The Instance my_app (PID = 639) has been terminated. -* ``tt clean`` -- remove instance artifacts: logs, snapshots, an other files. +* ``tt clean`` -- remove instance artifacts: logs, snapshots, an other files. .. code-block:: console @@ -93,16 +99,19 @@ Basic instance management • /var/lib/tarantool/my_app/00000000000000000000.snap • /var/lib/tarantool/my_app/00000000000000000000.xlog + .. note:: + + The ``-f`` option removes the files without confirmation. These commands can be called without an instance name. In this case, they are -executed for all instances from ``instances.enabled``. +executed for all enabled instances. .. _admin-start_stop_instance-running_locally: Running Tarantool locally ------------------------- -Sometimes you may need to run a Tarantool instance locally,for example, for test +Sometimes you may need to run a Tarantool instance locally, for example, for test purposes. ``tt`` runs in a local environment if it finds a ``tt.yaml`` configuration file in the current directory or any of its enclosing directories. To force ``tt`` into the local mode, add the ``-L`` or ``--local`` argument. @@ -118,8 +127,8 @@ To set up a local environment for ``tt``: $ tt init • Environment config is written to 'tt.yaml' -This command creates a default ``tt`` configuration file ``tt.yaml`` and the -required directories for instance files, control sockets, logs, and other Tarantool +This command creates a default ``tt`` configuration file ``tt.yaml`` for a local +environment and the directories for instance files, control sockets, logs, and other artifacts: .. code-block:: console @@ -143,4 +152,39 @@ the current directory: * logs in ``var/log/`` * snapshots and write-ahead logs in ``var/lib/`` -* control sockets in ``var/run/`` \ No newline at end of file +* control sockets and PID files in ``var/run/`` + +.. _admin-start_stop_instance-systemd: + +Using systemd tools +------------------- + +If you start an instance using ``systemd`` tools, like this (the instance name +is ``my_app``): + +.. code-block:: console + + $ systemctl start tarantool@my_app + $ ps axuf|grep my_app + taranto+ 5350 1.3 0.3 1448872 7736 ? Ssl 20:05 0:28 tarantool my_app.lua + +This actually calls ``tarantoolctl`` like in case of +``tarantoolctl start my_app``. + +To enable ``my_app`` instance for auto-load during system startup, say: + +.. code-block:: console + + $ systemctl enable tarantool@my_app + +To stop a running ``my_app`` instance with ``systemctl``, run: + +.. code-block:: console + + $ systemctl stop tarantool@my_app + +To restart a running ``my_app`` instance with ``systemctl``, run: + +.. code-block:: console + + $ systemctl restart tarantool@my_app \ No newline at end of file diff --git a/doc/reference/tooling/tarantoolctl.rst b/doc/reference/tooling/tarantoolctl.rst index 5580024d4a..a3afa72bfe 100644 --- a/doc/reference/tooling/tarantoolctl.rst +++ b/doc/reference/tooling/tarantoolctl.rst @@ -400,18 +400,6 @@ Here is what ``tarantoolctl`` does when you issue the command: 7. Finally, use Lua ``dofile`` command to execute the instance file. -If you start an instance using ``systemd`` tools, like this (the instance name -is ``my_app``): - -.. code-block:: console - - $ systemctl start tarantool@my_app - $ ps axuf|grep my_app - taranto+ 5350 1.3 0.3 1448872 7736 ? Ssl 20:05 0:28 tarantool my_app.lua - -... this actually calls ``tarantoolctl`` like in case of -``tarantoolctl start my_app``. - To check the instance file for syntax errors prior to starting ``my_app`` instance, say: @@ -419,27 +407,17 @@ instance, say: $ tarantoolctl check my_app -To enable ``my_app`` instance for auto-load during system startup, say: - -.. code-block:: console - - $ systemctl enable tarantool@my_app - To stop a running ``my_app`` instance, say: .. code-block:: console $ tarantoolctl stop my_app - $ # - OR - - $ systemctl stop tarantool@my_app To restart (i.e. stop and start) a running ``my_app`` instance, say: .. code-block:: console $ tarantoolctl restart my_app - $ # - OR - - $ systemctl restart tarantool@my_app .. _tarantoolctl-start_stop_instance-running_locally: From 9cf8116ca05f8aade58f77d28255bc2ccc8db71f Mon Sep 17 00:00:00 2001 From: Pavel Semyonov Date: Wed, 27 Sep 2023 17:39:12 +0700 Subject: [PATCH 3/8] Use tt in start_stop_instance.rst --- doc/book/admin/start_stop_instance.rst | 25 +++++++++++++++++-------- 1 file changed, 17 insertions(+), 8 deletions(-) diff --git a/doc/book/admin/start_stop_instance.rst b/doc/book/admin/start_stop_instance.rst index e4ae3b8125..36411bc13b 100644 --- a/doc/book/admin/start_stop_instance.rst +++ b/doc/book/admin/start_stop_instance.rst @@ -3,6 +3,9 @@ Starting and stopping instances =============================== +Quick start +----------- + To start a Tarantool instance from an :ref:`instance file ` using the :ref:`tt ` utility: @@ -17,13 +20,18 @@ using the :ref:`tt ` utility: • Starting an instance [my_app]... In this case, ``tt`` starts an instance from any ``*.lua`` file it finds in ``/etc/tarantool/instances.enabled/``. -If there are several Lua files, ``tt`` starts a separate instance for each of them. -All the instance files or directories placed in this directory are called -*enabled instances*. + +Starting instances +------------------ + +All the instance files or directories placed in the ``instances_enabled`` directory +specified in :ref:`tt configuration ` are called *enabled instances*. +If there are several enabled instances, ``tt start`` starts a separate instance for each of them. + Learn more about working with multiple Tarantool instances in :ref:`Managing multiple instances `. -To start a specific enabled instance to start, specify its name in the ``tt start`` argument: +To start a specific enabled instance, specify its name in the ``tt start`` argument: .. code-block:: console @@ -36,7 +44,6 @@ The default ``tt`` configuration file is created automatically in ``/etc/taranto Learn how to set up a ``tt`` environment in a directory of your choice in :ref:`Running Tarantool locally `. - After the instance has started and worked for some time, you can find its artifacts in the directories specified in the ``tt`` configuration. These are the default locations: @@ -52,6 +59,11 @@ locations: Basic instance management ------------------------- +.. note:: + + These commands can be called without an instance name. In this case, they are + executed for all enabled instances. + ``tt`` provides a set of commands for performing basic operations over instances: * ``tt check`` -- check the instance file for syntax errors: @@ -103,9 +115,6 @@ Basic instance management The ``-f`` option removes the files without confirmation. -These commands can be called without an instance name. In this case, they are -executed for all enabled instances. - .. _admin-start_stop_instance-running_locally: Running Tarantool locally From ee3fb1d9dd3caed0d251dba5b70ea74561878f8f Mon Sep 17 00:00:00 2001 From: Pavel Semyonov Date: Wed, 27 Sep 2023 18:26:28 +0700 Subject: [PATCH 4/8] Fix notes markup --- doc/book/admin/start_stop_instance.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/book/admin/start_stop_instance.rst b/doc/book/admin/start_stop_instance.rst index 36411bc13b..e96b894da7 100644 --- a/doc/book/admin/start_stop_instance.rst +++ b/doc/book/admin/start_stop_instance.rst @@ -91,7 +91,7 @@ Basic instance management .. note:: - The ``-y`` option responds "yes" to confirmation prompt automatically. + The ``-y`` option responds "yes" to confirmation prompt automatically. * ``tt stop`` -- stop the instance: @@ -113,7 +113,7 @@ Basic instance management .. note:: - The ``-f`` option removes the files without confirmation. + The ``-f`` option removes the files without confirmation. .. _admin-start_stop_instance-running_locally: From 2961e4316e5e4efd88c2bf9da08e894e098135e4 Mon Sep 17 00:00:00 2001 From: Pavel Semyonov Date: Thu, 28 Sep 2023 12:55:10 +0700 Subject: [PATCH 5/8] Add multi-instance example --- doc/book/admin/start_stop_instance.rst | 141 +++++++++++++++++- doc/reference/tooling/tt_cli/index.rst | 2 +- .../tooling/tt_cli/multiple_instances.rst | 117 --------------- 3 files changed, 139 insertions(+), 121 deletions(-) delete mode 100644 doc/reference/tooling/tt_cli/multiple_instances.rst diff --git a/doc/book/admin/start_stop_instance.rst b/doc/book/admin/start_stop_instance.rst index e96b894da7..cd0867cfb6 100644 --- a/doc/book/admin/start_stop_instance.rst +++ b/doc/book/admin/start_stop_instance.rst @@ -29,7 +29,7 @@ specified in :ref:`tt configuration ` are called *enabled instan If there are several enabled instances, ``tt start`` starts a separate instance for each of them. Learn more about working with multiple Tarantool instances in -:ref:`Managing multiple instances `. +:ref:`Managing multiple instances `. To start a specific enabled instance, specify its name in the ``tt start`` argument: @@ -73,7 +73,7 @@ Basic instance management $ tt check my_app • Result of check: syntax of file '/etc/tarantool/instances.enabled/my_app.lua' is OK -* ``tt status`` -- check the instance's status: +* ``tt status`` -- check the instance status: .. code-block:: console @@ -100,7 +100,7 @@ Basic instance management $ tt stop my_app • The Instance my_app (PID = 639) has been terminated. -* ``tt clean`` -- remove instance artifacts: logs, snapshots, an other files. +* ``tt clean`` -- remove instance artifacts: logs, snapshots, and other files. .. code-block:: console @@ -115,6 +115,141 @@ Basic instance management The ``-f`` option removes the files without confirmation. +.. _admin-start_stop_instance-multi-instance: + +Multi-instance applications +--------------------------- + +Tarantool applications can include multiple instances that run different code. +A typical example is a cluster application that includes router and storage +instances. The ``tt`` utility enables managing such applications. +With a single ``tt`` call, you can: + +* start an application on multiple instances (:ref:`tt start `) +* check the status of application instances (:ref:`tt status `) +* connect to a specific instance of an application (:ref:`tt connect `) +* stop a specific instance of an application or all its instances (:ref:`tt stop `) + +Application directory +~~~~~~~~~~~~~~~~~~~~~ + +To create an multi-instance application, prepare its configuration +in a directory inside ``instances_enabled``. The directory name is used as +the application identifier. + +This directory should contain the following files: + +* The application file named ``init.lua``. +* The instances configuration file ``instances.yml`` with instance names followed by colons: + + .. code-block:: yaml + + : + : + ... + + .. note:: + + Do not use the dot (``.``) and dash (``-``) characters in the instance names. + They are reserved for system use. + +* (Optional) Application files to run on specific instances. + These files should have names ``.init.lua``, where ```` + is the name specified in ``instances.yml``. + For example, if your application has separate source files for the ``router`` and ``storage`` + instances, place the router code in the ``router.init.lua`` file. + +Example: a ``demo`` application that has three instances (``master``, ``replica``, and ``router``). +``master and ``replica`` share the same code and ``router`` has its own. Its directory +``demo`` inside ``instances_enabled`` must contain the following files: + +* ``instances.yml`` -- the instances configuration: + + .. code-block:: yaml + + master: + replica: + router: + +* ``init.lua`` -- the code of ``master`` and ``replica`` +* ``router.init.lua`` -- the code of ``router`` + + +Identifying instances in code +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +When the application is working, each instance has associated environment variables +``TARANTOOL_INSTANCE_NAME`` and ``TARANTOOL_APP_NAME``. You can use them in the application +code to identify the instance on which the code runs. + +To obtain the instance and application names, use the following code: + +.. code:: lua + + local inst_name = os.getenv('TARANTOOL_INSTANCE_NAME') + local app_name = os.getenv('TARANTOOL_APP_NAME') + + +Managing multi-instance applications +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Start all three instances of the ``demo`` application: + +.. code-block:: bash + + $ tt start demo + • Starting an instance [demo:master]... + • Starting an instance [demo:replica]... + • Starting an instance [demo:router]... + +Check the status of ``demo`` instances: + +.. code-block:: bash + + $ tt status demo + INSTANCE STATUS PID + demo:master RUNNING 55 + demo:replica RUNNING 56 + demo:router RUNNING 57 + +Check the status of a specific instance: + +.. code-block:: bash + + $ tt status demo:replica + INSTANCE STATUS PID + demo:replica RUNNING 56 + +Connect to an instance: + +.. code-block:: bash + + $ tt connect demo:router + • Connecting to the instance... + • Connected to /var/run/tarantool/demo/router/router.control + + /var/run/tarantool/demo/router/router.control> + +Stop a specific instance: + +.. code-block:: bash + + $ tt stop demo:replica + • The Instance demo:replica (PID = 56) has been terminated. + +Stop all ``demo`` instances: + +.. code-block:: bash + + $ tt stop demo + • The Instance demo:master (PID = 55) has been terminated. + • can't "stat" the PID file. Error: "stat /var/run/tarantool/demo/replica/replica.pid: no such file or directory" + • The Instance demo:router (PID = 57) has been terminated. + +.. note:: + + The error message indicates that ``replica`` is already not running. + .. _admin-start_stop_instance-running_locally: Running Tarantool locally diff --git a/doc/reference/tooling/tt_cli/index.rst b/doc/reference/tooling/tt_cli/index.rst index 23f7b285bf..f2c4968d0f 100644 --- a/doc/reference/tooling/tt_cli/index.rst +++ b/doc/reference/tooling/tt_cli/index.rst @@ -49,7 +49,7 @@ you can write an application that includes different source files for storage an instances. With ``tt``, you can start and stop them in a single call, or manage each instance independently. -Learn more about working with multi-instance applications in :ref:`Managing multiple instances `. +Learn more about working with multi-instance applications in :ref:`Multi-instance applications `. Replacement for tarantooctl and Cartridge CLI --------------------------------------------- diff --git a/doc/reference/tooling/tt_cli/multiple_instances.rst b/doc/reference/tooling/tt_cli/multiple_instances.rst deleted file mode 100644 index 72828f0e3a..0000000000 --- a/doc/reference/tooling/tt_cli/multiple_instances.rst +++ /dev/null @@ -1,117 +0,0 @@ -.. _tt-multi-instances: - -Managing multiple instances -=========================== - -The ``tt`` utility can manage Tarantool applications that run on -multiple instances. With a single ``tt`` call, you can: - -* start an application on multiple instances (:ref:`tt start `) -* check the status of application instances (:ref:`tt status `) -* connect to a specific instance of an application (:ref:`tt connect `) -* stop a specific instance of an application or all its instances (:ref:`tt stop `) - - -Application directory ---------------------- - -To create an application that runs on multiple instances, prepare its configuration -in a directory. The directory name is used as the application's identifier. - -This directory should contain the following files: - -* The application file named ``init.lua``. -* The instances configuration file ``instances.yml`` with instance names followed by colons: - - .. code-block:: yaml - - : - : - ... - - .. note:: - - Do not use the dot (``.``) and dash (``-``) characters in the instance names. - They are reserved for system use. - -* (Optional) Application files to run on specific instances. - These files should have names ``.init.lua``, where ```` - is the name specified in ``instances.yml``. - For example, if your application has separate source files for the ``router`` and ``storage`` - instances, place the router code in the ``router.init.lua`` file. - -Identifying instances in code ------------------------------ - -When the application is working, each instance has associated environment variables -``TARANTOOL_INSTANCE_NAME`` and ``TARANTOOL_APP_NAME``. You can use them in the application -code to identify the instance on which the code runs. - -To obtain the instance and application names, use the following code: - -.. code:: lua - - local inst_name = os.getenv('TARANTOOL_INSTANCE_NAME') - local app_name = os.getenv('TARANTOOL_APP_NAME') - - -Example -------- - -The ``demo`` application runs on three instances: ``master`` and ``replica`` for -storing data and ``router`` for connections. ``master`` and ``replica`` share -the same code, and ``router`` has its own code. - -The application configuration is stored in the ``demo`` directory. The directory -contains the following files: - -* ``instances.yml`` -- the instances configuration: - - .. code-block:: yaml - - master: - replica: - router: - - - -* ``init.lua`` -- the code of ``master`` and ``replica``. -* ``router.init.lua`` -- the code of ``router``. - - -Start all three instances of the ``demo`` application: - -.. code-block:: bash - - tt start demo - -Check the status of ``demo`` instances: - -.. code-block:: bash - - tt status demo - -Check the status of a specific instance: - -.. code-block:: bash - - tt status demo:replica - -Connect to an instance: - -.. code-block:: bash - - tt connect demo:router - -Stop a specific instance: - -.. code-block:: bash - - tt stop demo:replica - -Stop all ``demo`` instances: - -.. code-block:: bash - - tt stop demo - From 184ee28b813f6fb79fddb687d775d8596d3c2a3c Mon Sep 17 00:00:00 2001 From: Pavel Semyonov Date: Thu, 28 Sep 2023 14:10:13 +0700 Subject: [PATCH 6/8] Add multi-instance example --- doc/book/admin/start_stop_instance.rst | 71 +++++++++++++------------- doc/reference/tooling/tt_cli/index.rst | 1 - 2 files changed, 36 insertions(+), 36 deletions(-) diff --git a/doc/book/admin/start_stop_instance.rst b/doc/book/admin/start_stop_instance.rst index cd0867cfb6..9bc8960a8b 100644 --- a/doc/book/admin/start_stop_instance.rst +++ b/doc/book/admin/start_stop_instance.rst @@ -125,21 +125,22 @@ A typical example is a cluster application that includes router and storage instances. The ``tt`` utility enables managing such applications. With a single ``tt`` call, you can: -* start an application on multiple instances (:ref:`tt start `) -* check the status of application instances (:ref:`tt status `) -* connect to a specific instance of an application (:ref:`tt connect `) -* stop a specific instance of an application or all its instances (:ref:`tt stop `) +* start an application on multiple instances +* check the status of application instances +* connect to a specific instance of an application +* stop a specific instance of an application or all its instances -Application directory -~~~~~~~~~~~~~~~~~~~~~ +Application layout +~~~~~~~~~~~~~~~~~~ -To create an multi-instance application, prepare its configuration +To create an multi-instance application, prepare its layout in a directory inside ``instances_enabled``. The directory name is used as the application identifier. This directory should contain the following files: -* The application file named ``init.lua``. +* The default instance file named ``init.lua``. This file is used for all + instances of the application unless there are specific instance files (see below). * The instances configuration file ``instances.yml`` with instance names followed by colons: .. code-block:: yaml @@ -153,25 +154,25 @@ This directory should contain the following files: Do not use the dot (``.``) and dash (``-``) characters in the instance names. They are reserved for system use. -* (Optional) Application files to run on specific instances. +* (Optional) Specific instances files. These files should have names ``.init.lua``, where ```` is the name specified in ``instances.yml``. For example, if your application has separate source files for the ``router`` and ``storage`` instances, place the router code in the ``router.init.lua`` file. -Example: a ``demo`` application that has three instances (``master``, ``replica``, and ``router``). -``master and ``replica`` share the same code and ``router`` has its own. Its directory -``demo`` inside ``instances_enabled`` must contain the following files: +Example: a ``demo`` application that has three instances (``storage1``, ``storage2``, and ``router``). +Storage instances share the same code, and ``router`` has its own. The application +directory ``demo`` inside ``instances_enabled`` must contain the following files: * ``instances.yml`` -- the instances configuration: .. code-block:: yaml - master: - replica: + storage1: + storage2: router: -* ``init.lua`` -- the code of ``master`` and ``replica`` +* ``init.lua`` -- the code of ``storage1`` and ``storage2`` * ``router.init.lua`` -- the code of ``router`` @@ -195,34 +196,34 @@ Managing multi-instance applications Start all three instances of the ``demo`` application: -.. code-block:: bash +.. code-block:: console $ tt start demo - • Starting an instance [demo:master]... - • Starting an instance [demo:replica]... • Starting an instance [demo:router]... + • Starting an instance [demo:storage1]... + • Starting an instance [demo:storage2]... Check the status of ``demo`` instances: -.. code-block:: bash +.. code-block:: console $ tt status demo INSTANCE STATUS PID - demo:master RUNNING 55 - demo:replica RUNNING 56 - demo:router RUNNING 57 + demo:router RUNNING 55 + demo:storage1 RUNNING 56 + demo:storage2 RUNNING 57 Check the status of a specific instance: -.. code-block:: bash +.. code-block:: console - $ tt status demo:replica + $ tt status demo:router INSTANCE STATUS PID - demo:replica RUNNING 56 + demo:router RUNNING 55 Connect to an instance: -.. code-block:: bash +.. code-block:: console $ tt connect demo:router • Connecting to the instance... @@ -232,23 +233,23 @@ Connect to an instance: Stop a specific instance: -.. code-block:: bash +.. code-block:: console - $ tt stop demo:replica - • The Instance demo:replica (PID = 56) has been terminated. + $ tt stop demo:storage1 + • The Instance demo:storage1 (PID = 56) has been terminated. -Stop all ``demo`` instances: +Stop all running instances of the ``demo`` application: -.. code-block:: bash +.. code-block:: console $ tt stop demo - • The Instance demo:master (PID = 55) has been terminated. - • can't "stat" the PID file. Error: "stat /var/run/tarantool/demo/replica/replica.pid: no such file or directory" - • The Instance demo:router (PID = 57) has been terminated. + • The Instance demo:router (PID = 55) has been terminated. + • can't "stat" the PID file. Error: "stat /var/run/tarantool/demo/storage1/storage1.pid: no such file or directory" + • The Instance demo:storage2 (PID = 57) has been terminated. .. note:: - The error message indicates that ``replica`` is already not running. + The error message indicates that ``storage1`` is already not running. .. _admin-start_stop_instance-running_locally: diff --git a/doc/reference/tooling/tt_cli/index.rst b/doc/reference/tooling/tt_cli/index.rst index f2c4968d0f..d5ca5c6742 100644 --- a/doc/reference/tooling/tt_cli/index.rst +++ b/doc/reference/tooling/tt_cli/index.rst @@ -22,7 +22,6 @@ concept explanation, and the ``tt`` command reference. arguments commands external_modules - multiple_instances .. _tt-cli-environments: From 35e79240196c1ceebbc3665e92fd3fd2869c2fba Mon Sep 17 00:00:00 2001 From: Pavel Semyonov Date: Thu, 28 Sep 2023 16:48:12 +0700 Subject: [PATCH 7/8] Apply suggestions from code review Co-authored-by: Andrey Aksenov <38073144+andreyaksenov@users.noreply.github.com> --- doc/book/admin/start_stop_instance.rst | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/doc/book/admin/start_stop_instance.rst b/doc/book/admin/start_stop_instance.rst index 9bc8960a8b..da82f07a50 100644 --- a/doc/book/admin/start_stop_instance.rst +++ b/doc/book/admin/start_stop_instance.rst @@ -48,12 +48,12 @@ After the instance has started and worked for some time, you can find its artifa in the directories specified in the ``tt`` configuration. These are the default locations: -* ``/var/log/tarantool/.log`` -- instance :ref:`logs ` -* ``/var/lib/tarantool//`` -- snapshots and write-ahead logs -* ``/var/run/tarantool/.control`` -- control socket. This is - a Unix socket with Lua console attached to it. This file is used to connect +* ``/var/log/tarantool/.log`` -- instance :ref:`logs `. +* ``/var/lib/tarantool//`` -- snapshots and write-ahead logs. +* ``/var/run/tarantool/.control`` -- a control socket. This is + a Unix socket with the Lua console attached to it. This file is used to connect to the instance console. -* ``/var/run/tarantool/.pid`` -- PID file that ``tt`` uses to +* ``/var/run/tarantool/.pid`` -- a PID file that ``tt`` uses to check the instance status and send control commands. Basic instance management @@ -91,7 +91,7 @@ Basic instance management .. note:: - The ``-y`` option responds "yes" to confirmation prompt automatically. + The ``-y`` option responds "yes" to the confirmation prompt automatically. * ``tt stop`` -- stop the instance: @@ -133,7 +133,7 @@ With a single ``tt`` call, you can: Application layout ~~~~~~~~~~~~~~~~~~ -To create an multi-instance application, prepare its layout +To create a multi-instance application, prepare its layout in a directory inside ``instances_enabled``. The directory name is used as the application identifier. @@ -160,7 +160,7 @@ This directory should contain the following files: For example, if your application has separate source files for the ``router`` and ``storage`` instances, place the router code in the ``router.init.lua`` file. -Example: a ``demo`` application that has three instances (``storage1``, ``storage2``, and ``router``). +Example: a ``demo`` application that has three instances:``storage1``, ``storage2``, and ``router``. Storage instances share the same code, and ``router`` has its own. The application directory ``demo`` inside ``instances_enabled`` must contain the following files: From 5c2cf1414f30da7d1ab26ad5b269c2f60f94fdb9 Mon Sep 17 00:00:00 2001 From: Pavel Semyonov Date: Thu, 28 Sep 2023 16:59:56 +0700 Subject: [PATCH 8/8] Review fixes --- doc/book/admin/start_stop_instance.rst | 28 +++++++++++++------------- 1 file changed, 14 insertions(+), 14 deletions(-) diff --git a/doc/book/admin/start_stop_instance.rst b/doc/book/admin/start_stop_instance.rst index da82f07a50..b341c841ca 100644 --- a/doc/book/admin/start_stop_instance.rst +++ b/doc/book/admin/start_stop_instance.rst @@ -3,9 +3,6 @@ Starting and stopping instances =============================== -Quick start ------------ - To start a Tarantool instance from an :ref:`instance file ` using the :ref:`tt ` utility: @@ -26,7 +23,8 @@ Starting instances All the instance files or directories placed in the ``instances_enabled`` directory specified in :ref:`tt configuration ` are called *enabled instances*. -If there are several enabled instances, ``tt start`` starts a separate instance for each of them. +If there are several enabled instances, ``tt start`` starts a separate Tarantool +instance for each of them. Learn more about working with multiple Tarantool instances in :ref:`Managing multiple instances `. @@ -89,9 +87,7 @@ Basic instance management • The Instance my_app (PID = 729) has been terminated. • Starting an instance [my_app]... - .. note:: - - The ``-y`` option responds "yes" to the confirmation prompt automatically. + The ``-y`` option responds "yes" to the confirmation prompt automatically. * ``tt stop`` -- stop the instance: @@ -111,9 +107,7 @@ Basic instance management • /var/lib/tarantool/my_app/00000000000000000000.snap • /var/lib/tarantool/my_app/00000000000000000000.xlog - .. note:: - - The ``-f`` option removes the files without confirmation. + The ``-f`` option removes the files without confirmation. .. _admin-start_stop_instance-multi-instance: @@ -160,9 +154,9 @@ This directory should contain the following files: For example, if your application has separate source files for the ``router`` and ``storage`` instances, place the router code in the ``router.init.lua`` file. -Example: a ``demo`` application that has three instances:``storage1``, ``storage2``, and ``router``. -Storage instances share the same code, and ``router`` has its own. The application -directory ``demo`` inside ``instances_enabled`` must contain the following files: +For example, take a ``demo`` application that has three instances:``storage1``, +``storage2``, and ``router``. Storage instances share the same code, and ``router`` has its own. +The application directory ``demo`` inside ``instances_enabled`` must contain the following files: * ``instances.yml`` -- the instances configuration: @@ -259,7 +253,6 @@ Running Tarantool locally Sometimes you may need to run a Tarantool instance locally, for example, for test purposes. ``tt`` runs in a local environment if it finds a ``tt.yaml`` configuration file in the current directory or any of its enclosing directories. -To force ``tt`` into the local mode, add the ``-L`` or ``--local`` argument. To set up a local environment for ``tt``: @@ -299,6 +292,13 @@ the current directory: * snapshots and write-ahead logs in ``var/lib/`` * control sockets and PID files in ``var/run/`` +To work with a local environment from a directory outside it, issue ``tt`` calls with +the ``-L`` or ``--local`` argument with the path to this environment as its value: + +.. code-block:: console + + $ tt --local=/usr/tt/env/ start + .. _admin-start_stop_instance-systemd: Using systemd tools