The in-memory database Tarantool is great for microservice architectures because it is versatile and self-sufficient:

• It includes a full Lua application server that runs concurrent to its database server, which allows it to function without an additional back-end language.

• It's fully ACID, so can handle transactional workloads.

• It's persistent and can work with data sets larger than RAM.

But when you run a Tarantool microservice, you need a way to start it, keep it alive, and manage it. So this guide will demonstrate how to use tarantoolctl, the utility that accomplishes these tasks for Tarantool instances. We'll learn tarantoolctl by creating a microservice that inserts the IP addresses of visitors to a webpage into a database. Note that if you haven't read Tarantool 101: Guide 1, which teaches the absolute basics of Tarantool, you should probably start there (or at the very least, you'll need to install Tarantool as well as its HTTP module before using this guide).

The “training wheels” aspect of Guide 1 was that we ran everything from a single file. A Tarantool best practice, however, is to use two files for an instance: one for config code (which DBAs would presumably be responsible for) and one for application code (which developers would be responsible for). This enables you to, for example, run multiple Tarantool instances simultaneously with the same application code, using a different config file for each one.

1. Create the Config Code File Our Instance

So, let's begin by using nano to create a config file for our application in the following location:

nano /etc/tarantool/instances.enabled/iplogger.lua

In the file, we'll place the code that a) calls and configures our database, b) creates a space after first checking whether a space with that name exists, c) creates a primary index — because at least one index is required for a Tarantool application, and d) calls in the application code from the file that we will create in the next step:       

box.cfg{}

if not box.space.bigspace then
    s = box.schema.space.create('bigspace')
    s:create_index('primary',
        {type = 'tree', parts = {1, 'unsigned'}})
end  

local m = require('iplogger').start({...})

Note that we have created this file in the instances.enabled directory to keep things simple, but you could also place it in instances.available and have a symlink to instances.enabled (similar to NGINX).

2. Create the Application Code File for Our Instance

Let's use nano again to create the application code file in the following location:

nano /usr/share/tarantool/iplogger.lua

Then the code:

function handler(self)
    local selfVar = self.peer.host;
    box.space.bigspace:auto_increment{selfVar};
    return self:render({
        json = selfVar
    })
end

function start()
    local server = require('http.server').new(nil, 8081)
    server:route({ path = '/'}, handler)
    server:start()
end

return {
    start = start;
}

Let’s begin by looking at the second function here, which is basically the same server code from Guide 1. However, we have wrapped it in the start function and exported it, which enables us to call it from the config file that we made earlier. As regards the top function, similar to Guide 1, the server calls the handler function on the root route. The handler function collects the IP (self.peer.host) and then inserts it into the database using auto_increment, which adds a new key to the database along with our data (which we assigned to the variable selfVar). It then sends the data to the front end.

3. Check the Syntax

We can take a slight break for a moment to check the syntax of our two files. This is a nice additional functionality of  tarantoolctl:          

tarantoolctl check /usr/share/tarantool/iplogger.lua   

Then:

tarantoolctl check /etc/tarantool/instances.enabled/iplogger.lua

4. Start Application With tarantoolctl and Check Its Status

Now we can start our iplogger application. tarantoolctl can be started from any location on your server:

tarantoolctl start iplogger

You will get a message stating that the application has started. Once you receive that, you can check the status of the application with:

tarantoolctl status iplogger

5. Visit Our Server's IP and Log Our Browsing IP

We can now visit our server's IP, which will log our browsing IP. Similar to the previous tutorial, visit the server's IP on port 8081:

youripaddress:8081

You will see your browsing IP address displayed because we are sending it back from Tarantool to the browser. Refresh the page several times so that multiple records are inserted into the database.

6. Stop the Application

Now, let’s stop our application.    

tarantoolctl stop iplogger

7. Show Our Logged Data

Next, we'll start the Tarantool console to see that our IPs were logged. This brings me to something that should be pointed out: the console cannot be run in just any directory like tarantoolctl  can. Rather, you need to run it in the same directory as your snapshot and log files. This can be specified in a config file but the default is /var/lib/tarantool. So let’s go there:

cd /var/lib/tarantool/iplogger

 Then:  

tarantool

This is followed by the usual:

 box.cfg{}       

Now let’s display the contents of bigspace:

box.space.bigspace:select()

You should see your IP records in tuples:

Additional Notes

There are a few other things I wanted to mention:

• tarantoolctl piggybacks on the Unix utility systemd.

• The config file we used was tailored to our iplogger application but tarantoolctl has its own config file, as well ( etc/default/tarantool), which overrides anything in the individual config files.

• It is generally advised to run one Tarantool application per CPU core at scale.

Now that you have seen how powerful, yet simple, Tarantool is, I hope that you will try out other ideas for microservices using it. Please let us know what you accomplish. I can be emailed directly at evan@tarantool.io, and if you would like to learn more about our enterprise support services, please fill out the form here.