Install XOSP

This page provides a detailed description of how to install the Plxtra XOSP release onto your local computer. See the Quick start page for a more streamlined description to get you up and running quickly.

Overview

XOSP is a distribution of the Plxtra software suite, providing a full retail trading platform and digital exchange for the purposes of demonstration, evaluation, and development.

XOSP is not intended for a production retail trading environment.

Installing Plxtra XOSP involves:

1. Check you meet the system requirements
2. Installing prerequisites
3. Downloading an XOSP release
4. Preparing your environment
5. Running the XOSP installation scripts
6. Perform the final manual steps
   1. Installing the SSL certificate
   2. Installing DNS aliases into your hosts file

After the installation is complete, you can begin using Plxtra.

System Requirements

Plxtra XOSP has the following physical requirements for installation:

1. An x86-64 processor. Arm is not currently supported by Plxtra.
2. 4GB of storage for the database and container images
3. 1GB of RAM for container services

Plxtra XOSP supports the following operating systems:

1. Windows 10 (22H2) or 11, with WSL2 support.
2. Linux distributions such as Alpine, Debian, RHEL, and Ubuntu. (See the supported platforms for PowerShell)

Additional operating systems, such as Mac OS or additional community Linux distributions, may work but are not officially supported. Compatibility issues may arise.

XOSP has been tested on Windows 10 22H2 and Windows 11. (Testing on Linux distributions will be carried out shortly)

Prerequisites

The following prerequisites need to be installed beforehand:

1. PowerShell
   The installation scripts for XOSP require PowerShell 7.5+
   https://learn.microsoft.com/en-us/powershell/scripting/install/installing-powershell
2. (Windows only) WSL2
   Docker on Windows requires either WSL2 or Hyper-V to run Linux containers. XOSP has not been tested in the Hyper-V scenario.
   https://learn.microsoft.com/en-us/windows/wsl/install
3. Docker
   XOSP utilises Docker to manage the containers running the Plxtra services. Docker Desktop can be used to view and manipulate these containers.
   https://docs.docker.com/get-started/get-docker/

Download XOSP

After ensuring the prerequisites are installed, the next step is to download XOSP.

XOSP provides the scripts and base configuration files for a complete Plxtra installation. It also provides a base docker-compose file used to arrange the containers running the Plxtra services.

There are multiple options for downloading XOSP:

1. Select and download a specific release from GitHub.
2. Download a zip of the latest code from the GitHub repository, which will need to be extracted.
3. Use Git locally to clone the repository to your machine, and install directly from the working copy.

Choose whichever one best fits your needs.

Preparation

Make sure your environment is ready to begin.

1. Docker needs to be started and accessible. If you’re using Docker Desktop, ensure the engine is running. You should see ‘Engine running’ in the bottom left corner of the Docker Desktop application.
2. PowerShell needs permission to run the scripts. If you extracted XOSP from an archive, you may encounter security issues attempting to run untrusted scripts.
   The easiest way to fix this is with PowerShell, by running the command Get-ChildItem *.ps1 | Unblock-File in the XOSP folder.

Install XOSP

An XOSP release provides a number of scripts for installing and manipulating your Plxtra installation. These scripts are written in PowerShell and need to be run from a PowerShell terminal.

Once you have a PowerShell terminal, navigate to the folder you downloaded XOSP to, and use the following commands

1. .\XOSP-Clear.ps1 (optional)
   This script removes all XOSP-related Docker containers, along with the database and any other files used by the Plxtra installation. This script is useful if you want to start with a fresh installation.
2. .\XOSP-Configure.ps1
   This script generates the installation configuration. This includes user and database credentials, certificates, as well as applying any configuration settings to customise the installation to your needs.
3. .\XOSP-Install.ps1
   This script creates the Docker containers, and exercises various system APIs to populate it with initial data. This script can take several minutes to run, depending on your computer’s performance.

Once installed, you will be presented with a list of manual steps to perform to make the installation accessible from a local browser, along with links to the Plxtra web front-ends, and some default credentials to access them.

Manual Installation Steps

The XOSP installation process does not interact with any software outside of Docker and the Plxtra installation. This means things like DNS resolution and SSL certificates need to be installed manually before Plxtra will be accessible from a web browser.

Enable SSL and HTTPS

XOSP’s default configuration prepares Plxtra to use HTTPS for all external communications. This is enabled via a self-signed certificate generated during the Configure step, which needs to be installed into your operating system or browser’s certificate store.

The generated certificate is named xosp.crt, located in the Docker folder within XOSP.

Installation of the certificate depends on your specific operating system and browser.

• Windows with Chrome or Edge: Use the certmgr command to install it into the Trusted Root Certification Authorities. Make sure to restart your browser if it’s running.
• Windows with Firefox: Firefox requires a self-signed root, and is not currently supported. You can, however, skip this step and accept the certificate manually for each domain.
• Linux: This process is distribution-specific, but generally involves placing the certificate into /etc/certificates and running update-ca-certificates.

Note that this certificate is self-signed and should only be used for testing and development purposes. It is not suitable for a production environment.

Enable DNS resolution

XOSP’s default configuration sets up Plxtra to utilise subdomains of xosp.localhost to access the services. This removes the need to expose multiple ports for each service, and instead requires some DNS aliasing.

For a purely local installation, we recommend doing this through a simple addition to your operating system’s hosts file.

The Install step will generate an example hosts file under the Docker folder within XOSP, which will have the correct aliases for your configuration to apply: Windows: This file will reference 127.0.0.1, and require a port override on URLs to access, which by default is 8043. Linux: Containers can be directly accessed by IP, so the file will reference the appropriate container’s IP, and will not require a port override.

To install the aliases, simply copy the contents of this file into your hosts file as appropriate for your operating system:

• Windows: Can be found at C:\Windows\System32\drivers\etc\hosts. You will need an editor such as Notepad in Administrator mode.
• Linux and MacOS: Can be found at /etc/hosts.

The specific domain (and SSL port if required) can be overridden with the configuration settings for XOSP.

Next Steps

Once installation is complete, you should be able to access your Plxtra installation whenever Docker is running.

• Web Browser
  Plxtra front-ends can be viewed with a web browser. The full URLs for these applications will be shown at the end of the Install step, together with the username and password for an administrative account. We recommend changing the password and recording it somewhere for reference.
• Public APIs
  The Plxtra public APIs can be accessed by getting an Access Token from the authentication server.
• XOSP-Control
  To perform administrative tasks like registering new Markets, Symbols, Users, or Trading Accounts, the Control terminal can be used.
• Development
  To start customising

Development

For front-end development, you can download and build the Plxtra front-ends such as Motif, Arclight, and Expo, or create your own.

Just point them at your local Plxtra installation and provide some credentials. Development Plxtra applications are already registered by XOSP, but you can easily add your own to the example authentication server.

For back-end development, you can download and build the specific services you’re interested in, and debug them directly inside Docker. We’re still working on this workflow, so check back in the future.