- What is Tarantool
- Quick start
- What's on board
- Versions, tags, and release policy
- How to use these images
- Environment variables
TARANTOOL_USER_NAMETARANTOOL_USER_PASSWORDTARANTOOL_PORTTARANTOOL_PROMETHEUS_DEFAULT_METRICS_PORTTARANTOOL_REPLICATIONTARANTOOL_MEMTX_MEMORYTARANTOOL_SLAB_ALLOC_FACTORTARANTOOL_MEMTX_MAX_TUPLE_SIZETARANTOOL_MEMTX_MIN_TUPLE_SIZETARANTOOL_CHECKPOINT_INTERVALTARANTOOL_FORCE_RECOVERYTARANTOOL_LOG_FORMATTARANTOOL_LOG_LEVEL
- Reporting problems and getting help
- Contributing
Tarantool is an in-memory computing platform that combines a Lua application server and a database management system. Read more about Tarantool at tarantool.io.
To try out Tarantool, run this command:
$ docker run --rm -t -i tarantool/tarantoolIt will create a one-off Tarantool instance and open an interactive
console.
From there, you can either type tutorial() in the console or follow the
documentation.
The tarantool/tarantool images contain the Tarantool executable
and a combination of Lua modules and utilities often used in production.
Designed as a building block for modern services, these modules and utilities are based on a few
design choices that set them apart from the systemd-controlled Tarantool.
We check all these extensions for compatibility with the Tarantool version included in the image.
The Docker images come in three flavors, based on three different images: alpine:3.15, centos:7
and ubuntu:20.04. Check them out:
$ docker run --rm -t -i tarantool/tarantool:2.10.0
$ docker run --rm -t -i tarantool/tarantool:2.10.0-centos7
$ docker run --rm -t -i tarantool/tarantool:2.10.0-ubuntuThe entrypoint script in each of these images uses
environment variables
to set various configuration options,
such as replication sources, memory limits, and so on.
If specified, the environment variables override the settings provided in your code.
This way, you can set options using docker compose or
other orchestration and deployment tools.
There are also a few convenience tools that make use of the fact that there is only one Tarantool instance running in the container.
The following Lua modules are included in the build:
- avro-schema: Apache Avro scheme for your data.
- connpool: Keep a pool of connections to other Tarantool instances.
- curl: HTTP client based on libcurl.
- expirationd: Automatically delete tuples based on expiration time.
- gis: Store and query geospatial data.
- gperftools: Collect a CPU profile to find bottlenecks in your code.
- http: Embedded HTTP server with Flask-style routing support.
- memcached: Access Tarantool as if it was a memcached instance.
- metrics: Metric collection library for Tarantool.
- mqtt: Client for MQTT message brokers.
- mysql: Query MySQL right from Tarantool.
- pg: Query PostgreSQL right from Tarantool.
- prometheus: Instrument code and export metrics to Prometheus monitoring.
- queue: Priority queues with TTL and confirmations.
- vshard: Automatically distribute data across multiple instances.
If the module you need is not listed here, there is a good chance we can add it. Open an issue on our GitHub.
Mount these directories as volumes:
-
/var/lib/tarantoolcontains operational data (snapshots, xlogs and vinyl runs). -
/opt/tarantoolis the directory for Lua application code.
-
console: Execute without arguments to open an administrative console to a running Tarantool instance. -
tarantool_is_up: Returns0if Tarantool has been initialized and is operating normally. -
tarantool_set_config.lua: Allows you to dynamically change certain settings without the need to recreate containers.
The images are built and published on Docker Hub for each Tarantool release as well as for some beta and release candidate versions.
There are three variants built from different base images:
- Alpine 3.15, the "default" build with tags having no mention of base image, like
latest,1,2,1.10,1.10.z,2.y,2.y.zand others. - CentOS 7 with tags like
1-centos7,2-centos7, and so on. - Ubuntu 20.04 with tags like
1-ubuntu22.04,2-ubuntu22.04, and so on.
$ docker run \
--name mytarantool \
-p 3301:3301 -d \
tarantool/tarantoolThis will start an instance of Tarantool and expose it on port 3301. Note that by default there is no password protection, so don't expose this instance to the outside world.
In this case, as there is no Lua code provided, the entrypoint script initializes the database using a reasonable set of defaults. Some of them can be tweaked with environment variables (see below).
$ docker run \
--name mytarantool \
-p 3301:3301 \
-e TARANTOOL_USER_NAME=myusername \
-e TARANTOOL_USER_PASSWORD=mysecretpassword -d \
tarantool/tarantoolThis starts an instance of Tarantool, disables guest login, and
creates a user named myusername with admin privileges and the password
mysecretpassword.
As in the previous example, the database is initialized automatically.
$ docker exec -t -i mytarantool consoleThis will open an interactive admin console on the running instance
named mytarantool. You can safely detach from it anytime, the server
will continue running.
This console doesn't require authentication, because it uses a local
Unix socket in the container to connect to Tarantool. However, it requires
you to have direct access to the container.
If you need to access a remote console via TCP/IP, use the tt utility
as explained here.
You can start a replica set with Docker alone, but it's more
convenient to use docker-compose.
Here's a simplified docker-compose.yml for starting a master-master
replica set:
version: '2'
services:
tarantool1:
image: tarantool/tarantool:latest
environment:
TARANTOOL_REPLICATION: "tarantool1,tarantool2"
networks:
- mynet
ports:
- "3301:3301"
tarantool2:
image: tarantool/tarantool:latest
environment:
TARANTOOL_REPLICATION: "tarantool1,tarantool2"
networks:
- mynet
ports:
- "3302:3301"
networks:
mynet:
driver: bridgeStart it like this:
$ docker compose upThe simplest way to provide application code is to mount your code
directory to /opt/tarantool:
$ docker run \
--name mytarantool \
-p 3301:3301 -d \
-v /path/to/my/app:/opt/tarantool \
tarantool/tarantool \
tarantool /opt/tarantool/app.luaHere, /path/to/my/app is the host directory containing Lua code
and app.lua is the entry point of your application.
Note that for your code to run, you must execute the main script explicitly,
which is done in the last line.
To pack and distribute an image with your code,
create your own Dockerfile:
FROM tarantool/tarantool:2.10.0
COPY app.lua /opt/tarantool
CMD ["tarantool", "/opt/tarantool/app.lua"]Then build it with:
$ docker build -t company/appname:tag .Please pay attention to the format of CMD. Unless it is specified in
square brackets, the wrapper entrypoint that our Docker image
provides will not be called. In this case, you will not be able to configure
your instance using environment variables.
We recommend building from an image with a precise tag,
that is, 2.10.0 or 2.10.0-centos7, not
2.10 or latest.
This way you will have more control over the updates of
Tarantool and other dependencies of your application.
When you run this image, you can adjust some of Tarantool settings. Most of them either control memory/disk limits or specify external connectivity parameters.
If you need to fine-tune specific settings not described here, you can
always inherit this container and call box.cfg{} yourself.
See the
documentation on box.cfg for
details.
Setting this variable allows you to pick the name of the user that is
utilized for remote connections. By default, it is guest. Please
note that since the guest user in Tarantool can't have a password, it is
highly recommended that you change it.
For security reasons, it is recommended that you never leave this
variable unset. This environment variable sets the user's password for
Tarantool. In the above example, it is set to mysecretpassword.
Optional. Specifying this variable will tell Tarantool to listen for
incoming connections on a specific port. Default is 3301.
Optional. If specified, Tarantool will start an HTTP server on the provided port
and expose the Prometheus metrics endpoint with common metrics
(fibers, memory, network, replication, etc.).
Optional. Comma-separated list of URIs to treat as replication
sources. Upon start, Tarantool will attempt to connect to
those instances, fetch the data snapshot, and start replicating
transaction logs. In other words, it will become a slave. For a
multi-master configuration, other participating instances of
Tarantool should be started with the same TARANTOOL_REPLICATION.
(NB: Applicable only to versions later than 1.7.)
Example:
user1:pass@host1:3301,user2:pass@host2:3301
Optional. Specifies how much memory Tarantool allocates to
actually store tuples, in bytes. When the limit is reached, INSERT
or UPDATE requests begin failing. Default is 268435456 (256
megabytes).
Optional. Used as the multiplier for computing the sizes of memory
chunks that tuples are stored in. A lower value may result in less
wasted memory, depending on the total amount of memory available
and the distribution of item sizes. Default is 1.05.
Optional. Size of the largest allocation unit in bytes. It can be
increased if it is necessary to store large tuples. Default is
1048576.
Optional. Size of the smallest allocation unit, in bytes. It can be
decreased if most of the tuples are very small. Default is 16.
Optional. Specifies how often snapshots are made, in seconds.
Default is 3600 (every 1 hour).
Optional. When set to true, Tarantool tries to continue if there is an error while
reading a snapshot file or a write-ahead log file.
Skips invalid records, reads as much data as possible,
print a warning in console and start the database.
Optional. There are two possible log formats:
- 'plain' — the default one.
- 'json' — with more details and with JSON labels.
More details can be found in the log module reference.
Optional. Default value is 5 (that means INFO). More details can be found in log level configuration.
You can report problems and request features on our GitHub.
Alternatively, you may get help on our Telegram channel.
Open a pull request to the master branch.
A maintainer is responsible for merging the PR.
Say, we have updated 'dockerfiles/alpine_3.9' and want to check it:
$ TAG=2 OS=alpine DIST=3.9 VER=2.x PORT=5200 make -f .github.mk build
$ docker run -it tarantool/tarantool:2
...perform a test...Fixed release versions:
| Docker tag | FROM | Dockerfile |
|---|---|---|
| 2.10.0 | alpine:3.15 | dockerfile/alpine_3.15 |
| 2.10.0-centos7 | centos:7 | dockerfile/centos_7 |
| 2.10.0-ubuntu20.04 | ubuntu:20.04 | dockerfile/ubuntu_20.04 |
| 2.10.0-rc1 | alpine:3.9 | dockerfile/alpine_3.9 |
| 2.10.0-beta2 | alpine:3.9 | dockerfile/alpine_3.9 |
| 2.10.0-beta1 | alpine:3.9 | dockerfile/alpine_3.9 |
| 2.8.0 .. 2.8.4 | alpine:3.9 | dockerfile/alpine_3.9 |
| 2.7.0 .. 2.7.3 | alpine:3.9 | dockerfile/alpine_3.9 |
| 2.6.0 .. 2.6.3 | alpine:3.9 | dockerfile/alpine_3.9 |
| 2.5.0 .. 2.5.3 | alpine:3.9 | dockerfile/alpine_3.9 |
| 2.4.0 .. 2.4.3 | alpine:3.9 | dockerfile/alpine_3.9 |
| 2.3.1 .. 2.3.3 | alpine:3.9 | dockerfile/alpine_3.9 |
| 2.3.0 | alpine:3.5 | dockerfile/alpine_3.5 |
| 2.2.2 .. 2.2.3 | alpine:3.9 | dockerfile/alpine_3.9 |
| 2.2.0 .. 2.2.1 | alpine:3.5 | dockerfile/alpine_3.5 |
| 2.1.3 | alpine:3.9 | dockerfile/alpine_3.9 |
| 2.1.0 .. 2.1.2 | alpine:3.9 | dockerfile/alpine_3.5 |
| 1.10.13 | alpine:3.9 | dockerfile/alpine_3.9 |
| 1.10.4 .. 1.10.12 | alpine:3.9 | dockerfile/alpine_3.9 |
| 1.10.0 .. 1.10.3 | alpine:3.5 | dockerfile/alpine_3.5 |
Rolling versions:
| Docker tag | Dockerfile |
|---|---|
| 2, latest | dockerfile/alpine_3.15 |
| 2-centos7 | dockerfile/centos_7 |
| 1 | dockerfile/alpine_3.15 |
| 1 | dockerfile/alpine_3.15 |
| 2.1 .. 2.8 | dockerfile/alpine_3.9 |
| 2.1 .. 2.8 | dockerfile/alpine_3.9 |
Special builds:
| Docker tag | Dockerfile |
|---|---|
| 2.10.0-centos7 | dockerfile/centos_7 |
| 2.10.0-ubuntu | dockerfile/ubuntu_20.04 |
| 1.x-centos7 | dockerfile/centos_7 |
| 2.x-centos7 | dockerfile/centos_7 |
All images are pushed to Docker Hub.
Fixed version tags (x.y.z) are frozen: we never update them.
Example of versions timeline for Tarantool since 2.10 (see the release policy):
2.10.0-beta1— Beta2.10.0-rc1— Release candidate2.10.0— Release (stable)
Example of minor versions timeline for Tarantool up to 2.8:
x.y.0- Alphax.y.1- Betax.y.2- Stablex.y.3- Stable
Rolling versions are updated to the latest release (stable) versions:
x.y==x.y.latest-z(==means 'points to the same image')1==1.10.latest-z2==2.latest-y.zlatest==2
Special stable builds (CentOS) are updated with the same policy as rolling versions:
1.x-centos7image offers a last1.<last-y>.2release2.x-centos7image offers a last2.<last-y>.2release
As an exception we can deliver an important update for the existing tarantool
release within x.y.z-r1, x.y.z-r2, ... tags.
When x.y.z-r<N> is released, the corresponding rolling releases (x.y, x
and latest if x == 2) should be updated to point to the same image.
There is no strict policy, which updates should be considered important. Let's decide on demand and define the policy later.
TBD: How to notify users about the exceptional updates?
Example:
$ export TAG=2
$ export OS=alpine DIST=3.9 VER=2.x # double check the values!
$ PORT=5200 make -f .github.mk build
$ docker push tarantool/tarantool:${TAG}
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent