Tarantool Cartridge — a framework for distributed applications development
Table of contents
- About Tarantool Cartridge
- Getting Started
- Create first application
- Next stages
- Contribution
- Building from source
- Running demo cluster
- Auto-generated sources
- Running tests
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:
- Step-by-step
getting started guide
in the
<code>cartridge-cli</code>
repository. - Documentation page
- API Reference
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:
<code>tarantool</code><code>, </code><code>tarantool-dev</code>
(instructions: https://www.tarantool.io/en/download/?v=1.10);<code>git</code><code>, </code><code>gcc</code><code>, </code><code>cmake</code>
.
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:
<code>nodejs</code>
>= 8 (instructions);<code>npm</code>
>= 6.
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 accesed trhough 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