Skip to content

Application templates

tt create creates an application from a template.

A template is a built-in one, named by its name (tt create cluster), or a template of your own, given by its path: a directory, or a .tgz or .tar.gz archive, which may be named without its extension (tt create ./templates/basic). A path is told from a name by a slash in it, so a template in the current directory is given as ./<name>.

The application is created in the --name directory of the current directory, or of the --dst directory.

Built-in templates

The built-in templates are single_instance, cluster, vshard_cluster and config_storage. Each of them creates a project that starts on localhost as it is: the code of the application in the project directory, and the pair it runs from, instances.yaml and config.yaml, in .templates/default/:

$ tt create cluster --name app1
app1/
├── .templates
│   └── default
│       ├── config.yaml
│       └── instances.yaml
└── app.lua

app.file and the other paths of config.yaml are relative to the project directory, the directory the instances run in; the data, logs and sockets go to .tarantool/var/ there. A package installed from an archive runs in a directory that holds only what the archive carries, so the config of a package loads its code as app.module, not as app.file; see Packing. The project is named after its directory; vshard_cluster also writes app.manifest.toml, which names it --name with _ replaced by -, and needs tt package build for its vshard dependency before it starts. config_storage needs Tarantool Enterprise Edition, which provides the config.storage role.

When the template writes app.manifest.toml, tt create refuses a --name that does not make a package name there - lowercase letters, digits and dashes, starting with a letter - and creates nothing: --name my_app gives vshard_cluster the name my-app, --name My_App is refused.

Templates of your own

A template of your own creates a project laid out as the built-in ones do. It carries the pair in .templates/<name>/, where its files are instantiated like any other, or anywhere else: tt create moves the instances.yaml of the template's root, or of the one directory of it that holds one, and the config.yaml beside it, into .templates/default/. A config.yaml alone at the root is the pair of a template of the config alone and is moved too. The paths of the pair are relative to the project directory wherever the pair lies, so the move changes nothing of what it says. Everything else stays where the template has it.

tpl/                        $ tt create ./tpl --name myapp
├── config.yaml             myapp/
├── init.lua                ├── .templates
└── instances.yaml          │   └── default
                            │       ├── config.yaml
                            │       └── instances.yaml
                            └── init.lua

A template that keeps a pair in .templates/ already is left as it is, with a config.yaml of its root, which is then a file of the application. An instances.yaml in more than one directory, or a file the move would put over one in .templates/default/, is an error.

The result must be a project: tt create refuses a template that writes neither app.manifest.toml nor a pair, and creates nothing. With an include list in MANIFEST.yaml, list the pair there too, by its place in the template: the files the list does not name are removed before the pair is moved.

Application template may contain:

  • *.tt.template - template files, that will be instantiated during application creation.
  • MANIFEST.yaml - template manifest (see details below).

MANIFEST.yaml

The template manifest MANIFEST.yaml has the following format:

description: Template description
vars:
    - prompt: User name
      name: user_name
      default: admin
      re: ^\w+$

    - prompt: Retry count
      default: "3"
      name: retry_count
      type: integer
      min: 1
      max: 10
pre-hook: ./hooks/pre-gen.sh
post-hook: ./hooks/post-gen.sh
include:
- init.lua
- .templates/default/instances.yaml
- .templates/default/config.yaml
follow-up-message: Run "tt instance start" in {{.name}}.

Where:

  • description (string) - template description.
  • vars - template variables used for instantiation.
  • prompt - user prompt for variable value input.
  • name - variable name.
  • default - default value of the variable.
  • re - regular expression used for value validation. It matches a part of the value unless it is anchored with ^...$.
  • type - string (the default) or integer. A value of an integer variable is a decimal integer.
  • min, max - the bounds of an integer variable, both optional.
  • pre-hook (string) - executable to run before template instantiation.
  • post-hook (string) - executable to run after template instantiation.
  • include (list) - list of files to keep in application directory after create.
  • follow-up-message (string) - message printed after the application is created, with the variables instantiated in it.

There are pre-defined variables that can be used in template text: name - application name. It is set to --name CLI argument value.

Don't include the .rocks directory in your application template. To specify application dependencies, declare them in [dependencies] of app.manifest.toml (see Packages).

Variables

tt create asks for the value of every variable of vars, offering its default. --var name=value, which can be repeated, and --vars-file FILE give values in advance, and -s (--non-interactive) takes the defaults of the rest without asking. -f overwrites an application directory that exists.

A value is checked against the type, min, max and re of its variable before anything is rendered. A value given in advance that does not pass fails the command with the reason, such as invalid format of num_replicas variable: "3abc" is not an integer >= 2; a value typed in is asked for again.

The follow-up message of the template is printed after the application is created, with -s as well.