Build a custom Zonemaster-GUI installation package

Background

If you follow the Zonemaster-GUI installation instructions you can install an official package, and skip the instructions in this document.

However, if you have created a custom config.ts, done theme settings in tsconfig.json or done some theme updates then you must create a custom installation package for your custom installation. That can be achieved by following the steps below.

It is also important to state that even though the installation package is created on Ubuntu 22.04 below, the resulting installation package can be installed on at least all OSs supported in the Zonemaster-GUI installation instructions.

Prepare build environment

Start by creating a build environment. Here we assume and base it on Ubuntu version 22.04. The instructions will probably work with other versions of Ubuntu, or with other Linux distributions or other OSs, but then you might need to adapt some of the commands. Note however that it is important that the system fully supports npm.

Install toolchain

Make a clean installation of Ubuntu 22.04.
Update the package database and install Curl and Git.
```
sudo apt-get update
sudo apt-get install curl git
```

Install Node.js by using NVM, a node version manager.

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.2/install.sh | bash

After installation, log out and log in again to handle known issue, or just:
```
source ~/.bashrc
```
Install the supported Node.js version
```
nvm install 24
```
Switch to the previously installed version
```
nvm use 24
```

Check out source code

You need to checkout the source code of Zonemaster-GUI. In the usual case you will start with the master branch latest Zonemaster-GUI release as shown below.

git clone -b master https://github.com/zonemaster/zonemaster-gui.git
cd zonemaster-gui

If you already have a clone, make sure that you start from an up-to-date master branch.

git checkout master
git fetch --all
git pull

Add customization

From there, you can start to do your own customization. The simplest case only requires an update to config.ts. See the GUI Configuration overview for more details.

You should then save any changed file by doing the following steps (see Git tutorial).

git checkout -b MY-BRANCH
git add FILE
git commit -m 'What did I do?'

Build installation package

When building you should have a clean repository. Clean means that all temporary (i.e. non-versioned) files are removed.

List all files and changes that will be removed with next step.
```
git status --ignored
```
Remove all files and changes not included in a Git branch (listed in previous step).
```
git clean -dfx
git reset --hard
```
Install npm libraries in the repository.
```
npm install
```
Build the Zonemaster-GUI.
```
npm run build
```
If building fails, go back to the "Install toolchain" section and repeat the two nvm commands and restart building.
Build a Zonemaster-GUI installation package (a zip file).
```
npm run release
```

If all steps worked well, there will be a zip file in the current repository that can be used for installation, i.e. by replacing the official installation package (zip file) with this new zip file in the Zonemaster-GUI installation instructions.

If the build step above fails, go back to a safe branch and add your updates one by one, and repeating steps 1-5.

Testing the Build Locally

To test the static build locally, it must be served from the root path (/). You can use any static server. Here are two common options, and note that additional software has to be installed for those:

python3 -m http.server 8000 --directory ./public

php -S localhost:8000 -t ./public

Ensure you're serving the ./public directory (or your build output folder) as the root for all assets and routing to work correctly.