server-administration.xml dist.lua

doc/user/server-administration.xml

@@ -207,6 +207,208 @@ Explanatory notes about what tarantool displayed in the above example:
 
 </section>
 
+<section xml:id="dist.lua">
+<title>Utility <code>dist.lua</code></title>
+<para>
+With dist.lua one can say: "start an instance of the
+Tarantool server which runs a single user-written Lua
+program, allocating disk resources specifically for
+that program, via a standardized deployment method."
+If Tarantool was downloaded from source, then the script
+is in ~/extra/dist/dist.lua. If Tarantool was installed
+with debian or Red Hat installation packages, the script
+is renamed <code>tarantoolctl</code> and is in
+/usr/bin/tarantoolctl. The script handles such things as:
+starting, stopping, rotating logs, logging in to the
+application's console, and checking status.
+</para>
+
+<bridgehead renderas="sect4">configuring for dist.lua</bridgehead>
+<para>
+The dist.lua script will read a configuration file
+named /etc/sysconfig/tarantool, or /etc/default/tarantool.
+Most of the settings are similar to the settings
+used by <code>box.cfg{...}</code>; however, dist.lua
+adjusts some of them by adding an application name.
+A copy of /etc/sysconfig/tarantool, with defaults for
+all settings, would look like this:<programlisting>
+default_cfg = {
+     pid_file = "/var/run/tarantool",
+     wal_dir = "/var/ lib / tarantool",
+     snap_dir = "/var/lib/tarantool",
+     sophia_dir = "/var/lib/tarantool",
+     logger = "/var/log/tarantool",
+     username = "tarantool",
+}
+instance_dir = "/etc/tarantool/instances.enabled"</programlisting>
+</para>
+<para>
+The settings in the above script are:
+</para>
+<para>
+pid_file = The directory for the pid file and control-socket file.
+The script will add "/<replaceable>instance-name</replaceable>" to the directory name.
+</para>
+<para>
+wal_dir = The directory for the write-ahead *.xlog files.
+The script will add "/<replaceable>instance-name</replaceable>" to the directory-name.
+</para>
+<para>
+snap_dir = The directory for the snapshot *.snap files.
+The script will add "/<replaceable>instance-name</replaceable>" to the directory-name.
+</para>
+<para>
+sophia_dir = The directory for the Sophia-storage-engine files.
+The script will add "/sophia/<replaceable>instance-name</replaceable>" to the directory-name.
+</para>
+<para>
+logger = The place where the application log will go.
+The script will add /<replaceable>instance-name</replaceable>.log" to the name.
+</para>
+<para>
+username = the user that runs the tarantool server.
+</para>
+<para>
+instance_dir = the directory where all applications for this host are stored.
+The user who writes an application for dist.lua must put the application's
+source code in this directory, or a symbolic link. For examples in this section the application
+name <code>my_app</code> will be used, and its source will have to be in
+<code><replaceable>instance_dir</replaceable>/my_app.lua</code>.
+</para>
+
+<bridgehead renderas="sect4">commands for dist.lua</bridgehead>
+<para>
+The command format is <code>dist.lua <replaceable>operation</replaceable> application-name</code>,
+where <replaceable>operation</replaceable> is one of: <code>start</code>, <code>stop</code>,
+<code>status</code>, <code>logrotate</code>, <code>enter</code>. Thus ...<programlisting>
+dist.lua start my_app          -- starts application my_app
+dist.lua stop my_app           -- stops my_app
+dist.lua enter my_app          -- show my_app's admin console, if it has one
+dist.lua logrotate my_app      -- rotate my_app's log files (make new, remove old)
+dist.lua status my_app         -- check my_app's status</programlisting>
+</para>
+
+<bridgehead renderas="sect4">typical code snippets for dist.lua</bridgehead>
+<para>
+A user can check whether my_app is running with these lines:<programlisting>
+  if dist.lua status my_app; then
+        ...
+  fi</programlisting>
+A user can initiate, for boot time, an init.d set of instructions:<programlisting>
+  for (each file mentioned in the instance_dir directory):
+   dist.lua start `basename $ file .lua`</programlisting>
+A user can set up a further configuration file for log rotation, like this:<programlisting>
+/path/to/tarantool/*.log {
+     daily
+     size 512k
+     missingok
+     rotate 10
+     compress
+     delaycompress
+     create 0640 tarantool adm
+     postrotate
+         /path/to/dist.lua logrotate `basename $ 1 .log`
+     endscript
+}</programlisting>
+</para>
+
+<bridgehead renderas="sect4">A detailed example for dist.lua</bridgehead>
+<para>
+The example's objective is: make a temporary directory
+where dist.lua can start a long-running application
+and monitor it.
+</para>
+<para>
+The assumptions are: the root password is known,
+the computer is only being used for tests,
+the Tarantool server is ready to run but is
+not currently running, and
+there currently is no directory named tarantool_test.
+</para>
+<para>
+Create a directory named /tarantool_test:<programlisting>
+sudo mkdir /tarantool_test</programlisting>
+</para>
+<para>
+Copy dist.lua to /tarantool_test.
+If you made a source download to ~/tarantool-master, then<programlisting>
+sudo cp ~/tarantool-master/extra/dist/dist.lua /tarantool_test/dist.lua</programlisting>
+If the file was named tarantoolctl and placed on /usr/bin/tarantoolctl, then<programlisting>
+sudo cp /usr/bin/tarantoolctl /tarantool_test/dist.lua</programlisting>
+</para>
+<para>
+Check and possibly change the first line of /tarantool_test/dist.lua.
+Initially it says<programlisting>
+#!/usr/bin/env tarantool</programlisting>
+If that is not correct, edit dist.lua and change the line.
+For example, if the Tarantool server is actually on
+/home/user/tarantool-master/src/tarantool, change the line to<programlisting>
+#!/usr/bin/env /home/user/tarantool-master/src/tarantool</programlisting>
+</para>
+<para>
+Save a copy of /etc/sysconfig/tarantool, if it exists.
+</para>
+<para>
+Edit /etc/sysconfig/tarantool.
+It might be necessary to say sudo mkdir /etc/sysconfig first.
+Let the new file contents be:<programlisting>
+default_cfg = {
+     pid_file = "/tarantool_test/my_app.pid",
+     wal_dir = "/tarantool_test",
+     snap_dir = "/tarantool_test",
+     sophia_dir = "/tarantool_test",
+     logger = "/tarantool_test/log",
+     username = "tarantool",
+}
+instance_dir = "/tarantool_test"</programlisting>
+</para>
+<para>
+Make the my_app application file, that is, /tarantool_test/my_app.lua.
+Let the file contents be:<programlisting>
+box.cfg{listen = 3301}
+box.schema.user.passwd('Gx5!')
+box.schema.user.grant('guest','read,write,execute','universe')
+fiber = require('fiber')
+box.schema.create_space('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</programlisting>
+</para>
+<para>
+Tell dist.lua to start the application ...<programlisting>
+cd /tarantool_test
+sudo ./dist.lua start my_app</programlisting>
+... expect to see messages indicating that the instance has started. Then ...<programlisting>
+ls -l /tarantool_test/my_app</programlisting>
+... expect to see the .snap file, .xlog file, and sophia directory. Then ...<programlisting>
+less /tarantool_test/log/my_app.log</programlisting>
+... expect to see the contents of my_app's log, including error messages, if any. Then ...<programlisting>
+cd /tarantool_test
+#assume that 'tarantool' invokes the tarantool server
+sudo tarantool
+box.cfg{}
+console = require('console')
+console.connect('localhost:3301')
+box.space.tester:select({0},{iterator='GE'})</programlisting>
+... expect to see several tuples that my_app has created.
+</para>
+<para>
+Stop. The only clean way to stop my_app is with dist_lua, thus:<programlisting>
+sudo ./dist.lua stop my_app</programlisting>
+</para>
+<para>
+Clean up. Restore the original contents of /etc/sysconfig/tarantool, and ...<programlisting>
+cd /
+sudo rm -R tarantool_test</programlisting>
+</para>
+
+</section>
+
 <section xml:id="os-install-notes">
 <title>System-specific administration notes</title>
 <blockquote><para>