User’s Guide / Tarantool Cartridge / Table of contents / Tarantool Cartridge — a framework for distributed applications development
User’s Guide / Tarantool Cartridge / Table of contents / Tarantool Cartridge — a framework for distributed applications development

Tarantool Cartridge — a framework for distributed applications development

Tarantool Cartridge — a framework for distributed applications development

About Tarantool Cartridge

Tarantool Cartridge allows you to easily develop Tarantool-based applications and run them on one or more Tarantool instances organized into a cluster.

As a cluster management tool, Tarantool Cartridge provides your cluster-aware applications with the following key benefits:

  • horizontal scalability and load balancing via built-in automatic sharding;
  • asynchronous replication;
  • automatic failover;
  • centralized cluster control via GUI or API;
  • automatic configuration synchronization;
  • instance functionality segregation.

A Tarantool Cartridge cluster can segregate functionality between instances via built-in and custom (user-defined) cluster roles. You can toggle instances on and off on the fly during cluster operation. This allows you to put different types of workloads (e.g., compute- and transaction-intensive ones) on different physical servers with dedicated hardware.

Tarantool Cartridge has an external utility called cartridge-cli which provides you with utilities and templates to help:

  • easily set up a development environment for your applications;
  • plug the necessary Lua modules;
  • pack the applications in an environment-independent way: together with module binaries and Tarantool executables.

Getting Started

Create first application

To get a template application that uses Tarantool Cartridge and run it you need to install cartridge-cli utility (supposing that Tarantool is already installed).

Long story short, copy-paste it into console:

tarantoolctl rocks install cartridge-cli
.rocks/bin/cartridge create --name myapp
cd myapp
../.rocks/bin/cartridge build
../.rocks/bin/cartridge start

That’s all! You can visit http://localhost:8081 and see your application Admin Web UI:

Next stages

See:

Contribution

From the point of view of cartridge contributor, the workflow differs: it implies building the project from source (documentation, webui) and running tests.

Building from source

Prerequisites:

The fastest way to build the project is to skip building Web UI:

CMAKE_DUMMY_WEBUI=true tarantoolctl rocks make

But if you want to build frontend too, you’ll also need:

Documentation is generated from source code, but only if ldoc tool is installed:

tarantoolctl rocks install ldoc --server=http://rocks.moonscript.org
tarantoolctl rocks make

Running demo cluster

There are several example entrypoints which are mostly used for testing, but can also be useful for demo purposes or experiments:

tarantoolctl rocks install cartridge-cli
.rocks/bin/cartridge start

# or select specific entrypoint
# .rocks/bin/cartridge start --script ./test/entrypoint/srv_basic.lua

It can be accessed through Web UI (http://localhost:8081) or with binary protocol:

tarantoolctl connect admin@localhost:3301

For more detailed information about cartridge-cli see here.

Auto-generated sources

After GraphQL API is changed one shouldn’t forget to fetch the schema doc/schema.graphql:

npm install graphql-cli@3.0.14
./fetch-schema.sh

Running tests

# Backend
tarantoolctl rocks install luacheck
tarantoolctl rocks install luatest 0.5.0
.rocks/bin/luacheck .
.rocks/bin/luatest -v --exclude cypress

# Frontend
npm install cypress@3.4.1
./frontend-test.sh
.rocks/bin/luatest -v -p cypress

# Collect coverage
tarantoolctl rocks install luacov
tarantoolctl rocks install luacov-console
.rocks/bin/luatest -v --coverage
.rocks/bin/luacov-console `pwd`
.rocks/bin/luacov-console -s