<a href="http://tarantool.org"> <img src="https://avatars2.githubusercontent.com/u/2344919?v=2&s=250" align="right" alt="Tarantool logo"> </a>

Tarantool CLI

[![Go Reference][godoc-badge]][godoc-url] [![Go Report][report-badge]][report-url] [![Release][release-badge]][release-url] [![Full CI][testing-actions-badge]][testing-actions-url]

Tarantool CLI - command line utility for managing Tarantool packages and Tarantool-based applications.

Intro
Getting started
- Installation
- Build from source
Configuration
- Configuration file
Creating tt environment
External modules
CLI Args
- Autocompletion
TT usage
Migration from older TT versions
Known issues
Commands

Intro

tt is tarantool's instance and environment management utility and is used to develop, deploy, run and operate applications.

One of the basic concepts that tt introduces is "environment". The "environment" is an isolated workspace for the tarantool application suite. tt.yaml configuration file defines the root and configuration of the environment. When tt is installed from a repository by a package manager (apt, rpm, ...) a "system" config file (/etc/tarantool/tt.yaml) is included which forms the "system" environment - the case when tt replaces the tarantoolctl. In case we want to form a local environment (very convenient during development), we use a "local" tt.yaml generated with the tt init command. In this way, the user/developer can have a large number of different "environments" in the system in which different versions of both tarantool/tt and the applications being developed will be used.

The example of a typical "environment":

graph LR
    %% Colors %%
    classDef lime fill:#C7EA46,stroke:#000,color:#000

    subgraph dot[Environment root]
      config
      bin
      modules
      local_reps
      inst_enabled[instances.enabled]
    end
    subgraph local_reps[Local repositories]
      dist[distfiles]
      rocks[rocks]
    end
    subgraph app1_files[Application]
        app_dir[app]
        app_dir --> init(init.lua):::lime
        app_dir --> |multi-instance|instances(instances.yaml):::lime
        app_dir --> |3.0|cluster_config(config.yaml):::lime
        app_dir --> var[var]
        var --> run[run] --> inst11[instance]
        inst11 --> pid1(tt.pid):::lime
        inst11 --> control1(tarantool.control):::lime
        inst11 --> binary1(tarantool.sock):::lime

        var --> log1[log] --> inst12[instance] --> logfile1(tt.log):::lime

        var --> lib1[lib] --> inst13[instance]--> xlogs1(*.xlog,*.snap):::lime
    end

    root[.] --> config(tt.yaml):::lime

    bin --> bin_dir(tarantool<br/>tarantool-ee<br/>tt-ee<br/>tt):::lime
    root --> bin[bin]

    modules --> modules_dir(ext_module_1<br/>ext_module_2):::lime
    root --> modules[modules]

    root --> dist
    root --> rocks
    inst_enabled --> app_dir

Getting started

Installation

TT can be installed from the deb / rpm repository "tarantool/modules".

Install the tarantool repositories:

https://www.tarantool.io/en/download/os-installation/

Install TT:

Deb based distributions:

apt-get install tt

Rpm based distributions:

yum install tt
dnf install tt

On Gentoo Linux, the TT can be installed from the Tarantool Gentoo Overlay:

emerge tt

On MacOS, the TT can be installed from brew:

brew install tt

You can also install Tarantool CLI by downloading archive with pre-built binary for your OS from GitHub's Releases page.

However, on MacOS to run that binary you will need to do additional steps:

After first try to run binary, you will encounter an error:
<img src="doc/images/macOS_error.jpeg" width="250" alt="MacOS error." />
To fix it, you should go to 'system settings->privacy and security', then scroll down and find:
<img src="doc/images/macOS_settings.jpeg" width="350" alt="MacOS settings." />
Click on 'Allow Anyway' and you should be able to use Tarantool Cli.

Build from source

Prerequisites

To run tests:

Build

git clone https://github.com/tarantool/tt --recursive
cd tt

You can build a binary without OpenSSL and TLS support for development purposes:

TT_CLI_BUILD_SSL=no mage build
mage build

You can build a binary with statically linked OpenSSL. This build type is used for releases:

TT_CLI_BUILD_SSL=static mage build

Finally, you can build a binary with dynamically linked OpenSSL for development purposes:

TT_CLI_BUILD_SSL=shared mage build

Dependencies

tt rocks runtime dependencies:

tt install && search runtime dependencies:

Run tests

Disable etcd service:

systemctl stop etcd
systemctl disable etcd

Create a virtual environment and install tests requirements:

python3 -m venv .venv

source .venv/bin/activate

pip install -r test/requirements.txt

Once inside the virtual environment, run default set of tests (excluding slow tests):

mage test

To run full set of tests:

mage testfull

Commit changes

The project uses pre-commit to check code before committing. After activating the virtual environment for run tests, the pre-commit hooks must be installed in the repository:

pre-commit install

Now you will perform automatic checks at every commit. The first time you use pre-commit it will install the dependencies needed for it to work, which may take some time. Subsequent runs will be much faster.

If errors were found, the commit will fail. If the errors can be corrected automatically, you will receive modified files to add to the commit, checking for correctness. In other cases you will get a message with errors that need to be corrected manually.

Configuration

Tarantool CLI can be launched in several modes:

System launch (flag -S) - the working directory is current, configuration file searched in /etc/tarantool directory.
Local launch (flag -L) - the working directory is the one you specified, configuration file is searched in this directory. If configuration file doesn't exists, config searched from the working directory to the root. If it is also not found, then take config from /etc/tarantool. If tarantool or tt executable files are found in working directory, they will be used further.
Default launch (no flags specified) - configuration file searched from the current directory to the root, going down the directory until file is found. Working directory - the one where the configuration file is found. If configuration file isn't found, config taken from /etc/tarantool directory. In this case working directory is current.

Configuration file

By default, configuration file is named tt.yaml.

You can specify the path to the configuration file by using the --cfg command line option or by setting the TT_CLI_CFG environment variable. The TT_CLI_CFG variable has a lower priority than the --cfg option.

Example of configuration file format:

env:
  instances_enabled: path/to/available/applications
  bin_dir: path/to/bin_dir
  inc_dir: path/to/inc_dir
  restart_on_failure: bool
  tarantoolctl_layout: bool
modules:
  directory: path/to/modules/dir
app:
  run_dir: path/to/run_dir
  log_dir: path/to/log_dir
  wal_dir: var/lib
  vinyl_dir: var/lib
  memtx_dir: var/lib
repo:
  rocks: path/to/rocks
  distfiles: path/to/install
ee:
  credential_path: path/to/file
templates:
  - path: path/to/templates_dir1
  - path: path/to/templates_dir2

env

instances_enabled (string) - path to directory that stores all applications.
bin_dir (string) - directory that stores binary files.
inc_dir (string) - directory that stores header files. The path w

Tt

Install / Use

README