============ 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 :doc:`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 .. _native-packages: .. _vss_installation: 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: * `Visionect Software Suite for x86 hardware `_ * `Visionect Software Suite for ARM embedded boards needs the "-arm" tag in the end `_ 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 :ref:`embedded-boards`. .. _quick_start: 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: .. code-block:: sh # 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 `_ option to set custom resource limitations. .. _upgrade: 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. .. code-block:: sh # 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: .. code-block:: sh 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). .. figure:: images/net-primer-ip-addr.png :align: center *An example output of IP addr command. The IP address of the virtual machine is highlighted* .. _embedded-boards: 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** .. code-block:: sh # 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: * Raspberry Pi 2 (https://www.raspberrypi.org/products/raspberry-pi-2-model-b/) * Raspberry Pi 3 (https://www.raspberrypi.org/products/raspberry-pi-3-model-b/) * Odroid U2 and U3 (http://www.hardkernel.com/main/products/prdt_info.php?g_code=G138745696275) * Odroid C1 (http://www.hardkernel.com/main/products/prdt_info.php?g_code=G141578608433) * Freescale i.MX 6 Sabre Lite (http://boundarydevices.com/product/sabre-lite-imx6-sbc/) .. warning:: Raspberry Pi 1 is an ARMv6 board and is not supported. **Installation** .. code-block:: sh # 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 :ref:`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.