Skip to content

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 .git history 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:

  1. Calls version.js with the test version 1.0.0.
  2. Generates the app manifest and version information before compilation.
  3. Runs the production compilation script, which sets the DHIS2 base URL to ../../.. and clears the local-development username and password.
  4. Runs postbuild, which packages the contents of dist into icv3.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

  1. Sign in to your test DHIS2 instance.
  2. Open App Management.
  3. Choose Manual install, then Upload an app to install or the equivalent upload action.
  4. Select dist/icv3.zip and wait for installation to finish.
  5. Open iCapture from the DHIS2 app menu.
  6. Select the test dataset or program and organisation unit.
  7. 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.