Install an application for a user¶
The user scope runs an application without root: a test stand, a
developer's machine, a host where tt is not installed system-wide. Its root
is ~/.local/share/tarantool on Linux, or TT_USER_ROOT. The same steps
work for the system scope with --scope system, run as root.
You need the archive of the application, made by tt package pack (see
Your first package).
Install¶
$ tt package install --scope user kv-api-1.0.0-linux-amd64.tt
installed kv-api 1.0.0 into user scope
$ tt package list --scope user
NAME ACTIVE VERSIONS DESCRIPTION
kv-api 1.0.0 1.0.0
The archive becomes the version versions/kv-api/kv-api_1.0.0/ of the
scope, and apps/kv-api points to it. The Tarantool and the tt the archive
bundles go into versions/ of the scope; no network is needed.
Run¶
No project is needed: run the commands from any directory.
$ tt instance start kv-api:* --scope user
$ tt instance status kv-api:* --scope user
$ tt instance logs kv-api:kv-1 --scope user --follow
$ tt connect kv-api:kv-1 --scope user
The instances run from the default template of the version, and keep their
data in var/lib/kv-api/ of the scope.
tt instance status --scope user with no target shows every instance of
every application installed in the scope; an application whose description
cannot be read is warned of and left out.
Describe this host¶
The templates of a version are part of the package; an upgrade replaces
them. To set what runs on this host - which instances, which ports, which
passwords - write the pair of the host into etc/<app>/ of the scope. It
wins over the templates:
$ mkdir -p ~/.local/share/tarantool/etc/kv-api
$ cd ~/.local/share/tarantool/etc/kv-api
$ $EDITOR config.yaml # the cluster config of this host
$ $EDITOR instances.yaml # what runs here, such as: kv-1: {restart: on-failure}
$ tt instance start kv-api:* --scope user
The pair of the host needs instances.yaml: it says which instances of the
cluster run on this host. See Instances.
Upgrade¶
$ tt package install --scope user --upgrade kv-api-1.1.0-linux-amd64.tt
installed kv-api 1.1.0 into user scope
⚠ 2 instances of kv-api run 1.0.0: kv-1, kv-2
⚠ to move them to 1.1.0: tt instance restart kv-api:kv-1,kv-api:kv-2 --scope user
$ tt package list --scope user
NAME ACTIVE VERSIONS DESCRIPTION
kv-api 1.1.0 1.0.0, 1.1.0
$ tt instance restart kv-api:* --scope user --yes
Every install makes the version it installs active at once, newer or older
than the active one: a plain tt package install of a newer archive is an
upgrade already. --upgrade only adds a check: it installs a version newer
than every installed one, and does nothing otherwise.
A running instance keeps running the version it started from, also when its
watchdog restarts it after a crash; tt instance restart moves it to the
active one. install names the instances that do not run the version it
installed, and tt instance status --details shows the version every
running instance runs:
$ tt instance status kv-api:* --scope user --details
Version of kv-api:kv-1: 1.0.0, restart pending: 1.1.0 is active
...
In -o json the same is the version and restart_pending of an instance.
Roll back¶
The earlier versions stay installed next to the active one.
tt package switch makes one of them active again, with no archive and with
the instances running:
$ tt package switch kv-api 1.0.0 --scope user
switched kv-api from 1.1.0 to 1.0.0 in user scope
⚠ 2 instances of kv-api run 1.1.0: kv-1, kv-2
⚠ to move them to 1.0.0: tt instance restart kv-api:kv-1,kv-api:kv-2 --scope user
$ tt instance restart kv-api:* --scope user --yes
As after an upgrade, the running instances stay on the version they started
from until tt instance restart. apps/kv-api is replaced in one rename, so
an instance that starts during the switch gets one version or the other.
Without a version, tt package switch kv-api --scope user offers the
installed versions to choose from on a terminal; off a terminal it lists
them, the active one marked with *, and fails. Switching to the active
version does nothing. A version that is not installed is refused, and so is
one whose bundled Tarantool has been removed from the scope with
tt binary uninstall: the error names the tt binary install command that
brings it back. The project scope holds one version of every package, so
there tt package switch is refused: reinstall the version wanted with
tt package install --force.
Forward again is a switch as well, to the newer version:
tt package switch kv-api 1.1.0 --scope user.
Uninstall¶
$ tt instance stop kv-api:* --scope user --yes
$ tt package uninstall kv-api --scope user --yes
removed kv-api from user scope: versions 1.0.0, 1.1.0
uninstall refuses while an instance runs. It removes every version and the
apps/ link, and keeps the data in var/, the pair of the host in
etc/kv-api/, and the runtimes in versions/, which other applications may
use.