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. Installation Files: Ensure all the installation files are gotten from HERE

---

1. Deploy WDX Runtime (PLC Visu)

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

Load the Image

Import the provided WDX Docker image into your local repository.

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" `
  wdx-runtime:4.0.1.107-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" \
  wdx-runtime:4.0.1.107-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.

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.

# 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.5

    #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:

Start the Stack

Navigate to the directory and execute:

Windows, Linux and Mac

docker compose up -d

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. Login: Use the default administrator credentials provided in your license documentation.

---

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