Skip to content

Commit 07cb38f

Browse files
patiencedaurp7novxuniqEvgeniy Osintsev
authored
Restructure docs, stage 2 (#3116)
* Put the Access control page in the Admin guide * Remove redundant Authentication page * Add Concepts page and section - Incorporate the sections Data model, Indexes, Storage engines, Transactions - Incorporate the Triggers section (temporarily, will end up in Reference later on) - Add content from the sections Application server, Replication, Sharding * Split the Application server section Move the content to different chapters, save some content for the Concepts section. - Tutorial on pokemons (Creating application): How-to - Developing with IDE, Cookbook recipes: How-to - Module installation and reload: Admin guide - Module contribution: Dev guide * Create a Tooling section in the Reference chapter - Move console tools and LuaJIT tooling to Tooling * Split the Sharding section - Overview & Architecture -> Concepts - Quick start -> How-to - Sharding administration -> Administration * Split the Replication section - Remove unused replication examples from the toctree - Move replication guides to Administration * Monitoring a replica set * Reseeding a replica * Recovering from a degraded state * Resolving replication conflicts - Move some information on Synchronous replication and Leader election to Concepts and How-to - Move 'Server startup with replication' to Internals - Move replica orphan status information to Internals * Add concept links to Overview * Format by style guide * Fix build warnings Co-authored-by: Pavel Semyonov <[email protected]> Co-authored-by: Kseniia Antonova <[email protected]> Co-authored-by: Evgeniy Osintsev <[email protected]>
1 parent d8519f0 commit 07cb38f

File tree

289 files changed

+9139
-8244
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

289 files changed

+9139
-8244
lines changed

conf.py

Lines changed: 2 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -62,12 +62,8 @@
6262
'_build',
6363
'archive/*',
6464
'book/connectors/__*',
65-
'book/replication/*_1.rst',
66-
'book/replication/*_2.rst',
67-
'getting_started/using_package_manager.rst',
68-
'getting_started/using_docker.rst',
69-
'dev_guide/box_protocol.rst',
70-
'dev_guide/internals.rst',
65+
'how-to/using_package_manager.rst',
66+
'how-to/using_docker.rst',
7167
'reference/configuration/cfg_*',
7268
'images',
7369
'book/cartridge/cartridge_overview.rst',

doc/book/box/authentication.rst renamed to doc/book/admin/access_control.rst

Lines changed: 2 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -4,10 +4,8 @@
44
Access control
55
================================================================================
66

7-
Understanding security details is primarily an issue for administrators.
8-
However, ordinary users should at least skim this section to get an idea
9-
of how Tarantool makes it possible for administrators to prevent unauthorized
10-
access to the database and to certain functions.
7+
This section explains how Tarantool makes it possible for administrators
8+
to prevent unauthorized access to the database and to certain functions.
119

1210
Briefly:
1311

doc/book/admin/index.rst

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -29,8 +29,12 @@ This chapter includes the following sections:
2929

3030
instance_config
3131
start_stop_instance
32+
modules
3233
logs
3334
security
35+
access_control
36+
vshard_admin
37+
replication/index
3438
server_introspection
3539
daemon_supervision
3640
disaster_recovery

doc/book/admin/modules.rst

Lines changed: 213 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,213 @@
1+
.. _admin-managing_tarantool_modules:
2+
3+
Managing modules
4+
================
5+
6+
This section covers the installation and reloading of Tarantool modules.
7+
To learn about writing your own module and contributing it,
8+
check the :ref:`Contributing a module <app_server-contributing_module>` section.
9+
10+
.. _app_server-installing_module:
11+
12+
Installing a module
13+
-------------------
14+
15+
Modules in Lua and C that come from Tarantool developers and community
16+
contributors are available in the following locations:
17+
18+
* Tarantool modules repository (see :ref:`below <app_server-installing_module_luarocks>`)
19+
* Tarantool deb/rpm repositories (see :ref:`below <app_server-installing_module_debrpm>`)
20+
21+
.. _app_server-installing_module_luarocks:
22+
23+
Installing a module from a repository
24+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
25+
26+
See
27+
`README in tarantool/rocks repository <https://github.com/tarantool/rocks#managing-modules-with-tarantool-174>`_
28+
for detailed instructions.
29+
30+
.. _app_server-installing_module_debrpm:
31+
32+
Installing a module from deb/rpm
33+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
34+
35+
Follow these steps:
36+
37+
1. Install Tarantool as recommended on the
38+
`download page <http://tarantool.org/download.html>`_.
39+
40+
2. Install the module you need. Look up the module's name on
41+
`Tarantool rocks page <http://tarantool.org/rocks.html>`_ and put the prefix
42+
"tarantool-" before the module name to avoid ambiguity:
43+
44+
.. code-block:: console
45+
46+
$ # for Ubuntu/Debian:
47+
$ sudo apt-get install tarantool-<module-name>
48+
49+
$ # for RHEL/CentOS/Amazon:
50+
$ sudo yum install tarantool-<module-name>
51+
52+
For example, to install the module
53+
`shard <http://github.com/tarantool/shard>`_ on Ubuntu, say:
54+
55+
.. code-block:: console
56+
57+
$ sudo apt-get install tarantool-shard
58+
59+
Once these steps are complete, you can:
60+
61+
* load any module with
62+
63+
.. code-block:: tarantoolsession
64+
65+
tarantool> name = require('module-name')
66+
67+
for example:
68+
69+
.. code-block:: tarantoolsession
70+
71+
tarantool> shard = require('shard')
72+
73+
* search locally for installed modules using ``package.path`` (Lua) or
74+
``package.cpath`` (C):
75+
76+
.. code-block:: tarantoolsession
77+
78+
tarantool> package.path
79+
---
80+
- ./?.lua;./?/init.lua; /usr/local/share/tarantool/?.lua;/usr/local/share/
81+
tarantool/?/init.lua;/usr/share/tarantool/?.lua;/usr/share/tarantool/?/ini
82+
t.lua;/usr/local/share/lua/5.1/?.lua;/usr/local/share/lua/5.1/?/init.lua;/
83+
usr/share/lua/5.1/?.lua;/usr/share/lua/5.1/?/init.lua;
84+
...
85+
86+
tarantool> package.cpath
87+
---
88+
- ./?.so;/usr/local/lib/x86_64-linux-gnu/tarantool/?.so;/usr/lib/x86_64-li
89+
nux-gnu/tarantool/?.so;/usr/local/lib/tarantool/?.so;/usr/local/lib/x86_64
90+
-linux-gnu/lua/5.1/?.so;/usr/lib/x86_64-linux-gnu/lua/5.1/?.so;/usr/local/
91+
lib/lua/5.1/?.so;
92+
...
93+
94+
.. NOTE::
95+
96+
Question-marks stand for the module name that was specified earlier when
97+
saying ``require('module-name')``.
98+
99+
.. _app_server-reloading_module:
100+
101+
Reloading a module
102+
------------------
103+
104+
You can reload any Tarantool application or module with zero downtime.
105+
106+
.. _app_server-reloading_lua_module:
107+
108+
Reloading a module in Lua
109+
~~~~~~~~~~~~~~~~~~~~~~~~~
110+
111+
Here's an example that illustrates the most typical case -- "update and reload".
112+
113+
.. NOTE::
114+
115+
In this example, we use recommended :ref:`administration practices <admin>`
116+
based on :ref:`instance files <admin-instance_file>` and
117+
:ref:`tarantoolctl <tarantoolctl>` utility.
118+
119+
1. Update the application file.
120+
121+
For example, a module in ``/usr/share/tarantool/app.lua``:
122+
123+
.. code-block:: lua
124+
125+
local function start()
126+
-- initial version
127+
box.once("myapp:v1.0", function()
128+
box.schema.space.create("somedata")
129+
box.space.somedata:create_index("primary")
130+
...
131+
end)
132+
133+
-- migration code from 1.0 to 1.1
134+
box.once("myapp:v1.1", function()
135+
box.space.somedata.index.primary:alter(...)
136+
...
137+
end)
138+
139+
-- migration code from 1.1 to 1.2
140+
box.once("myapp:v1.2", function()
141+
box.space.somedata.index.primary:alter(...)
142+
box.space.somedata:insert(...)
143+
...
144+
end)
145+
end
146+
147+
-- start some background fibers if you need
148+
149+
local function stop()
150+
-- stop all background fibers and clean up resources
151+
end
152+
153+
local function api_for_call(xxx)
154+
-- do some business
155+
end
156+
157+
return {
158+
start = start,
159+
stop = stop,
160+
api_for_call = api_for_call
161+
}
162+
163+
2. Update the :ref:`instance file <admin-instance_file>`.
164+
165+
For example, ``/etc/tarantool/instances.enabled/my_app.lua``:
166+
167+
.. code-block:: lua
168+
169+
#!/usr/bin/env tarantool
170+
--
171+
-- hot code reload example
172+
--
173+
174+
box.cfg({listen = 3302})
175+
176+
-- ATTENTION: unload it all properly!
177+
local app = package.loaded['app']
178+
if app ~= nil then
179+
-- stop the old application version
180+
app.stop()
181+
-- unload the application
182+
package.loaded['app'] = nil
183+
-- unload all dependencies
184+
package.loaded['somedep'] = nil
185+
end
186+
187+
-- load the application
188+
log.info('require app')
189+
app = require('app')
190+
191+
-- start the application
192+
app.start({some app options controlled by sysadmins})
193+
194+
The important thing here is to properly unload the application and its
195+
dependencies.
196+
197+
3. Manually reload the application file.
198+
199+
For example, using ``tarantoolctl``:
200+
201+
.. code-block:: console
202+
203+
$ tarantoolctl eval my_app /etc/tarantool/instances.enabled/my_app.lua
204+
205+
.. _app_server-reloading_c_module:
206+
207+
Reloading a module in C
208+
~~~~~~~~~~~~~~~~~~~~~~~
209+
210+
After you compiled a new version of a C module (``*.so`` shared library), call
211+
:doc:`box.schema.func.reload('module-name') </reference/reference_lua/box_schema/func_reload>`
212+
from your Lua script to reload the module.
213+

doc/book/admin/replication/index.rst

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
Replication administration
2+
==========================
3+
4+
.. toctree::
5+
:maxdepth: 2
6+
7+
repl_monitoring
8+
repl_recover
9+
repl_reseed
10+
repl_problem_solving

doc/book/replication/repl_monitoring.rst renamed to doc/book/admin/replication/repl_monitoring.rst

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -42,7 +42,7 @@ these instances, issue a :doc:`/reference/reference_lua/box_info/replication` re
4242
This report is for a master-master replica set of three instances, each having
4343
its own instance id, UUID and log sequence number.
4444

45-
.. image:: mm-3m-mesh.svg
45+
.. image:: /concepts/replication/images/mm-3m-mesh.svg
4646
:align: center
4747

4848
The request was issued at master #1, and the reply includes statistics for the
@@ -78,6 +78,5 @@ The primary indicators of replication health are:
7878

7979
For better understanding, see the following diagram illustrating the ``upstream`` and ``downstream`` connections within the replica set of three instances:
8080

81-
.. image:: replication.svg
81+
.. image:: /concepts/replication/images/replication.svg
8282
:align: left
83-

0 commit comments

Comments
 (0)