Windows Relayer-UI

A Relayer install begins with the XNS Console

• When you first access the Console, you are prompted for a login. New users should click the Register link at the bottom which creates an account in our system. You need to confirm using email and then log in. This is your Single Sign-On (SSO) with XNS and is required for all activities on our Cloud. You can have multiple logins but your main login will be the account billed as your Primary Account. If you have multiple users, this account is analogous to a Root account
• Once you are logged into the Console, the first task is to enter valid Payment type/method. Today, only credit cards are accepted, but soon we’ll add the ability to pay on terms for qualified organizations

Prerequisites

Hardware and networking guidance is covered in Relayer Setup Introduction

Relayer software deploys with Docker. It is highly recommended to install Docker following the Windows specific Docker Desktop guide. Docker Desktop should be started with “Run as administrator” to function properly, operating in Linux containers mode.

To verify docker engine is installed and running, open Windows PowerShell and run the below command. Commands are indicated by the prompt $.

$ docker ps

CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES

Docker compose is also needed: this should be included with Docker Desktop, but verify.

$ docker-compose version

docker-compose version 2.15.1

If the output doesn’t resemble the expected, please review the Docker docs and go over the install guide carefully.

Installing Relayer UI

Open File Explorer and create a directory where the Relayer program will store its files. Consider something like C:\XNS-Relayer. You can also create a separate cache folder on a different disk.

Within this folder, two files need to be created: the first is docker-compose.yml and the second is .env. Right-click in the folder, and create new Text Documents with these names. Be sure to remove any trailing .txt from the filename.

Right click docker-compose.yml and Open With -> Notepad. Copy-paste the below text in to the text editor.

version: "3.4"
services:
  xns:
    container_name: xns-relayer
    image: scprime/xns-relayer:stable
    restart: unless-stopped
    volumes:
      - C:\XNS-Relayer:/relayer
      #- D:\relayer-cache:/relayer/meta
    ports:
      - ${UI_PORT}:8888
      - ${MINIO_PORT}:9000
    env_file:
      - .env

The line(s) under volumes: will need to be customized to your filesystem. If you created C:\XNS-Relayer earlier, then this sample is ready for use. The second line, optional, is commented out by the #. This symbol can be deleted and point to a separate cache folder if desired (here demonstrated by D:\relayer-cache). Do not modify anything past the colon character (:) in the middle of the line. Save and exit. This file is highly sensitive in structure, and any stray/missing spaces can cause issues.

Next, open .env, also copy-pasting the below in to the text editor.

UI_PORT=8888
MINIO_PORT=9000

The .env file serves to host environment options. Again, save and exit.

Container Start

With docker-compose.yml and .env created (and if desired, customized), the docker container is ready to be created.
Within the folder containing these two files, Shift+Right-click empty space and Open PowerShell window here. Then run:

$ docker-compose up -d --force-recreate

This will pull the image layers and create the container. It should then become visible with docker ps
Within a few moments, the web-UI will become accessible on the machine at port 8888. Visit it at http://<local IP address>:8888. If the UI can’t be reached, confirm the local IP of the machine, and check firewall settings to see if traffic is being filtered. It is also possible something in the docker-compose.yml file is creating issues.

This tab may look like the above, or it may ask you to sign in to your console account before taking you to the dashboard.

Configuration

Before starting up the system, take a look through the Configuration tab.

General Configuration

• Maximum Cache Size
  • This should be at least as large as the largest dataset you intend to upload in a short period. You will receive warnings if this cache size exceeds the space available.
• Endpoint Access Key/Secret Key
  • These values will be changed in a future step. These keys are used by MinIO to authenticate S3 endpoint access.
• Certificate
  • By default, MinIO will run in https mode with a self-signed certificate. Many apps require an https endpoint, but a self-signed certificate may not be recognized as valid.
  • If an authentic certificate is available, change to “Custom SSL Certificate” and upload the SSL Certificate and Private Key underneath. These files may be a .crt, .cer, or .pem filetype. A Certificate Authority (CA) can also be uploaded, but is not required.

Advanced Configuration:

• Database
  • By default, a database local to the docker container will be created and used. This volume will be stored on the main OS drive.
  • A database external to the container can be used by flipping the “Use Local Database” slider, and entering the information for this external database in the fields that open.
  • The database stores essential metadata, and switching between databases can have undesirable consequences. Take care making changes, and have backups.
• HostIO
  • The Relayer Wizard can guide settings sensible for the capabilities of a machine, but they can be further tweaked in the UI.
  • If a parameter is set in the .env file, the UI will not be able to override it. This is reflected by the field becoming greyed out.

Click Save Changes in the upper right. All of these settings can be changed later, but the Relayer will require a restart to take effect.

Launching

From the Dashboard click Startup, and the subsystem components should become active.

In the first period after starting, HostIO will be scanning through providers and assembling the information it needs to begin uploading data from the cache to the providers (draining). While this is building, the message HostIO is currently calculating providers will be displayed. This process will take less than 5 minutes.

Restart the Container

You will now need to restart the container. The reason for this is you will notice under the configuration menu on the Relayer dashboard that your Endpoint Access Key and Endpoint Secret key are the default ‘123’ and ‘12345678’ respectively. 

The command to stop the container must be run from the folder containing docker-compose.yml and .env

docker-compose stop

The command to start the container must also be run from the folder containing docker-compose.yml and .env

docker-compose up -d

With the container running again, under the configuration menu you should see the Endpoint Access Key and Endpoint Secret Key are now random numbers and letters.

Disable Default User

The last step before your relayer is ready for use is the disable the default user under the IAM tab on the dashboard.

Click on the blue box with the ‘X’ to disable the user.

With the default user disabled, you can now create new users and use the relayer. To learn more about IAM and adding new users, see this document.

Operation

Click the Endpoint URL to access the MinIO interface. Log in using the random Access and Secret keys set during the previous step or with a user created via the IAM menu. You can also visit the File Manager tab directly to create and use buckets.

Note that before the S3 endpoint will be usable directly by application software, a bucket will need to be created. To learn more about the various S3 applications that will work with XNS, visit this page.

The main dashboard will display some information on the status of the Relayer; Cache status is particularly of note:

• Total Cache Size: This is the maximum amount of hard drive space allocated for the cache. It is normal for the used space to reach up to this limit, as the system retains files in the cache to facilitate quicker access instead of retrieving them from the network anew each time. The cache is designed to always operate at or near its maximum capacity to ensure efficiency.
• Used Cache: This represents the current amount of space occupied in the cache. It will be less than the ‘Total Cache Size’ only if you haven’t yet utilized the full cache capacity. Once it reaches 100%, the system maintains this level of utilization by automatically removing older data to accommodate new incoming data, ensuring that the most recent files are always locally available.
• Pending Uploads: This indicates the volume of data waiting to be uploaded. It is crucial to monitor this value to prevent it from approaching the ‘Total Cache Size’. The goal is to maintain this value at or near zero, indicating that there are no pending uploads. Note that reducing the ‘Pending Uploads’ to zero does not free up space on your hard drive; it merely signifies that all uploads have been processed.

To maintain optimal performance, it’s important to carefully manage the cache size and balance your ingress and egress speeds. This helps in keeping the ‘Pending Uploads’ at a manageable level, preferably below 80% of the ‘Total Cache Size’. If ‘Pending Uploads’ nears the total cache capacity, the gateway module will instruct clients to reduce their data transfer rate, allowing time for the pending uploads to clear and prevent system overload.

The System tab will contain more detailed information on the specs of the environment, including the results of a brief internet bandwidth test run at container start.

Starting, Stopping, Updating

The command to start the container must be run from the folder containing docker-compose.yml and .env

docker-compose up -d

The -d flag runs the command in “daemon” mode, returning command of the terminal to the user after execution. The container can be checked on while running with docker ps which lists the currently running containers. To see all containers, even stopped ones, use docker ps -a

To stop the container from running, run

docker-compose stop

To update the container when a new image is available, run

(docker-compose pull) -and (docker-compose up -d --force-recreate)

Docker Desktop – WSL2 Resource Limits

If the Relayer container is performing poorly, and does not appear to be using much memory even when available, it is likely Docker Desktop is hitting a resource limit. New Docker Desktop installs are likely steered toward the WSL2 backend, which while more stable than Hyper-V, have unintuitive memory and CPU constraints.

If this is suspected to be the case, visit this Microsoft article on setting custom limits for the WSL2 engine. You will likely need to create a .wslconfig file in your C:\Users\$username folder. The format of the .wslconfig file is contained in the linked page, but the most pertinent settings are below:

# Settings apply across all Linux distros running on WSL 2
[wsl2]
# Limits VM memory to use no more than 4 GB, this can be set as whole numbers using GB or MB
memory=4GB
# Sets the VM to use two virtual processors
processors=2

Edit and save this file in Notepad, and restart Docker Desktop (remembering to start it again as administrator). The Relayer container should now adhere to the resource limits outlined in this configuration file.