Руководство для разработчика

To develop an application, use the Tarantool Cartridge framework that is installed as part of Tarantool Enterprise Edition.

Ниже приведен список необходимых команд:

Создайте приложение с поддержкой кластеров из шаблона:
```
$ tt create cartridge --name <app_name> -d /path/to
```
Разработайте приложение:
```
$ cd /path/to/<app_name>
$ ...
```

Упакуйте приложение:

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

Разверните приложение:
- Для пакета rpm:
  1. Загрузите пакет на все серверы, выделенные для Tarantool.
  2. Установите пакет:
    $ yum install <app_name>-<version>.rpm
  3. Запустите приложение.
    $ systemctl start <app_name>
- Для архива tgz:
  1. Загрузите архив на все серверы, выделенные для Tarantool.
  2. Распакуйте архив:
    $ tar -xzvf <app_name>-<version>.tar.gz -C /home/<user>/apps
  3. Запустите приложение
    $ tarantool init.lua

Более подробную информацию с примерами см. на следующих страницах:

руководство для начинающих, в котором пошагово разбирается разработка и развертывание простого кластерного приложения с помощью Tarantool Cartridge,
a detailed manual on creating and managing clustered Tarantool applications using Tarantool Cartridge.

Кроме того, в этом руководстве особое внимание уделяется функциям разработчика, специфичным для Enterprise-версии, которые доступны в дополнение к Tarantool Community Edition в среде Tarantool Cartridge:

авторизация с использованием LDAP в веб-интерфейсе,
независимые от среды приложения,
примеры приложений, которые подходят для Enterprise-версии.

Реализация авторизации с использованием LDAP в веб-интерфейсе

If you run an LDAP server in your organization, you can connect Tarantool Enterprise to it and let it handle the authorization. In this case, follow the general recipe where in the first step add the ldap module to the .rockspec file as a dependency and consider implementing the check_password function the following way:

-- auth.lua
-- Require the LDAP module at the start of the file
local ldap = require('ldap')
...
-- Add a function to check the credentials
local function check_password(username, password)

    -- Configure the necessary LDAP parameters
    local user = string.format("cn=%s,ou=tarantool,dc=glauth,dc=com", username)

    -- Connect to the LDAP server
    local ld, err = ldap.open("localhost:3893", user, password)

    -- Return an authentication success or failure
    if not ld then
       return false
    end
    return true
end
 ...

Формирование независимых от среды приложений

Tarantool Enterprise позволяет создавать независимые от среды приложения.

Независимое от среды приложение представляет собой сборку следующих компонентов (в одной директории):

файлы с кодом на Lua,
исполняемый файл tarantool,
подключенные внешние модули (при необходимости).

Запущенное с помощью исполняемого файла tarantool приложение обеспечивает работу сервиса.

Модули – это сторонние библиотеки на Lua, установленные в виртуальную среду (в директории приложения), которая аналогична virtualenv в Python и bundler в Ruby.

Структура такого приложения остается неизменной как на стадии разработки, так и на стадии производственной эксплуатации. Весь связанный с приложением код находится в одном месте, готов к упаковке и копированию на любой сервер.

Упаковка приложений

После определения пользовательских кластерных ролей и разработки приложения упакуйте его со всеми зависимостями (бинарные файлы модулей) и с исполняемым файлом tarantool.

Это позволит вам легко загружать, устанавливать и запускать приложение на любом сервере.

Чтобы упаковать приложение, выполните команду:

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

где укажите путь к вашей среде разработки (репозиторию Git, который содержит код приложения), а также один из параметров сборки:

rpm для сборки RPM-пакета (рекомендуется), или
tgz для сборки архива tar + gz (выберите этот параметр, только если у вас нет прав уровня root на серверах, выделенных для Tarantool Enterprise).

В результате будет создан пакет (или сжатый архив) с именем <имя_приложения>-<версия_тег>-<количество_коммитов> (например, myapp-1.2.1-12.rpm), который будет хранить ваше приложение в не зависимом от среды виде.

Далее переходите к развертыванию пакетных (или же архивированных) приложений на серверах.

Развертывание пакетных приложений

Чтобы развернуть пакетное приложение, выполните следующие действия на каждом сервере, выделенном для Tarantool Enterprise:

Загрузите локально пакет, созданный на предыдущем шаге.
Установите приложение:
```
$ yum install <app_name>-<version>.rpm
```
Запустите один или несколько экземпляров Tarantool с соответствующими сервисами, как описано ниже.
- Отдельный экземпляр:
```
$ systemctl start <app_name>
```
  Это запустит экземпляр сервиса systemd с прослушиванием по порту 3301.
- Несколько экземпляров на одном или нескольких серверах:
```
$ systemctl start <app_name>@instance_1
$ systemctl start <app_name>@instance_2
...
$ systemctl start <app_name>@instance_<number>
```
  где <app_name>@instance_<number> (<имя_приложения>@экземпляр_<число>) – это имя экземпляра сервиса systemd с инкрементным числом <number> (уникальным для каждого экземпляра), которое следует добавить к порту 3300 для настройки прослушивания (например, 3301, 3302 и т.д.).
In case it is a cluster-aware application, proceed to deploying the cluster.

Чтобы остановить все сервисы на сервере, используйте команду systemctl stop и укажите имена экземпляров по одному. Например:

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

Развертывание архивированных приложений

Тогда как пакет RPM по умолчанию помещает ваше приложение в /usr/share/tarantool/<имя_приложения> на вашем сервере, архив tar + gz не создает какую-либо структуру, помимо директории <имя_приложения>/, поэтому вы сами несете ответственность за правильность размещения приложения.

Примечание

Для развертывания рекомендуется использовать RPM-пакеты. Развертывайте архивы, только если у вас нет прав уровня root.

Чтобы разместить и развернуть приложение, выполните следующие действия на каждом сервере, выделенном для Tarantool Enterprise:

Загрузите архив, распакуйте его и извлеките содержимое в директорию /home/<user>/apps:
```
$ tar -xzvf <app_name>-<version>.tar.gz -C /home/<user>/apps
```
Запустите экземпляры Tarantool с соответствующими сервисами.

Для управления и конфигурации экземпляров используйте такие средства, как ansible, systemd и supervisord.
In case it is a cluster-aware application, proceed to deploying the cluster.

Обновление кода

Все экземпляры в кластере должны использовать один и тот же код. Это относится ко всем компонентам: пользовательским ролям, приложениям, бинарным файлам модулей, исполняемым файлам tarantool и tt (при необходимости).

Обратите внимание на возможную обратную совместимость, которую может принести с собой любой компонент. Это поможет вам выбрать сценарий для обновления в эксплуатационной среде. Имейте в виду, что вы несете ответственность за совместимость кода и обработку конфликтов в случае возникновения несоответствий.

Чтобы обновить любой из компонентов, подготовьте новую версию пакета (архива):

Обновите необходимые файлы в вашей среде разработки (директории):
- Ваш собственный исходный код: пользовательские роли и / или приложения.
- Бинарные файлы модулей.
- Исполняемые файлы. Замените их на файлы из нового комплекта.
Increment the version as described in application versioning.
Повторно упакуйте обновленные файлы, как описано в разделе по упаковке приложений.
Выберите сценарий обновления, как описано в разделе по обновлению в эксплуатационной среде.

Запуск примеров приложений

Дистрибутив Enterprise включает в себя примеры приложений в директории examples/, которые демонстрируют основные функциональные возможности Tarantool.

Примеры приложений:

Приложение кэширования со сквозной записью в PostgreSQL
Приложение кэширования с отложенной записью в Oracle
Простейшее приложение в Docker

Приложение кэширования со сквозной записью в PostgreSQL

Пример в pg_writethrough_cache/ показывает, как Tarantool может кэшировать данные, записанные через него в базу данных PostgreSQL для ускорения запросов на чтение.

Для примера приложения требуется развернутая база данных PostgreSQL и следующие модули сторонних библиотек:

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

Просмотрите код в файлах, чтобы понять, что может делать приложение.

Чтобы запустить приложение для локальной базы данных PostgreSQL, выполните команду:

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

Приложение кэширования с отложенной записью в Oracle

Пример в ora-writebehind-cache/ показывает, как Tarantool может кэшировать записи и помещать их в базу данных Oracle для ускорения как записи, так и чтения.

Требования приложения

Для примера приложения необходимы:

развернутая база данных Oracle;
инструменты Oracle: Instant Client and SQL Plus, оба версии 12.2;

Примечание

Если Oracle Instant Client выдает ошибки в файлах с расширением .so (динамические библиотеки Oracle), поместите их в какую-либо директорию и добавьте ее в переменную окружения LD_LIBRARY_PATH.

Например: export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$PWD/<путь_к_файлам_so>
модули сторонних библиотек, перечисленные в файле rockspec.

Чтобы установить модули, выполните следующую команду в директории examples/ora_writebehind_cache:

$ tt rocks make oracle_rb_cache-0.1.0-1.rockspec

Если у вас нет развернутого экземпляра Oracle под рукой, запустите пустой объект в контейнере Docker:

В браузере войдите в Реестр контейнеров Oracle, выберите Database (База данных) и примите «Корпоративные условия и ограничения Oracle».

В директории ora-writebehind-cache/ войдите в репозиторий под учетной записью Oracle, получите данные и запустите образ с помощью подготовленных скриптов

$ docker login container-registry.oracle.com
Login:
Password:
Login Succeeded
$ docker pull container-registry.oracle.com/database/enterprise:12.2.0.1
$ docker run -itd \
   -p 1521:1521 \
   -p 5500:5500 \
   --name oracle \
   -v "$(pwd)"/setupdb/configDB.sh:/home/oracle/setup/configDB.sh \
   -v "$(pwd)"/setupdb/runUserScripts.sh:/home/oracle/setup/runUserScripts.sh \
   -v "$(pwd)"/startupdb:/opt/oracle/scripts/startup \
   container-registry.oracle.com/database/enterprise:12.2.0.1

Когда всё будет готово, запустите пример приложения.

Запуск кэширования с отложенной записью

Чтобы запустить приложение, выполните следующую команду в директории examples/ora_writebehind_cache:

$ tarantool init.lua

Данное приложение поддерживает следующие запросы:

Получение данных: GET http://<host>:<http_port>/account/id;
Добавление: POST http://<host>:<http_port>/account/ со следующими данными:
```
{"clng_clng_id":1,"asut_asut_id":2,"creation_data":"01-JAN-19","navi_user":"userName"}
```
Обновление: POST http://<host>:<http_port>/account/id с теми же данными, что и в запросе на добавление;
Удаление: DELETE http://<host>:<http_port>/account/id,где id – это идентификатор учетной записи.

Взгляните на примеры скриптов CURL в директории examples/ora_writebehind_cache/testing и просмотрите файл README.md для получения дополнительной информации об их использовании.

Простейшее приложение в Docker

Пример в директории docker/ содержит простейшее приложение, которое можно упаковать в контейнер Docker и запустить на CentOS 7.

Файл hello.lua представляет собой элементарную точку входа в приложение, поэтому вы можете добавить туда собственный код.

Чтобы создать контейнер, выполните команду:
```
$ docker build -t tarantool-enterprise-docker -f Dockerfile ../..
```

Чтобы запустить его:

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

Версия:

Руководство для разработчика

Реализация авторизации с использованием LDAP в веб-интерфейсе

Формирование независимых от среды приложений

Упаковка приложений

Развертывание пакетных приложений

Развертывание архивированных приложений

Обновление кода

Запуск примеров приложений

Приложение кэширования со сквозной записью в PostgreSQL

Приложение кэширования с отложенной записью в Oracle

Требования приложения

Запуск кэширования с отложенной записью

Простейшее приложение в Docker