Run an external process¶
An application may run programs that are not Tarantool - a gateway, a
worker, an exporter - next to its Tarantool instances. A record with
binary in instances.yaml is such an external process: the instance
commands start, stop and show it next to the Tarantool instances, under the
same watchdog.
Describe the process¶
storage-001:
gateway:
binary: gateway # a program of .rocks/bin, or on PATH, or a path
args: [--port, "8080"]
env: {GATEWAY_MODE: production}
workdir: ./gateway # <root>/var/lib/<app>/<instance>/ by default
stop_signal: SIGINT # SIGTERM by default
stop_timeout: 10s # 30s by default
logrotate_signal: SIGHUP # none by default
restart: on-failure # no by default
binarywith a slash is a path, relative to the application directory. Without one it names a program, looked up first in.rocks/bin/of the application, where tt builds the programs of the package, and then onPATH:binary: python3runs thepython3of the host.workdiris relative to the application directory. Without it the process runs in its data directory,<root>/var/lib/<app>/<instance>/, whichtt instance startcreates.envgoes on top of the environment of tt.args,workdirandlogrotate_signalare for external processes only.
tt instance start reports a binary it cannot run, or a workdir that does
not exist, before it starts anything. See the
reference for every field.
Build the program with the package¶
A component whose build makes a program puts it into .rocks/bin/, so the
package carries it, and the record names it by its name:
[components.gateway]
path = "gateway" # a Go module
[components.gateway.build]
backend = "go"
$ tt package build
$ ls .rocks/bin
gateway
$ tt instance start
$ tt instance logs myapp:gateway
myapp:gateway: gateway started, port [--port 8080]
The backends that build programs:
go:go build -trimpathofpackage(.by default) into a program namedname, the component's name by default;tags,ldflags, andcgo(off by default). The Go sources are not laid out into the package: only whatincludeof the component names is.tt package build --target linux/arm64builds it for another platform withGOOSandGOARCH, unlesscgo = true, which compiles C with the C compiler of the machine (see Other platforms).cargo:cargo buildof the binarybin, in thereleaseprofile unlessprofilesays otherwise, in_build/cargo/;package,features. A block that namesmoduletoo builds the module of the library as well; see Build a module in Rust.zig:zig buildof thebuild.zigofcwd, the programbintaken from what it installed into its prefix,bin/;steps,optimize,options. A block that namesmoduletoo takes the module as well; see Build a module in Zig.cmake: the CMake project ofcwd, built out of the source in_build/component/<component>/, its programs listed inoutputwithto = "bin", relative to the build tree;variables,targets,build_type.makeandshell: a build of your own, its programs listed inoutputwithto = "bin", relative tocwd, and what it makes on the way inTT_BUILD_DIR.
[components.tools.build]
backend = "make"
make_target = "tools"
output = [{ path = "build/gw-cli", to = "bin" }]
A component may make modules and programs at once: a string of output
is a module, a file with to = "share" a data file. The deprecated
kind = "executable" of manifest_version = "0.1" still works, with a
warning: its build makes programs only, and a make or shell build of it
writes them into TT_OUTPUT_DIR.
static = true asks go and cargo for a program that needs no loader and
no shared library, and the build checks that it got one; the programs of
cmake, make and shell are only checked. The toolchain must be on
PATH. See the manifest reference.
How it runs¶
- The process leads a process group of its own, which its stop signal and
tt instance killreach whole, so a wrapper script stops with the program it runs. - Its output goes to
tt.log. Its watchdog keepstt.pidand the pid of the process,process.pid, in the run directory. tt instance statusshows whether the process runs, and nothing more.tt instance logrotatereopenstt.logand sends the processlogrotate_signal, if the record has one. On Linux and macOS a process that does not catch, ignore or block that signal does not get it, since it would die of it;tt.logsays so.tt instance cleanremoves its log and its data directory.tt connect,tt data play,tt instance kill --dumpand the cluster commands refuse an external process: it is not a Tarantool instance.- The instances start in the order of
instances.yaml, and none waits for another to be ready.
A process whose watchdog was killed by something else than
tt instance kill runs on without it. tt instance status does not show it
running and names it in an alert, tt instance start refuses to start a
second one, and tt instance stop and tt instance kill stop it by
process.pid.