Installation Guide

This tutorial provides step-by-step instructions for deploying the WEVA environment on a host machine.

Prerequisites

Ensure the following conditions are met before starting the installation:

1. Hardware: Host machine meets System Requirements.
2. Software: Docker Desktop or Docker Engine is installed and running.
3. Network: Administrative access to the host machine's terminal (PowerShell or Bash).
4. WDX Runtime: Ensure you have WDX Docker image. If you dont have it, get it from Here

---

1. Deploy WDX Runtime (PLC Visu)

The WDX runtime is the primary communication bridge between WEVA and other controllers.

Load the Image

Import the provided WDX Docker image into your local repository.

• Open the folder where WDX was downloaded.
• Open a terminal in that folder location.
• Run the following command:

Windows, Linux and Mac

# In PowerShell or Terminal
docker load -i /{path-to-plcvisu}/plcvisu.tar

Start the Container

Run the container using the following command. This persistent mapping ensures logs and configurations are stored on the host.

Windows

docker run -d `
  -p 7081:80 `
  -p 7481:443 `
  --name wdx-runtime `
  --restart unless-stopped `
  -v "$env:USERPROFILE\Documents\WAGO\data:/opt/elrest/edesign/wdx/data" `
  -v "$env:USERPROFILE\Documents\WAGO\config:/opt/elrest/edesign/wdx/config" `
  -v "$env:USERPROFILE\Documents\WAGO\js-storage:/opt/elrest/edesign/wdx/storage" `
  plcvisu:{version-number}-X86_64-alpine

Linux and Mac

docker run -d \
  -p 7081:80 \
  -p 7481:443 \ 
  --name wdx-runtime \
  --restart unless-stopped \
  -v "$HOME/Documents/WAGO/wdx-logs/data:/opt/elrest/edesign/wdx/data" \
  -v "$HOME/Documents/WAGO/wdx-logs/config:/opt/elrest/edesign/wdx/config" \
  -v "$HOME/Documents/WAGO/wdx-logs/js-storage:/opt/elrest/edesign/wdx/storage" \
  plcvisu:{version-number}-X86_64-alpine

WARNING:

• Ensure the volume paths (e.g., C:\WAGO\...) exist on the host before running the command.
• Commands may be different on Mac. Confirm before use.
• If the fields in the commands are changed, ensure to be consistent for the rest of the installation process.
• Make sure the version number of plcvisu shown on Docker matches the one in the command.
• The -p in the command is the port number (it is 7081:80 in this case) where 7081 is your computer port number and 80 is the container port number.

Validate Start

To confirm if WDX was installed successfully, open a browser and access the port specified in the command ran in the previous section.

In the situation that the WDX web page is inaccessible, restarting WDX is required:

---

2. Deploy WEVA Application

Once the WDX runtime is verified, deploy the WEVA application stack.

Load WEVA Image

If you have the image in a .tar file:

Windows, Linux and Mac

docker load -i weva-app-image.tar

Configure Docker Compose

Create a directory for the deployment and place the docker-compose.yaml file inside it.

Note: If you dont have the docker-compose.yaml, create a new empty file named docker-compose.yaml in the folder you are in and paste the content below into the file 👇.

# docker-compose.yml
services:
  app:
    #if you have the .tar file, change the name to the 'name:tag' written in Docker
    image: ustaz/weva-app:1.0.8

    #name of the generated container
    container_name: weva

    #This is to ensure the container is always running
    restart: unless-stopped

    #DO NOT CHANGE THESE PARAMETERS!!
    ports:
      - "5170:5170"
    extra_hosts:
      - "host.docker.internal:host-gateway"
    environment:
      HTTP_SERVER_PORT: 5170
      
      # Data transfer frequency
      UPDATE_RATE: 3000

      DB_HOST: mysql
      DB_USER: root
      # Ideally, these should be changed!
      DB_PASSWORD: mypassword
      DB_NAME: wagopa
      WDX_SERVER_HOST: host.docker.internal
      WDX_SERVER_PORT: 7081
      # Note: If user accesses this from another PC on their network, 
      # they must change 'localhost' to the host machine's actual IP address.
      VITE_BACKEND_HOST: localhost
      VITE_WEBSOCKET_PORT: 3031
    depends_on:
      - mysql
    networks:
      - weva_net

  mysql:
    image: mysql:latest
    container_name: mysql-db
    restart: unless-stopped
    ports:
      - "3306:3306"
    environment:
    
    #It must be the same as the DB_PASSWORD parameter
      MYSQL_ROOT_PASSWORD: mypassword
    volumes:
      - mysql_data:/var/lib/mysql
      # This points to the init.sql file inside the folder.
      #Ensure its in the same folder with this file!!
      - ./init.sql:/docker-entrypoint-initdb.d/init.sql:ro
    networks:
      - weva_net

networks:
  weva_net:
    driver: bridge

volumes:
  mysql_data:

Note: Ensure the init.sql file is located at the same directory as the docker-compose.yaml file. This is to setup the mysql container properly.

Start the Stack

Navigate to the directory and execute:

Windows, Linux and Mac

docker compose up -d

By doing this, Docker would create the running containers and start running the processes without any errors.

GIF: Recording showing the 'docker compose up' command and successful container startup.

---

3. Verification

1. Container Status: Run docker ps to ensure all containers (weva-backend, weva-db, wdx-runtime) are in the Up state.
2. Web Access: Open a browser on the host and navigate to http://localhost:5170.
3. Registration: Create your profile in the Register Page as there is not default profile that comes with the software.

---

NOTE: Refer to the Troubleshooting Page if any errors were encountered!!