Packaging the application
To package your application, use the
cartridge pack TYPE [PATH] [flags]
TYPE(required) is the distribution type. Supported types:
PATH(optional) is the path to the application directory. Defaults to
.(the current directory).
cartridge pack builds the application.
This process is similar to what
cartridge build does.
The resulting artifact includes
.rocks modules and executables
that are specific for the system where you’ve packaged the application.
For this reason, a distribution built on one OS can’t be used on another—for
example, an RPM built on MacOS can’t be installed on a CentOS machine.
However, you can work around this by enforcing package build in Docker
If you use open-source Tarantool, your artifact will have
tarantool as a
dependency. Its version will be the same as in your system’s
If you use Tarantool Enterprise, your artifact will contain the
tarantoolctl binaries from your current SDK.
The following flags control the local packaging of any distribution type, be it RPM, DEB, TGZ, or a Docker image.
The package and the systemd service will have the same name.
The default name comes from the
||Application package version.
By default, the version string is the output of
||The suffix of the resulting file or image name.
For example, a
||Force Cartridge to build the application in Docker. Enforced if you’re building a Docker image.|
||Disable path caching.
When used with
By default, the package is built inside a temporary directory in
~/.cartridge/tmp/. In this way, the packaging process doesn’t affect the contents
of your application directory.
When Cartridge copies your application files, it ignores the
All file permissions are preserved in the resulting package,
and the code files owner is set to
Make sure all your application files have at least
a+rx for directories). Otherwise,
cartridge pack will raise an error.
You can specify a custom build directory for your application using the
CARTRIDGE_TEMPDIR environment variable.
If this directory doesn’t exist, it will be created, used
for packaging the application, and then removed.
If you specify an existing directory in the
CARTRIDGE_TEMPDIR/cartridge.tmp directory will be used for
packaging the application and then removed.
Before the packaging starts, this nested directory will be cleaned up.
This may be useful if you want to use your Docker build with GitLab CI.
Docker volumes don’t work properly with the default tmp directory in this case.
CARTRIDGE_TEMPDIR=. cartridge pack ....
This section concern building Cartridge applications locally. To learn about building them in Docker, check the corresponding documentation page.
Whether you’re building a TGZ archive, an RPM/DEB distributable, or a Docker image, your application is built in three stages.
At this stage, some files are filtered out of the application directory.
git clean -X -d -fremoves all untracked and ignored files (it works for submodules, too).
- After that, the
.gitdirectory itself is removed.
At this stage,
cartridge runs the following:
./cartridge.pre-build, if it exists in the application root directory. Learn more about pre-build and post-build scripts. Instead of using the pre-build script, you can define the build logic by including
cmakecommands in your
.rockspec, like we do it in Cartridge.
tarantoolctl rocks make. This requires a
.rockspecfile in the application root directory. If you created your application from template, the file is already there.
cartridgeinstalls all dependencies specified in that file.
As a result, the fully built application will appear in the
You can start it locally from your application directory.
At this stage,
cartridge.post-build, if it exists.
The post-build script removes junk files (like
generated during application build.
Learn more about pre-build and post-build scripts.
The package generates
VERSION.lua, a file that contains the current version
of the project. When you connect to an instance with
you can check the project version by obtaining information from this file:
VERSION.lua is also used when you call
-- Getting the project version require('VERSION') -- Reloading the instances after making some changes to VERSION.lua require('cartridge').reload_roles() -- Getting the updated project version require('VERSION')
VERSION.lua is already in the application directory,
it will be overwritten during packaging.
You can cache paths for packaging Cartridge applications.
For example, if you package an application multiple times,
.rocks are installed every time over and over.
To speed up the repacking process, specify the cached paths in
a file located in the application root directory.
By default, the
.rocks directory is cached. The standard template’s
pack-cache-config.yml contains the path to that directory:
- path: '.rocks': key-path: 'myapp-scm-1.rockspec' - path: 'node_modules': always-cache: true - path: 'third_party/custom_module': key: 'simple-hash-key'
Make sure you specify the path to
.rocks from the application root directory
and provide a cache key. Let’s look at the example above:
<path-to-myapp>/.rockswill be cached depending on the content of
<path-to-myapp>/node_moduleswill always be cached.
<path-to-myapp>/third_party/custom_modulewill be cached depending on
You can’t combine these options. For example, you can’t specify
key-path at the same time.
One project path can only have one caching key.
Suppose you cached
.rocks with a
.rockspec file as
Then you changed the contents of
.rockspec and ran
In this case, the old cache (associated with the old key)
for the project’s
.rocks directory path will be deleted.
After packing, the new
.rocks cache path will be saved with the new key.
There can be no more than 5 projects in the cache that have cached paths. If the 6th project appears, the oldest existing project is removed from the cache directory. However, this is not the case for cached paths within a single project. You can cache as many paths as you like as long as they are in one project.
To disable caching, use the
--no-cache flag or remove
pack-cache-config.yml. To completely reset the cache,