Windows Installation

Document Overview

• Running the installer
  • Any relevant installation instructions are described here
  • The images that will ultimately be built/loaded are also described here
• Using Podman Desktop
• Managing DataWORQ
  • Using the DataWORQ Admin Tool
  • Using DataWORQ
• Frequently Asked Questions

Running the Installer

The installer is mostly non-interactive; all default installation choices can be kept, and moving through the installer mostly consists of hitting the “Next” on each installer screen. The complete installation process is as follows:

1. Accept the DataWORQ license agreement
2. Install WSL (Windows Subsystem for Linux)
   • Podman can only be installed on Linux, not Windows. WSL allows us to run a performant Linux virtual machine on a Windows machine
   • For more info about what WSL is: WSL
3. Restart your machine
   • NB: the installation will automatically continue after restart
4. Choose “Complete” install to install with default settings selected
5. Accept all the UAC prompts
   • NB: the installer may take a while to download the required files

Using Podman Desktop

Podman Desktop is a tool that makes interacting with Podman and containers easier.

The primary purpose of Podman Desktop will be to start a handful of containers that DataWORQ depends on. Not all container management will be done using Podman Desktop, but it will be the starting point.

For more general information about Podman Desktop, see here: https://podman-desktop.io/docs/intro

Starting Containers

Podman Desktop can be used to start containers that are presently stopped:

After the installation successfully completes, you should be able to navigate to Podman Desktop and click on the “Containers” tab (represented by a picture of a cube in the below image). The containers in this image are all started, represented by their Status icon (the green cube).

The following container is the one that should be manually managed in Podman Desktop:

• admintool

If this container is stopped (represented by the transparent cube status icon), it can be manually started by clicking the “Start Container” button (the play icon) to the right of the container name.

To stop running containers, hit the “Stop Container” button to the right of the running container’s name.

Interacting with Containers and Accessing DataWORQ

After these containers have been started, all further interaction with DataWORQ should be done via a web browser.

By default, the following entities are exposed on these ports, and can be accessed by entering the following addresses into a browser:

• DataWORQ Admin Tool:
  • http://localhost:8080/AdminTool/index.xhtml
• NB: This URL is case-sensitive

Container Image Overview

This section includes optional, supplementary info, and can be skipped if desired.

The following are some of the containers/container images you might see in Podman Desktop. Deep knowledge of these containers' contents isn’t necessary to use DataWORQ, but are included here as supplementary information.

Managing DataWORQ via the Admin Tool

DataWORQ is managed by using the Admin Tool. There are three tabs visible when using the Admin Tool:

• Application Settings
• Raw Application Settings
• Container Management

Application Settings

The DataWORQ web application is configured through a list of properties set up in the Admin Tool.

These settings include:

• The port number on which DataWORQ is exposed (the default is 9600)
• The authentication mode that DataWORQ is set to use (the default is basic username/password auth)
• The ability to enable the following, all of which can be used directly inside of DataWORQ:
  • R
  • Python
  • GLPK
  • Command Line support

On accessing these settings the first time, after any necessary updates are made they must be saved by hitting the "Save" button.

Raw Application Settings

Additional, less often updated configuration settings can be managed here.

Container Management

The state of the DataWORQ specific containers can be managed in this tab. The actions made available here include:

• Checking the containers' status
• Starting containers
  • Pressing this button will either start the stopped DataWORQ specific containers, or if already started, restart them
• Export Data
  • The current state of the DataWORQ containers can be exported into a .zip file
• Import Data
  • The state of the running DataWORQ containers can be updated from a .zip file
  • This action also restarts the DataWORQ containers

Using DataWORQ

Navigate to http://localhost:9600/DataWORQ to access DataWORQ via a browser

NB: This URL is case-sensitive

When logging in the first time, whatever username/password are entered become the default admin account (for basic authentication)

Accessing DataWORQ Externally

DataWORQ running in the Podman machine is accessible from the Windows host itself via "localhost". However, because of how WSL works, DataWORQ isn't accessible by default when using the PC domain name or IP address.

To access DataWORQ from another machine, we first need to setup a port proxy for the port we want to access.

NB: the forward needs to be towards the WSL2 IP address, which is dynamic and changes on each reboot. So every time a Windows machine is started, the Windows proxy need to be reconfigured.

The following commands can be run in a command prompt:

wsl -d podman-machine-default -e sh -c "ip addr show eth0 | grep 'inet\b' | awk '{print $2}' | cut -d/ -f1" 

• This command will return an IP address that that virtual machine is using

netsh interface portproxy add v4tov4 listenport=9600 listenaddress=0.0.0.0 connectport=9600 connectaddress=XXX.XXX.XX.XX

• This command will actually do the port forwarding. The “XXX.XXX.XX.XX” should be replaced by the IP address from the first command

The following batch script can also be used to run the above commands:

DataWORQ-Port-Forward.bat