Linux Relayer-UI
A Relayer install begins with the XNS Console
- Register an account, and log in with it
- Head to the Billing the page
- Add a Payment Method (required even for free 50 GB)
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 distribution-specific Docker docs guides, and undertaking the post-installation steps.
Certain distributions (e.g. Ubuntu) may have prompted the user to install Docker during OS installation – this will not work, as it may use a package manager that installs Docker in an unsupported way (i.e. snap).
To verify docker engine is installed and running, 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 can be installed with sudo apt install docker-compose
$ docker-compose version
docker-compose version 1.29.2
If the output doesn’t resemble the expected, please review the Docker docs and go over the install guides carefully.
Docker installed following the Docker guide
Docker Post-Install steps performed
Docker Compose returning expected output
Installing Relayer UI
Create a directory where the Relayer program will store its files – consider using the user’s home directory. Make the directory with mkdir relayer. Enter it with cd relayer
Within this folder, two files need to be created: the first is docker-compose.yml and the second is .env
Create the first with nano docker-compose.yml, and 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:
- ./relayer-data:/relayer
#- /mnt/disk2/relayer-cache:/relayer/meta
ports:
- ${UI_PORT}:8888
- ${MINIO_PORT}:9000
env_file:
- .env
The line(s) under volumes: can be customized to your filesystem. This sample will create relayer-data within the directory the .yml exists in (this is the effect of the ‘.‘ in the path). The second line, optional, is commented out by the #. This symbol can be deleted and point to a separate cache folder if desired (demonstrated by /mnt/disk2/relayer-cache). Save and exit with Ctrl+X, Y, Enter. This file is highly sensitive in structure, and any stray/missing spaces can cause issues.
Next, nano .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 with Ctrl+X, Y, Enter.
Two files, .env and docker-compose.yml created and populated
Container Start
With docker-compose.yml and .env created (and if desired, customized), the docker container is ready to be created.
Still in the previously created relayer directory, run the command:
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
- Change from the defaults to original, secure values. 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.
Cache, and Endpoint keys modified
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.
Click the Endpoint URL to access the MinIO interface. Log in using the Access and Secret keys set during Configuration. 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.
Operation
The main dashboard will display some information on the status of the Relayer; Cache status is particularly of note:
- “Total” is the space made available to the cache earlier in Configuration
- “Used” is the volume currently in cache
- “Reserved” is the volume still in cache, pending upload to the network
When uploading begins, Reserved should begin draining toward zero. The cache will begin to decrease intake speed when it reaches 75% capacity to better allow the data already ingested to drain.
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 && docker-compose up -d --force-recreate