Create a Local Installation ZIP
Create an installation ZIP on your computer to test your customised application inside DHIS2. For a versioned package published to your project's GitHub Releases, use Versioning and Releases.
1. Prepare your project
- Work in a Git clone of your project fork, with its
.githistory available. The version script reads the latest commit. - Complete Start Locally and test the custom forms.
- Use Node.js and Yarn compatible with the project's dependencies. The included release workflow uses Node.js 24 and installs Yarn.
- Have access to a test DHIS2 instance and permission to install apps.
Run these commands from the application repository root:
yarn install
git status
Review your current changes so you can distinguish your extension work from generated files later.
2. Create the test package
On macOS or Linux, run the existing test packaging script:
yarn build:test
The script uses shell-style environment assignments. On Windows, run it in WSL or another compatible shell.
The script performs these steps:
- Calls
version.jswith the test version1.0.0. - Generates the app manifest and version information before compilation.
- Runs the production compilation script, which sets the DHIS2 base URL to
../../..and clears the local-development username and password. - Runs
postbuild, which packages the contents ofdistintoicv3.zip.
The resulting installation file is:
dist/icv3.zip
The test version is fixed by build:test; running this command does not determine a release version, create a Git tag, or publish a GitHub Release. Use it to test installation and application behaviour.
3. Install it in a test DHIS2 instance
- Sign in to your test DHIS2 instance.
- Open App Management.
- Choose Manual install, then Upload an app to install or the equivalent upload action.
- Select
dist/icv3.zipand wait for installation to finish. - Open iCapture from the DHIS2 app menu.
- Select the test dataset or program and organisation unit.
- Test opening, validation, saving, and reopening the custom forms.
The installed application connects to the DHIS2 instance hosting it and uses the signed-in user's access. It does not use the local development login from .env.
See Install iCapture v3 in DHIS2 for the installation screens, and Testing and Troubleshooting for the form checks.
4. Review generated files
The packaging scripts write generated version information and public manifests. If configured, they also copy the extension icon into public/icon.png.
Check your working directory again:
git status
Commit only intended project changes using Conventional Commits and Commitizen. Keep dist and incidental generated files out of your extension commit. The installed ZIP contains the files compiled for that run; files rewritten later by postbuild are not a reliable way to identify the version already inside that ZIP.
Troubleshooting
| Problem | What to check |
|---|---|
| The version script fails while reading a commit | Use a Git clone with commit history, rather than an extracted source archive without .git. |
| Node.js reports unsupported syntax or an engine error | Use a runtime compatible with the project; the release workflow uses Node.js 24. |
VERSION is not recognised as a command |
Run the script in a compatible shell, such as WSL on Windows. |
| Compilation fails and no installation ZIP is produced | Read the first error, resolve it, and rerun the command. An older ZIP is not evidence that the current run succeeded. |
| DHIS2 cannot recognise the archive as an app | Check for manifest.webapp at the ZIP root and upload icv3.zip, rather than the source archive. |
| The installed app displays an older layout | Check the uploaded package and refresh the application; complete the same form checks inside DHIS2. |