Qortal Project

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== How To Build Qortal UI From Source ======
{{:qortal_official_logo_transparent_.png?400|}}

Building the [[https://github.com/Qortal/qortal-ui|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 =====

  * [[https://nodejs.org|Node.js]]
  * [[https://www.npmjs.com|npm]]

The easiest way to install the required version of Node.js is via [[https://nvm.sh|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 <nowiki>--</nowiki>refresh upgrade''

We will also need to install [[https://curl.se|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:
<code>curl https://raw.githubusercontent.com/creationix/nvm/master/install.sh | bash</code>

  * Windows systems will need to use [[https://github.com/coreybutler/nvm-windows|nvm-windows]] which can be downloaded [[https://github.com/coreybutler/nvm-windows/releases/latest/download/nvm-setup.exe|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:
<code>nvm ls-remote</code>
Install LTS-Gallium version supported by Electron:
<code>nvm install v18.16.1</code>
Install npm:
<code>npm install -g npm@9.8.1</code>

  * 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.16.1).
If you are ever on the wrong version you can do the following to get back to the correct version:\\
''nvm install 18.16.1 && nvm use 18.16.1''

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

  * On Windows systems, install the [[https://www.npmjs.com/package/win-node-env|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):
<code>git clone https://github.com/Qortal/qortal-ui</code>
Once done, you need to move into the directory. ("cd" stands for change directory)
<code>cd qortal-ui</code>

===== 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. [[qortal_ui_from_source#build_script|(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):

<code>npm install</code>

===== Build UI Server & Files =====

Finally type the following command to build the UI:
<code>npm run build</code>
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 [[https://www.electron.build|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 [[https://github.com/Qortal/qortal-ui/blob/master/electron-builder.yml|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 electron:
<code>npm run start-electron</code>

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.
<code>npm run server &</code>

===== 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 [[https://github.com/Qortal/qortal-ui/blob/master/build.sh|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 Project

User Tools

Site Tools

Page Tools
