Qortal Project

The future of blockchain platforms

User Tools

Site Tools


Qortal Project Wiki

Important Notices


Project Model



Trade Portal

Data Hosting

Voting System

AT System


Frequently Asked Questions (FAQ)

How-To Guides

Node Setup Guides

Third-Party Services


How To Build Qortal UI From Source

Building the Qortal UI (User Interface) from source means you will be linking the dependencies and compiling it yourself from the open source code. Follow the steps below to download, install, build, and run the UI locally.

Installation Tools Needed

The easiest way to install the required version of Node.js is via nvm (Node Version Manager). First make sure your OS (Operating System) is up to date. Open the terminal and type the following command.

  • Debian-based: sudo apt-get update && sudo apt-get upgrade
  • Fedora / CentOS: sudo dnf --refresh upgrade

We will also need to install curl. This is a package that will be used to install nvm. The following command will install curl:

  • Debian-based: sudo apt -y install curl
  • Fedora / CentOS: sudo dnf -y install curl

We need nvm to manage which version of node we use. The following command will install nvm:

curl https://raw.githubusercontent.com/creationix/nvm/master/install.sh | bash
  • Windows systems will need to use nvm-windows which can be downloaded here.

Check the installation with the nvm -v command. You may need to refresh the environment by exiting and restarting the terminal window, or use the following command:

  • Debian-based: source ~/.profile
  • Fedora / CentOS: source ~/.bashrc

Now that your OS is up to date we need to install a few packages. Specifically Node.js and npm (Node Package Manager). Here are the installation commands for the terminal:

Fetch list of available Node.js versions:

nvm ls-remote

Install LTS-Gallium version supported by Electron:

nvm install v18.14.0

Install npm:

npm install -g [email protected]
  • On BSD do pkg_add node
  • Adding via binary package mirror will only work if you have set the package path. You can do a node or java build via ports instead by downloading ports with portsnap fetch method

You can verify your installation of Node.js using node -v (should be 18.14.0). If you are ever on the wrong version you can do the following to get back to the correct version:
nvm install 18.14.0 && nvm use 18.14.0

If you have an older installation of npm, please do not forget to update that with npm update -g

  • On Windows systems, install the win-node-env package with npm install -g win-node-env

Clone The Following Repo

The following command will clone the main UI repository (AKA all the code):

git clone https://github.com/Qortal/qortal-ui

Once done, you need to move into the directory. ("cd" stands for change directory)

cd qortal-ui

Dependency Installation & Linking

Now for the fun part, time to build the UI!

  • Note: If your system is capable of running bash scripts, you can skip the next two steps and just run the build script using the ./build.sh command. (more info)

We need to install and link dependencies in the main directory (qortal-ui). Assuming you are in the qortal-ui directory, the following commands below will link all the dependencies (press enter after each line, one by one):

npm install

Build UI Server & Files

Finally type the following command to build the UI:

npm run build

Hooray you built the UI from source! But there are still a few things left to do. If you want a fully packaged file (exe, deb, AppImage, etc.) you can use electron-builder with: npm run release (Note that this will build only for the platform it is run from by default.) The build config can be found in the electron-builder.yml file.

To Start The UI

You can run the UI using electron, but running it through server is recommended.
The following command will run UI using election:

npm run start-electron

Otherwise you can simply access it in your browser at http://localhost:12388 after using this command. The optional "&" runs commands in the background, to let you continue using the terminal.

npm run server &

Tips to Speed up Development

Every time you edit the code, you will need to run npm run build and refresh that part of the UI (depending on what part of the code you edited or added/removed). The fastest way to see your code changes is to first of all run the UI in your browser: npm run server & then, open a second terminal and do cd qortal & then enter the npm run watch command. Let that run for one or two minutes, until you see things stop moving in the terminal. Let me take a minute to explain how it works. First of all it is required that you run build before running watch. Normally if you make a change to the code, and build it will take two or three minutes for the change to be made after saving the file, and after that you have to refresh the UI page. That is REALLY slow for development. Instead, if you watch, it stays running in the background. After it has run for a few minutes it will only build your most recent changes. So after you save a file of code you edited, you can expect it to finish building that section of code in about 10 seconds, depending on how many lines of code you wrote. When looking in the terminal after saving a file, you will notice some text pops up, once that text goes away, it finishes applying your changes. You should now click to a new tab and back if the change is only in that tab. If the change is across the whole UI, you will have to refresh the page entirely.

Build Script

To automate the above process, run the build script with ./build.sh optionally specifying the following options:

  • -h: show help
  • -f: force relink and reinstall dependencies
  • -w: use npm run watch instead of npm run build to enable hot swapping
  • -s: run UI server after completing the build
  • -e: run electron server after completing the build

Example command to build and run the UI server:
./build.sh -s

qortal_ui_from_source.txt · Last modified: 05/11/2023 13:06 by quickmythril