Developer’s guide

Packaging applications

Once custom cluster role(s) are defined and the application is developed, pack it and all its dependencies (module binaries) together with the tarantool executable.

This will allow you to upload, install, and run your application on any server in one go.

To pack the application, say:

$ tt pack [rpm|tgz] /path/to/<app_name>

where specify a path to your development environment – the Git repository containing your application code, – and one of the following build options:

• rpm to build an RPM package (recommended), or
• tgz to build a tar + gz archive (choose this option only if you do not have root privileges on servers dedicated for Tarantool Enterprise).

This will create a package (or compressed archive) named <app_name>-<version_tag>-<number_of_commits> (e.g., myapp-1.2.1-12.rpm) containing your environment-independent application.

Next, proceed to deploying packaged applications (or archived ones) on your servers.

Deploying packaged applications

To deploy your packaged application, do the following on every server dedicated for Tarantool Enterprise:

1. Upload the package created in the previous step.

2. Install:

   $ yum install <app_name>-<version>.rpm
   

3. Start one or multiple Tarantool instances with the corresponding services as described below.

   • A single instance:

     $ systemctl start <app_name>
     

     This will start an instantiated systemd service that will listen to port 3301.

   • Multiple instances on one or multiple servers:

     $ systemctl start <app_name>@instance_1
     $ systemctl start <app_name>@instance_2
     ...
     $ systemctl start <app_name>@instance_<number>
     

     where <app_name>@instance_<number> is the instantiated service name for systemd with an incremental <number> (unique for every instance) to be added to the 3300 port the instance will listen to (e.g., 3301, 3302, etc.).

4. In case it is a cluster-aware application, proceed to deploying the cluster.

To stop all services on a server, use the systemctl stop command and specify instance names one by one. For example:

$ systemctl stop <app_name>@instance_1 <app_name>@instance_2 ... <app_name>@instance_<N>

Deploying archived applications

While the RPM package places your application to /usr/share/tarantool/<app_name> on your server by default, the tar + gz archive does not enforce any structure apart from just the <app_name>/ directory, so you are responsible for placing it appropriately.

To place and deploy the application, do the following on every server dedicated for Tarantool Enterprise:

1. Upload the archive, decompress, and extract it to the /home/<user>/apps directory:

   $ tar -xzvf <app_name>-<version>.tar.gz -C /home/<user>/apps
   

2. Start Tarantool instances with the corresponding services.

   To manage instances and configuration, use tools like ansible, systemd, and supervisord.

3. In case it is a cluster-aware application, proceed to deploying the cluster.

Upgrading code

All instances in the cluster are to run the same code. This includes all the components: custom roles, applications, module binaries, tarantool, and tt (if necessary) executables.

Pay attention to possible backward incompatibility that any component may introduce. This will help you choose a scenario for an upgrade in production. Keep in mind that you are responsible for code compatibility and handling conflicts should inconsistencies occur.

To upgrade any of the components, prepare a new version of the package (archive):

1. Update the necessary files in your development environment (directory):
   • Your own source code: custom roles and/or applications.
   • Module binaries.
   • Executables. Replace them with ones from the new bundle.
2. Increment the version as described in application versioning.
3. Repack the updated files as described in packaging applications.
4. Choose an upgrade scenario as described in the Upgrading in production section.

Write-through cache application for PostgreSQL

The example in pg_writethrough_cache/ shows how Tarantool can cache data written through it to a PostgreSQL database to speed up the reads.

The sample application requires a deployed PostgreSQL database and the following rock modules:

$ tt rocks install http
$ tt rocks install pg
$ tt rocks install argparse

Look through the code in the files to get an understanding of what the application does.

To run the application for a local PostgreSQL database, say:

$ tarantool cachesrv.lua --binary-port 3333 --http-port 8888 --database postgresql://localhost/postgres

Write-behind cache application for Oracle

The example in ora-writebehind-cache/ shows how Tarantool can cache writes and queue them to an Oracle database to speed up both writes and reads.

$ tt rocks make oracle_rb_cache-0.1.0-1.rockspec

$ tarantool init.lua

Hello-world application in Docker

The example in the docker/ directory contains a hello-world application that you can pack in a Docker container and run on CentOS 7.

The hello.lua file is the entry point and it is very bare-bones, so you can add your code here.

1. To build the container, say:

   $ docker build -t tarantool-enterprise-docker -f Dockerfile ../..
   

2. To run it:

   $ docker run --rm -t -i tarantool-enterprise-docker