Installation
Contents
Supported operating systems
The following operating systems are supported out-of-the-box:
Recommended for production setups
Tested and fully compatible
Alpine Linux 13.3+ (requires Glibc compatibility layer)
Docker images
Kubernetes
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).
To specify an alternative Python path during the installation, use PYTHON environment variable:
sudo -s
curl https://pub.bma.ai/eva4/install | env PYTHON=/path/to/python sh /dev/stdin -a --hmi
Additional special options for Python venv (must be also specified in environment variables):
PYTHON_USE_SYSTEM_PIP=1 - use system pip by default
PYTHON_SYSTEM_SITE_PACKAGES=1 - use system site-packages by default
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.
Overriding keys/passwords
If HMI service is selected to be installed, the installer automatically sets up Default ACL service and Local user/key authentication service services as well.
The passwords / API keys are generated automatically. To override, use the following environment variables:
DEFAULTKEY - the default host API key
ADMINKEY - the admin API key
ADMINPASSWD - the admin password
OPKEY - the operator API key
OPPASSWD - the operator password
Example:
sudo -s
curl https://pub.bma.ai/eva4/install | env DEFAULTKEY=secret sh /dev/stdin -a --hmi
Advanced options
The following environment variables override the default installation options:
EVA_REPOSITORY - EVA ICS repository URL (default: https://pub.bma.ai/eva4)
EVA_VERSION and EVA_BUILD - EVA ICS version and build to install (both must be set, default: latest)
Uninstalling
To uninstall EVA ICS, execute the following:
systemctl stop eva4
rm -rf /opt/eva4
rm -f /etc/systemd/system/eva4.service
systemctl daemon-reload
On Alpine Linux, stop EVA ICS using:
rc-service eva4 stop
# or
/etc/init.d/eva4 stop
Note
If installation has been failed at some point, it is recommended to execute the above commands to clean up the system before the next installation attempt.
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/venvmgr edit
or by editing “eva/config/python-venv” registry key in eva-shell or in other tools.
After configuring, rebuild the virtual environment:
/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
See also: Updating EVA ICS to 4.1.0.
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
Offline nodes
Nodes without the Internet, restricted Internet access or extremely slow connection can be updated using the following procedure:
Determine the binary architecture used on the target system:
eva -J version|jq -r .arch
Download the desired EVA ICS tarball from https://pub.bma.ai/eva4/, make sure the architecture matches the one used on the target system, place the file to into /opt/eva4/ directory.
Download the update.sh script, located in the same directory as the tarball on pub.bma.ai, place it into /opt/eva4/ directory as well. If updating to an older build, download update-<BUILD_NUMBER>.sh from nightly folder.
Execute:
cd /opt/eva4
sudo bash update.sh
After the update is finished, delete the downloaded tarball and the update.sh script.
The offline update does not work properly if Python venv has been setup on the node. Starting from 4.1.0 build 2025092301 it is also possible to use EVA_UPDATE_SKIP_VENV=1 environment variable:
cd /opt/eva4
sudo EVA_UPDATE_SKIP_VENV=1 bash update.sh
In this case venv is not updated automatically but it is highly recommended to do manual update of the following packages:
evaics (use the version from install/mods.list)
eva-shell (use the latest version available)
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).
Installing/updating on Debian 10
Despite Debian 10 is not officially supported, EVA ICS can be installed on it. If eva-shell or Python services are required, install Python 3.8 back-port:
sudo -s
apt -y install curl lsb-release
curl https://people.debian.org/~paravoid/python-all/unofficial-python-all.asc | \
tee /etc/apt/trusted.gpg.d/unofficial-python-all.asc
echo "deb http://people.debian.org/~paravoid/python-all $(lsb_release -sc) main" | \
tee /etc/apt/sources.list.d/python-all.list
apt update
apt -y install python3.8
The install EVA ICS as the following:
curl https://pub.bma.ai/eva4/install | env PYTHON=python3.8 sh /dev/stdin -a --hmi
If updating Python venv on an existing system, execute:
/opt/eva4/sbin/venvmgr edit
# or
/opt/eva4/sbin/eva-registry-cli edit eva/config/python-venv
Set “python” field to “python3.8” then execute:
/opt/eva4/sbin/venvmgr build -S
Note
Python 3.8 backport to Debian 10 is not officially supported by Debian.