Installer Reference

This page lists every argument of the UTMStack v12 installer, the files and folders it creates, the names of the services it deploys, and how it divides memory between them.

Where the installer lives

You download the installer as a file named installer and run it once, as root, to install UTMStack.
During installation it copies itself to /usr/local/bin/utmstack_installer and creates the shorter name /usr/local/bin/utmstack for the same program. The update service uses this copy, and updates replace it with the installer of each new version.

After installation, use the installed copy:

sudo /usr/local/bin/utmstack_installer --help

Arguments

Argument	What it does
(none), `--install`, `-i`	Installs UTMStack. If the `UTMStackComponentsUpdater` service is running, it only restarts that service and stops.
`--uninstall`, `-u`	Uninstalls UTMStack. See Uninstall.
`--version`, `-v`	Prints the installed version and edition, for example `UTMStack version: v12.0.2, edition: community`.
`--help`, `-h`	Prints the list of arguments.
`--recalculate-memory`	Recalculates the memory limits of all services from the server's current memory, saves them, and redeploys the services.
`--apply-memory`	Applies the memory limits in `/utmstack/updates/memory-allocation.json` and redeploys the services.
`--apply-memory --dry-run`	Checks the memory limits in that file and prints them, without redeploying anything.
`--run`, `-r`	Used by the update service. Do not run it yourself.

Any other argument prints the help.

Files the installer creates

The installer creates /root/utmstack.yml, the data folder /utmstack, the installation log /var/log/utmstack-installer.log, the update service and its folder /utmstack/updates, and compose.yml next to the installer program (for updates this is /usr/local/bin/compose.yml). The complete list of folders and files, with what each holds, is in Server Services and Files Reference.

Installation steps and lock files

The installer records each completed step as a file in /utmstack/locks and skips that step when it runs again, for example after a failed installation or during an update. Do not delete these files: a missing lock makes the step run again at the next update, for example the certificate step creates a new self-signed certificate over yours.

Step	Lock file
Checking system requirements	`202501131200.lock`
Generating certificates	`1.lock`
Preparing the system	`2.lock`
Preparing the kernel	`202402081552.lock`
Configuring VLAN	`202402081553.lock`
Configuring Docker	`3.lock`
Initializing Swarm	`4.lock`
Installing administration tools (Cockpit)	`5.lock`
Initializing the UTMStack and AgentManager databases	`6.lock`
Generating the Base URL	`9.lock`

These steps run every time, at installation and at every update: generating the stack configuration (including the memory check on a first run), downloading the images and deploying the services, writing the nginx settings and restarting nginx, waiting for the backend, and cleaning up unused Docker images.

Contents of /root/utmstack.yml

Key	Meaning
`main_server`	The server's main IP address: the address it uses to reach the internet. Detected at each run.
`branch`	The release channel. Leave it unchanged.
`password`	Generated password (16 characters). It is the PostgreSQL, ClickHouse and Valkey password and the first password of the `admin` user.
`data_dir`	Data folder. Default `/utmstack`.
`server_type`	Installation type. Default `aio` (all in one).
`server_name`	The server's host name, read at each run.
`internal_key`	Generated key (32 characters) that UTMStack services use to call each other.
`shared_key`	Generated key (32 characters) that nginx on the host adds to every request it forwards to the web container.
`updates_folder`	Folder of the update service. Default `/utmstack/updates`.
`mapping_name`	Optional. Not written unless set. When set, it is sent to the UTMStack update server at registration.

This file contains the database password and the internal keys. Keep it readable by root only, keep a secure copy, and never share it.

Docker services

The installer deploys one Docker Swarm stack named utmstack with 10 services: utmstack_frontend, utmstack_backend, utmstack_agentmanager, utmstack_log-input, utmstack_nats, utmstack_event-processor-worker, utmstack_event-processor-manager, utmstack_clickhouse, utmstack_postgres and utmstack_valkey. Use these names with docker service logs and docker service ps. What each service does is described in Server Services and Files Reference.

Do not change the services with docker service update options such as --env-add or --limit-memory, and do not edit compose.yml. The installer redeploys the stack from its own definition at every update and with --apply-memory or --recalculate-memory, which undoes such changes. Use the memory options below to change memory limits.

Memory limits

The installer gives each service a memory limit. It takes the server's total memory, keeps 1,000 MB for the operating system, gives every service its minimum and shares the rest by priority. Services with priority 1 get the largest share.

Service	Priority	Minimum (MB)	Maximum (MB)
`event-processor`	1	5,120	61,440
`clickhouse`	1	5,120	61,440
`log-input`	2	256	1,024
`postgres`	2	500	2,048
`nats`	3	256	2,048
`valkey`	3	128	1,024
`backend`	3	700	2,048
`agentmanager`	3	200	1,024
`frontend`	3	80	1,024

The minimums add up to 12,360 MB. With the 1,000 MB kept for the system, the installer needs at least 13,360 MB of memory. The event-processor value is the limit of each of the two event processor services (worker and manager).

The result is saved in /utmstack/updates/memory-allocation.json and reused by every update, so manual changes survive updates. For the limits the installer calculates on 16, 32, 64 and 128 GB servers, see Sizing and Capacity Planning.

Change the memory limits by hand

Edit /utmstack/updates/memory-allocation.json. Each service has an entry like this; change only AssignedMemory (in MB):

"backend": {
    "Name": "backend",
    "Priority": 3,
    "AssignedMemory": 2048,
    "MinMemory": 700,
    "MaxMemory": 2048
}

Check the file without changing anything:
```
sudo /usr/local/bin/utmstack_installer --apply-memory --dry-run
```
The installer refuses the file if a service is missing, if a value is below the service's minimum or above its maximum, or if the total is more than the server's memory minus 1,000 MB.
Apply it. The services are redeployed, which takes a while:
```
sudo /usr/local/bin/utmstack_installer --apply-memory
```

After adding or removing memory

Run:

sudo /usr/local/bin/utmstack_installer --recalculate-memory

This calculates new limits for the current memory, overwrites memory-allocation.json (manual changes in it are lost) and redeploys the services.