Installation

Supported operating systems

The following operating systems are supported out-of-the-box:

Tested and fully compatible

By default, an universal (static-linked) EVA ICS distribution package is installed. See Native packages for more info.

Preparing the system

The EVA ICS installer prepares the system automatically, installing required packages. The only necessary pre-installed packages is “curl” to download and start the installation.

Installing

Basic install

For a single node, which is going to host a HMI application, type:

sudo -s # the installer script requires root privileges
curl https://pub.bma.ai/eva4/install | sh /dev/stdin -a --hmi

If this is a secondary node and no web services / HTTP API are required, omit the “–hmi” argument.

Note

As the installer script always installs at least the minimal list of required system packages, it must be executed under root.

The installer automatically prepares the system, installs the latest EVA ICS distribution to /opt/eva4 (default) folder and sets up Python virtual environment in /opt/eva4/venv (for mode >= 1).

Installer arguments

By adding “-h” or “–help” argument, the full list of the installer arguments can be obtained. Let us review the primary ones:

  • --hmi automatically setups authentication and web HMI services.

  • --mode prepares the system, installs additional packages:

    • 0 installs the minimal list of required packages

    • 1 installs Python and eva-shell

    • 2 all of the above, plus C and C++ compilers, plus development headers

    • 3 all of the above, plus Rust compiler and additional development

      headers

The compilers and the development headers can be used to add custom Python modules into venv.

  • --prepare-only allows to install additional compilers / headers, without installing EVA ICS. Can be executed after the installation at any time.

Post-install configuration

Startup and watchdog options can be configured by editing configuration files in /opt/eva4/etc folder (create them from provided examples if missing).

Additional configuration can be performed by editing Registry database keys.

Read more in configuring documentation section.

Startup

If the automatic startup has been set up, EVA ICS node is started automatically either by Systemd or by OpenRC (Alpine). To start/stop the node server manually, use either “/opt/eva4/sbin/eva-control” script or eva-shell.

Configuring/rebuilding Python venv

An optional Python virtual environment can be configured using the command:

/opt/eva4/sbin/eva-edit-python-venv

or by editing “eva/config/python-venv” registry key in eva-shell or in other tools.

/opt/eva4/sbin/venvmgr build

To rebuild the virtual environment from scratch, completely delete /opt/eva4/venv folder or call the above command with -S argument.

Note

Operating system upgrade to a new version usually requires rebuilding venv from scratch after the upgrade process is finished.

Updating

Local nodes

To update a local node, use the command:

eva update
# or
/opt/eva4/bin/eva-cloud-manager node update

Remote nodes

If any remote nodes are connected with replication services and configured as managed (admin key is set), they can be updated using cloud-update feature:

eva cloud update
# or
/opt/eva4/bin/eva-cloud-manager cloud update

After being started, the cloud-update firstly gathers facts about the available nodes and after offers the update plan, which must be additionally confirmed.

Remote nodes are always updated to the same version, which the management node has got.

Mission-critical systems

The following update strategy is recommended for mission-critical systems:

  • Backup the system (/opt/eva4 directory) before updating

  • Apply update on a test system before updating the critical one

  • If the test system works with no issues after update has been applied, execute the following eva-shell command:

eva update -i

The above outputs the latest available EVA ICS build/version plus provides a command how to update other nodes to the same build the test system has got.

  • Execute the provided command on the target mission-critical system as-is:

eva update --target-version VERSION:BUILD

Running under a restricted user

By default, the EVA ICS main process is started as root, while secondary services drop their privileges to system restricted users.

Sometimes the whole platform must run under a restricted user. To make it work, perform the following:

  • Install EVA ICS v4 in the regular way. The commands below require eva-shell to be installed, so run the installer with -a option or install eva-shell later manually.

  • Execute the following command to remove “props/user” option in the existing deployed services:

eva svc export \*|grep -v '^    user: '|eva svc deploy

  • Stop the server completely

systemctl stop eva4
# if not using systemd to start/stop EVA ICS automatically
eva server stop

  • Create a desired user, change ownership of /opt/eva4 directory, where useracc is user’s login:

chown -R useracc /opt/eva4

  • If using systemd, create a systemd service configuration override:

systemctl edit eva4

and put the following to override the user:

[Service]
User=useracc

  • If logrotate is automatically configured during the install, edit /etc/logrotate.d/eva4 and replace in the default “create 640 root adm” line root to useracc.

  • Start the server back

systemctl start eva4
# if not using systemd to start/stop EVA ICS automatically
su - useracc -c "/opt/eva4/bin/eva server start"

Note

When deploying new services on EVA ICS system, which runs under a restricted user, avoid using “user” field in the service primary params section (remove it if using the default templates).