Creating an application from template | Tarantool

Creating an application from template

To create an application from a Cartridge template, run this in any directory:

cartridge create [path] [flags]

--name Application name.
--from Path to the application template. See details below.
--template Name of the application template. Currently, only the cartridge template is supported.

create also supports global flags.

Your application will appear in the <path>/<app-name>/ directory.

The template used by default is cartridge. It produces a simple Cartridge application that includes:

  • One custom role with an HTTP endpoint.
  • Sample tests and basic test helpers.
  • Development files like .luacheckrc.

If you have git installed, a Git repository with a .gitignore file will be also set up in the project root directory. The initial commit will be created and tagged with the application version.

Let’s take a closer look at the files inside the <app_name>/ directory:

  • Application files:

    • app/roles/custom-role.lua: a sample custom role with a simple HTTP API. Can be enabled as app.roles.custom.
    • <app_name>-scm-1.rockspec: contains application dependencies.
    • init.lua: application entry point.
    • stateboard.init.lua application stateboard entry point.
  • Build and packaging files:

    • cartridge.pre-build
    • Dockerfile.cartridge

    To learn more, check the documentation on pre-build and post-build scripts, building your application with Docker, and creating a Docker image of your application.

  • Development files:

    • resolves dependencies listed in the .rockspec file and installs test dependencies (like luatest).
    • instances.yml contains the configuration of instances and is used by cartridge start.
    • .cartridge.yml contains the Cartridge configuration and is also used by cartridge start.
    • systemd-unit-params.yml contains systemd parameters.
    • tmp is a directory for temporary files used as a run directory (see .cartridge.yml).
    • .git is the directory responsible for the Git repository.
    • .gitignore is a file where you can specify the files for Git to ignore.
  • Test files (with sample tests):

├── helper
│   ├── integration.lua
│   └── unit.lua
│   ├── helper.lua
│   ├── integration
│   │   └── api_test.lua
│   └── unit
│       └── sample_test.lua
  • Configuration files:
    • .luacheckrc
    • .luacov
    • .editorconfig

By default, create uses a standard template named cartridge. However, you can also make a custom template. To create an application from it, run cartridge create with the --from flag, specifying the path to your template.

If the template directory is a Git repository, all files in the .git directory will be ignored upon instantiating the template. Instead, a new git repo will be initialized for the newly created application.

Don’t include the .rocks directory in your template application. To specify application dependencies, use the .rockspec and cartridge.pre-build files.

Filenames and content can contain text templates.

You can use the following variables:

  • Name: application name.
  • StateboardName: application stateboard name (<app-name>-stateboard).
  • Path: absolute path to the application.

For example:

├── {{ .Name }}-scm-1.rockspec
└── init.lua
└── stateboard.init.lua
└── test
    └── sample_test.lua


print("Hi, I am {{ .Name }} application")
print("I also have a stateboard named {{ .StateboardName }}")
Found what you were looking for?