Installation#

Visionect provides Software Suite packages in multiple variations, based on your specific requirements. You can deploy the Suite either as a Virtual Machine (with tools for demo purposes) or a Docker image.

Before installing or upgrading the Software Suite, we suggest you consult our extensive Release notes

Default settings#

  1. Access to the Visionect Software Suite:

  • Port: 8081 (i.e.: http://your_server_ip:8081)

  • User: admin

  • Password: The password is set upon the first login to the server

Installation#

The Visionect Software Suite is a container/Docker-first software, which means that it is run in a container by default. Native packages are not available, with Visionect internally running all servers with Docker.

You will need to install Docker, which is supported on most modern operating systems and natively integrated into the latest Microsoft Windows Server 2016. More information regarding Docker installation can be found at https://docs.docker.com/engine/installation/

The containers are available on Docker Hub and include installation instructions.

Docker Hub repositories:

Docker containers are currently the only way to get the Visionect Software Suite running on embedded boards such as Raspberry Pi 2 and similar. For more information on embedded check Embedded Boards (Raspberry Pi 2 and others).

Quick start#

Docker Compose

Using the Docker Compose is the prefered option. Install the Visionect Software Suite by:

  • Verify that Docker Compose is installed.

  • Download docker-compose.yml from the link provided in the onboarding email you received when your trial license started.

  • Run: docker-compose up -d

Note

In order to display pages using self-signed SSL certificates, the Docker container should expose the directory /usr/local/share/ca-certificates as a volume. This directory can contain custom CA certificates that are applied when recreating the VSS container.

Note

The VSS_LICENSE_ID environmental variable must be set in order for the VSS to function. Without a proper value for the license, the devices will not be able to operate. The value for the env. variable is provided by Visionect upon purchase of the Essential license.

Docker run (alternative)

Alternatively, a series of docker commands can be executed:

# run redis (a requirement for Visionect Software suite version 5.2.x)
docker run --name some-redis -d redis -p6379:6379
# create postgres container
docker run -d --restart=always -e POSTGRES_PASSWORD=visionect -e POSTGRES_USER=visionect -e POSTGRES_DB=koala --name vserver_postgres postgres
# create data container  named 'vdata' (persistent volumes for things like, log files, firmware packages and configuration files)
docker create --name vdata visionect/visionect-server-v3
# run docker container and replace MACHINE_IP_ADDRESS with the actual IP of the machine where redis is running
docker run --privileged --cap-add=MKNOD --cap-add SYS_ADMIN -v /dev/shm:/dev/shm --device /dev/fuse -d --restart=always -e VSS_LICENSE_ID={LICENSE_ID} -e REDIS_ADDRESS={MACHINE_IP_ADDRESS}:6379 -p 8081:8081 -p 11113:11113 --link vserver_postgres:db2_1 --volumes-from vdata --name vserver visionect/visionect-server-v3


To control resources in container use `shm-size <https://docs.docker.com/engine/reference/run/#runtime-constraints-on-resources>`_ option to set custom resource limitations.

Upgrade#

docker run

To upgrade existing Visionect Software Suite only remove current Visionect Software Suite docker container and run it again. If there is a newer version published it will automatically download the latest image. Vdata and postgres containers do not need to be upgraded.

# remove current Visionect Software Suite container
docker rm -f vserver
# pull newer image from repository
docker pull visionect/visionect-server-v3
# run it again
docker run --privileged --cap-add=MKNOD --cap-add SYS_ADMIN -v /dev/shm:/dev/shm --device /dev/fuse -d --restart=always -e VSS_LICENSE_ID={LICENSE_ID} -e REDIS_ADDRESS={MACHINE_IP_ADDRESS}:6379 -p 8081:8081 -p 11113:11113 --link vserver_postgres:db2_1 --volumes-from vdata --name vserver visionect/visionect-server-v3

Note

If not sure about the name of Visionect Software Suite container run docker ps command.

docker-compose

If using docker-compose.yml as an installation method, type:

docker-compose pull && docker-compose up -d

Installation on Ubuntu#

To run the Visionect Software Suite on your Ubuntu machine, the Docker must be installed. Read the: https://docs.docker.com/engine/installation/linux/ubuntu/

After the Docker is installed, type in the commands listed in the ‘Quick start’ section of your terminal window.

After all the commands have been executed, type in docker ps -a and check if your Visionect Software Suite and postgres DB are running. The command execution should look similar to the image below.

Installation on Windows#

Note

Docker for Windows requires 64-bit Windows 10 Pro and Microsoft Hyper-V. To install on older Windows systems please check https://docs.docker.com/toolbox/toolbox_install_windows/

To run Visionect Software Suite on your Windows machine, the Docker must be installed. The requirements and installations steps are available on the: https://docs.docker.com/docker-for-windows/

After Docker is installed and running, open PowerShell in administrator mode. Type in all the commands listed in the Quick Start section.

After all the commands are being executed, type in docker ps -a and check if your Visionect Software Suite and postgres DB are running. The command execution should look similar to the image below.

Installation on Mac#

To run the Visionect Software Suite on your Mac, the Docker must be installed. Read the: https://docs.docker.com/docker-for-mac/

After the Docker is installed, type in the commands listed in the ‘Quick start’ section of your terminal window.

After all the commands have been executed, type in docker ps -a and check if your Visionect Software Suite and postgres DB are running. The command execution should look similar to the image below.

Environmental Variables#

The following is a list of the environmental variables that can be passed when starting the docker container.

Database-related Environmental Settings

The database settings below are mandatory and should be set if you are using an external PostgreSQL server.

DB2_1_PORT_5432_TCP_ADDR

The TCP host address of the PostgreSQL server to use

DB2_1_PORT_5432_TCP_PORT

The TCP port of the PostgreSQL server

DB2_1_PORT_5432_TCP_USER

The PostgreSQL database owner username

DB2_1_PORT_5432_TCP_PASS

The PostgreSQL database owner password

DB2_1_PORT_5432_TCP_DB

The PostgreSQL database name to be used for this deployment

License-related Environmental Setting

The license settings are mandatory and should be set for the devices to work.

VSS_LICENSE_ID

The license ID provided by Visionect allows the operation of devices up to the number of purchased licenses.

Software Suite Configuration

The settings below are not mandatory, but should be used to set up a master/slave Software Suite configuration.

VISIONECT_SERVER_CONFIG

If set, the content should be a JSON-formatted configuration file that will be used on the first run to store the entire server configuration. Use this if you want to migrate an older config.json configuration to a new Visionect Software Suite 3.x setup.

VISIONECT_SERVER_DEPLOYMENT_KEY

If set, the value overrides any set deployment key in the configuration and uses it to identify the components of the deployment

VISIONECT_SERVER_MASTER_HOST

If set, the value is used as the master host if setting up a master/slave configuration.

VISIONECT_SERVER_ENGINE_HOST

If set, the value is the hostname of the engine if the engine is to be a part of a master/slave server configuration.

REDIS_ADDRESS

The IP address and port of the Redis service (default port is 6379)

REDIS_PASSWORD

The password for the Redis instance (leave if there is no password set)

WebKit Memory Profiles

The HTML renderer supports dynamic memory profiles, meaning that the fixed RSS limit that can be set from the management interface is ignored. Instead, RSS limits are applied based on the screen size. For example, 32” devices will by default need more RAM to work than devices with 6” devices and a global RSS limit can’t be used.

Fine-tuning the RSS limiter is achieved by enabling the RSS memory profiles and specifying the values.

WEBKIT_RSS_PROFILE_ENABLE

This must be se to true to enable the RSS memory profiles.

WEBKIT_RSS_PROFILE_PARAMS

This env. variable defines the profile parameters:

  • (ui_pix1, ui_rssMb1) and (ui_pix2, ui_rssMb2) are two points that we use to create linear interpolation model for UI process expected memory usage.

  • ui_pix[1 2] is display size in pixels, and ui_rssMb[1 2] is RSS memory usage in MiB.

  • ui_tolerance is a value that is added to an expected memory usage to get a threshold value. If RSS usage of UI process exceeds this threshold, UI process will be killed eventually. (0.5 means model + 50%)

  • wp_rssMb is an expected RSS memory usage in MiB for WebProcess.

  • wp_tolerance is a value that is added to an expected memory usage to get a threshold value.

If RSS usage of WP process exceeds this threshold, UI process will be killed eventually. (0.5 means model + 50%)

A good example of the memory profile settings is:

`` WEBKIT_RSS_PROFILE_ENABLE=true WEBKIT_RSS_PROFILE_PARAMS=ui_pix1=776192,ui_rssMb1=200,ui_pix2=1920000,ui_rssMb2=300,ui_tolerance=0,wp_rssMb=230,wp_tolerance=0 ``

Defaults:#

Management Interface:

  • Port:8081: (ie: http://your_server_ip:8081)

  • Username: admin

  • Password: admin123

The user ‘visionect’ is a sudoer, which means you can run privileged commands by running sudo {your command}

Logs are located in /var/log/vss/.

Getting the server IP from the console#

In some cases you will need to get the current server’s IP address manually from the console.

In some cases you will need to get the current Suite’s IP address manually from the console. Log into the Virtual Machine and type the ip addr command. The out of the command will display the current networking configuration. Find the eth0 adapter and search for a line inet - the quad in the form of aaa.bbb.ccc.ddd is your current IP. If you do not see the inet line, you might have issues with your network configuration. The possible causes are a restricted use of DHCP (check with your network administrator), issues with your router, or the fact that you did not bridge the virtual adapter with the right networking adapter (see image).

../_images/net-primer-ip-addr.png

An example output of IP addr command. The IP address of the virtual machine is highlighted

Embedded Boards (Raspberry Pi 2 and others)#

Docker container are the only way to deploy the Visionect Software Suite on ARMv7 based embedded boards such as Raspberry Pi 2 and Odroid U2/U3. You should be able to run the Visionect Software Suite on an embedded board if Docker is supported, as long as you download the ARM version of the Visionect Software Suite from the Docker Hub.

Installation

# run redis (a requirement for Visionect Software suite version 5.2.x)
docker run --name some-redis -d redis -p6379:6379
 # create postgres container
docker run -d --restart=always -e POSTGRES_PASSWORD=visionect -e POSTGRES_USER=visionect --name vserver_postgres zsoltm/postgresql-armhf:9.4
# export environment variables
export POSTGRES_PORT_5432_TCP_ADDR=$(docker inspect -f '{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}' vserver_postgres)
export POSTGRES_PORT_5432_TCP_PORT=5432
# create the server database
docker exec vserver_postgres sh -c 'exec psql -h "$POSTGRES_PORT_5432_TCP_ADDR" -p "$POSTGRES_PORT_5432_TCP_PORT" -U visionect -c "CREATE DATABASE koala WITH owner=visionect;"'
# create data container  named 'vdata' (persistent volumes for things like, log files, firmware packages and configuration files)
docker create --name vdata visionect/visionect-server-v3-armhf
# run docker container
docker run --privileged --cap-add=MKNOD --cap-add SYS_ADMIN --device /dev/fuse -d --restart=always -e VSS_LICENSE_ID={LICENSE_ID} -e REDIS_ADDRESS={MACHINE_IP_ADDRESS}:6379  -p 8081:8081 -p 11113:11113 --link vserver_postgres:db2_1 --volumes-from vdata --name vserver visionect/visionect-server-v3-armhf

Currently tested boards include:

Warning

Raspberry Pi 1 is an ARMv6 board and is not supported.

Installation

# run redis (a requirement for Visionect Software suite version 5.2.x)
docker run --name some-redis -d redis -p6379:6379
# create postgres container
docker run -d --restart=always -e POSTGRES_PASSWORD=visionect -e POSTGRES_USER=visionect --name vserver_postgres zsoltm/postgresql-armhf:9.4
# export environment variables
export POSTGRES_PORT_5432_TCP_ADDR=$(docker inspect -f '{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}' vserver_postgres)
export POSTGRES_PORT_5432_TCP_PORT=5432
# create the server database
docker exec vserver_postgres sh -c 'exec psql -h "$POSTGRES_PORT_5432_TCP_ADDR" -p "$POSTGRES_PORT_5432_TCP_PORT" -U visionect -c "CREATE DATABASE koala WITH owner=visionect;"'
# create data container  named 'vdata' (persistent volumes for things like, log files, firmware packages and configuration files)
docker create --name vdata visionect/visionect-server-v3-armhf
# run docker container
docker run --privileged --cap-add=MKNOD --cap-add SYS_ADMIN --device /dev/fuse -d --restart=always -e VSS_LICENSE_ID={LICENSE_ID} -e REDIS_ADDRESS={MACHINE_IP_ADDRESS}:6379 -p 8081:8081 -p 11113:11113 --link vserver_postgres:db2_1 --volumes-from vdata --name vserver visionect/visionect-server-v3-armhf

Other ARMv7 boards should also work. A couple of caveats:

  1. Performance on the embedded boards is limited. These are not high performance servers. IN certain applications this should not pose an issue: non-interactive applications should work just fine.

  2. The embedded boards are mostly bound by memory, and general Visionect Software Suite limitations still apply. If you want to run a couple of screens from a i.MX 6 you’ll need to change the rendering backend from HTML to HTTP and build your app differently - check Graphics Engine and rendering backends for more information.

  3. You’ll need to make sure that you run PostgreSQL if you plan on hosting the database on the embedded board.

Performance Example:#

i.MX 6 Sabre Lite development kit with 1 GB of memory:

  • HTML backend, interactive app. We run 3x 6” panels or 2x 9.7” panels. 1x 32” should also work.

  • HTTP backend. We run 5x 32” panels + 1x 6” as a remote control on the same system.