Comment on page
Windows Full License Software Migration Guide
This guide will help DIY Windows users to upgrade an existing CLI provider with their Full License to run the Xa-Miner software. To do this you will need to have purchased a Full License or a Full License Upgrade from a Basic or free XM Basic license from the Xa-Miner Store. The installer supports all Windows 10 and Windows 11. Recent Windows Server versions like 2019 and 2022 will likely work as well but have not been tested formally. Versions of Windows prior to Windows 10 will also likely work but are unsupported.
Prior to starting, if you have changed the wallet password from the seed to a custom password, it is required to change it back to the seed. This is because the installer will discover the wallet seed during installation and this will be used to unlock the provider wallet automatically by Supervisor. To do this, on the Windows CLI, enter the command
spc wallet change-password, enter the current password when prompted and then enter the wallet seed as the new password and confirm.
The first step to install the software is to install Docker Desktop (latest version at the time of writing is 4.15.0). This can be downloaded from https://docs.docker.com/desktop/install/windows-install/. After downloading and starting the the installer, you will see the following:
Ensure to leave ‘Use WSL 2 instead of Hyper-V (recommended)’ ticked.
Once it’s finished installing, you’ll see the following:
If your provider is running, enter ‘spc stop’ in a command prompt and then click on Close and restart.
After restarting, run Docker Desktop. You may see an error stating Docker is not Initialized, this can be safely ignored. Once it’s started up, you will see the following message with regards WSL 2:
Follow the link in the message, there are 2 methods to installing WSL 2, either via the process documented here - https://learn.microsoft.com/en-us/windows/wsl/install or for older versions of Windows, using the following - https://learn.microsoft.com/en-us/windows/wsl/install-manual#step-4---download-the-linux-kernel-update-package
If using the 2nd method, download the installer linked in Step 4, run it and follow the prompts to install:
Once the installation is finished, click on Restart in the Docker Desktop dialog box.
After restarting, open up Docker Desktop and you should see it load up to this page:
Click on ‘Skip tutorial’ and you have completed the pre-installation steps for the Full Software.
Docker Desktop can be minimized at this point and next the Full License installer needs downloading from the XNS Console page (https://console.xns.tech/licenses). Click on the Download Latest Release button to download the Windows installer (note you will only see this if you have a full license in your account).
It's advisable now to run the installer as administrator to avoid the issue some users have run into where the installer stops at the searching for SPD step. To do this, right click the installer executable file and select Run as administrator:
A browser window will be automatically opened by the installer, showing the following, click on Advanced and then Proceed to…. (unsafe). This is just down to the self signed certificate used for the installer web page and not a security risk.
This will bring you to the initial installer page. Click on Next to proceed.
At this point the installer checks to see if Docker is installed on the system and then proceeds to the following page.
If the installer detects an instance of spd running on the system then the Migrate from DIY button will be active, this is the option to choose to upgrade a basic CLI provider to the Full License software. If the installer is run again once there is an xa-miner container running on the system then the Configure Existing option will be available and Fresh Installation and Migrate from DIY will not be available. This will be covered later in this guide. Click on Migrate from DIY.
In most cases the default Application Folder will suffice but can be changed if needed. To change the folder path, click on the existing path and a pop-up window will appear (note you’ll see all other application windows minimised and just the folder selection window will be shown, once you’ve selected the folder, the other application windows will be brought back up).
The installer will then attempt to find your metadata folder location. In some cases, the installer will be unable to automatically find the folder in which case you will see the page below and you need to set the metadata directory manually. Click on Set Metadata Directory and a folder selection pop-up window will appear (as above other application windows will be minimised). Find your metadata folder (by default this will be in C:\Users\<USER>\AppData\local\ScPrime but if you start spd with the -d flag to specify a different location then select that folder). Click on Finish.
The installer will then verify the api password and wallet seed are valid and display the following information about your existing provider. Confirm this is all correct, if anything does not seem correct then do not proceed and visit the relevant support channel in discord. Once confirmed, click on Finish.
The installer will then stop the running instance of spd.
The installer will then create a backup of your metadata folder and download it, this can be useful in case anything goes wrong to revert back to the basic provider setup. You will then see the following page for up to a minute while the docker container is downloaded and started up.
Then you will likely see another Windows Defender pop-up asking to allow Docker Desktop Backend access through the firewall, ensure Private networks is ticked and click on Allow Access. At this point the installer is finished and you will be presented with the link to the Xa-Miner UI.
Click on the link to proceed to the Xa-Miner UI setup. The first setup screen you should see the blockchain is already downloaded and extracted (as it's using the existing provider's metadata), once the Next button is available, click Next to proceed.
Should the Internet Status show Not Connected in the page above, this indicates the docker container that has been installed does not have internet access, this is likely related to having a firewall issue which is blocking the docker container. Either disable the firewall or add rules to allow the docker container to have internet access (should be covered by the Windows Defender pop-up above). Click on Next.
The next page displays the recovery seed phrase for your provider wallet, this is your existing seed phrase which you should already have saved. You can download the PDF containing it if you wish.
After clicking on Next you are taken to the registration page where you should register the Xa-Miner with the SAME e-mail address you used when ordering the license. This will help with ensuring all of your Xa-Miners and licenses are displayed together in the XNS Console page as they are linked by your e-mail address. If you are registering a 2nd or 3rd provider you should use the same e-mail address as the 1st is registered to (and the same address as any Xa-Miners you may have).
On the next screen click on Dashboard (note the Configure Ports is not possible on the Windows Xa-Miner UI and will be removed in a future version):
This will bring you to the main Xa-Miner UI Dashboard:
The GUI defaults to the Financials page where you can see your wallet balance, you can send or receive coins to the provider’s wallet, see a summary of your provider’s contracts and Income.
On the Stats page, you can see your provider’s stats. This is essentially your Grafana page that you are used to shown within the Xa-Miner UI. You can click on the Open in Grafana button to open up your public Grafana page in a new tab.
On the Storage page, you can see the storage folders which were discovered on the provider during the installation process. Here you can remove storage folders if you need to. See the Provider Maintenance section later in this guide for how to add new storage folders to a Full License DIY Xa-Miner.
On the Settings page, you can see your provider’s pricing config. Note these are now set for auto pricing so you do not need to change these settings and your provider will update them regularly to keep in line with the standard pricing structure for Xa-Miners. You can set your desired fiat currency which is used throughout the Xa-Miner UI from the drop down list at the bottom of the page.
Finally on the Support page, the status of Supervisor and the Daemon (spd) are shown, if either are offline there will be an Orange Restart button next to them where you can try to restart the processes. The rest of the buttons are as follows:
Download logs - this will zip up all the log files from your provider and the browser will download them to its default download location.
Reannounce - this is a manual reannounce button, Supervisor will now automatically re-announce your provider should the public IP address or ports change (so DDNS is no longer required for your provider). This button can be used should that not work or if the Support Team instructs you to use it.
Redownload - this button will redownload a fresh copy of the blockchain. Occasionally the consensus.db file can get corrupted and requires a fresh copy downloading.
Change Ports - should you need to change the ports your Xa-Miner is running on, click this button and enter the desired hosting port and relayer port. Typically these are consecutive ports like 4272 and 4273 or 14282 and 14283.
Reset Ports - this will reset your provider back to the default 4282 and 4283 ports.
Upload logs - this button will zip up your log files and then upload them to the Support Team’s server so they can be inspected to help in troubleshooting issues with a provider. Only use this at the instruction of the Support Team.
Open Chat Window - this feature allows you to chat 1:1 with a member of the Support Team without having to visit Discord. Please note that the Support Team is not necessarily available 24/7 and if no one is available, the chat button is disabled and will indicate that no one is online.
The final step now that the Xa-Miner UI is up and running is, if you have previously setup and auto startup script on your Windows provider to startup spd after a reboot, this needs to be disabled as the xa–miner docker container will automatically startup after a reload, Supervisor will then startup spd and unlock your wallet. If you followed the official Windows Setup guide, then the simplest way to disable the auto startup is to open Task Scheduler, right click on the task you created to start spd and disable it. If you also setup supervisor lite to start up then disable that task too.
Some typical maintenance tasks which a user needs to perform on their provider will now be slightly different with the UI as compared to using the CLI provider. These are documented below.
When a new version of the SPD daemon is released, for example, prior to the fork in January 2023, the process for full license installations is very straightforward.
Step 1 - In Docker Desktop, stop the container by clicking on the square icon to the right of the container
Step 2 - In File Explorer, locate the xa-miner app folder, by default it's C:\ProgramData\xa-miner\app. From here go into the config directory and then spd. Inside this folder you will see 2 files, ports.yml and spd. Move the spd file to the recycle bin. If you chose a different location for the xa-miner app folder during installation of the software then you will need to browse to that folder to find spd.
Step 3 - Start up the container in Docker Desktop by clicking on the play icon
If you refresh the Xa-Miner UI now, you will see on the Dashboard the updated SPD version.
Prior to upgrading to a new Xa-Miner container version, it is worth taking a copy of the docker run command used to deploy the existing container. This can help recover in case there are any issues in deploying the updated version which a few users have seen. To do this you must be running at least Docker Desktop 4.15.0, if you are on a previous version you should update to the latest version first.
In version 4.15.0 and later, click on the 3 dots to the right of your xa-miner container and click Copy docker run:
Then open a text editor like Notepad and paste the clipboard contents there. The output should look something like this (with your wallet seed where the blue redacted text is). Note the seed won't have any double quotes around it so you will need to add these as there are spaces in the seed for the command to work should you need it:
Save this file onto your desktop in case you need it later.
When a new version of the Software Xa-Miner is released, the process to update the software is to run the installer application used when first installing the software on the provider PC. This will bring up the installer UI as below:
Click on Next.
If there is a new version of the Xa-Miner container detected by the installer, the Update Existing button will be active and show Update Required underneath. Simply click on Update Existing, the installer will perform the upgrade (takes 1-2 mins) and when it's finished, the updated version will be running and the installer will exit. Refresh the Xa-Miner UI and the updated versions of the SPD, Supervisor and UI versions will show on the Dashboard.
To add a new storage folder to your provider, you will first need to add the drive into Windows, create a partition, format it and assign a drive letter. If it’s a large drive over 2TB, create multiple folders, plan for 1 folder per 2TB of space on the drive.
Once you have the folders created, run the installer application again, then in the installer GUI with the 4 options as below, select Configure Existing:
After clicking on Configure Existing, you’ll be presented with the following screen showing all the existing provider’s storage folders.
Click on Add Storage Folder
The same pop-up window will appear as earlier during installation. Select the folder you wish to add from here and click on OK. Repeat for each folder you wish to add.
Then you will see your new folder added to the list of storage folders.
Click on Finish. This GUI will show it configuring your Xa-Miner and then will present you with the following screen at which point you can close the browser tab and access the Xa-Miner UI again.
Now return to the main Xa-Miner UI, go to the Storage page and you’ll see the added storage folder there.
Enter the size in GB you want to set the folder size to and click Assign.
A similar process can be used in reverse to remove storage folders in a similar way to using ‘spc host folder remove <PATH>’ from the CLI. First navigate to the Storage page on the Xa-Miner UI, find the folder from the first column you wish to remove and click on the Remove button to the right.
Any data stored in the folder being removed will be moved by spd to other folders. This process may take some time depending on how much data needs moving so it’s recommended to remove just one folder at a time.
Once the folder is removed from the Xa-Miner UI, run the installer application again and choose Configure Existing:
The following screen will show all the folders which have been added to the Xa-Miner, note if you have more than 10 drives/folders then you may need to go to the next page or change the rows per page value to All to see the one(s) you want to remove.
Simply click on the red icon in the Action column against the folder you wish to remove and then click Finish. Once all folders on a drive have been removed, the drive can be physically removed from the PC.
Should the wallet seed phrase be forgotten, this can be recovered from the container terminal in Docker Desktop. The spc application has been added into the xa-miner container now, if spc is not available, an update of the Xa-Miner software will be required using the process above in the Upgrading to a new Xa-Miner Software Release section.
Bring up the Docker Desktop application, select Containers menu on the left side menu so you see the following page:
Click on the 3 dots on the right side of the xa-miner container and select Open in Terminal. This will give you a CLI for the container itself. Run the following command:
spc wallet seeds
This will show you the Primary Seed as below: