Start iCapture v3 Locally
After forking and downloading iCapture v3, run it on your computer and connect it to your project's DHIS2 instance. Complete this setup before creating a custom form.
1. Prepare your environment
Complete Fork the Core Repository and open the downloaded fork. You also need:
- Node.js and Yarn versions compatible with your fork's current dependencies and setup guidance.
- A reachable DHIS2 instance and a user account with access to the required datasets, programs, and organisation units.
- A DHIS2 administrator who can update the instance's CORS settings.
Use a development or test instance while creating and testing forms.
2. Open your project folder
Open the cloned fork in your editor, then open a terminal in its root directory:
cd icapture-v3-your_project_name
Replace your_project_name with your project name. You should see package.json, .env.sample, and src/ in this folder.
3. Create your local configuration
Copy .env.sample to a new file named .env in the same directory. If .env already exists, edit it rather than overwriting it.
On macOS or Linux, for a new configuration:
cp .env.sample .env
You can also copy and rename the file in your editor. Open .env and replace the sample connection values with those for your DHIS2 instance:
VITE_BASE_URL="https://your-dhis2-instance.example.org/"
VITE_USERNAME="your_username"
VITE_PASSWORD="your_password"
VITE_DEBUG="false"
| Variable | What to enter |
|---|---|
VITE_BASE_URL |
Your DHIS2 instance base URL, including its context path if present, for example https://your-server.example.org/dhis2/. |
VITE_USERNAME |
Your DHIS2 username. |
VITE_PASSWORD |
The password for that account. |
VITE_DEBUG |
Keep false for normal local development unless debugging requires otherwise. |
Save .env in the project root, alongside .env.sample and package.json. Keep the variable names unchanged.
Local credentials
Keep .env out of Git; the current iCapture v3 checkout ignores it. These VITE_ connection values are available to the browser during development. Use a test account and keep this credential-based configuration for local development. Do not publish it as a deployed application configuration.
4. Install dependencies
From the project root, run:
yarn install
Wait for installation to finish successfully before continuing. If Yarn is unavailable or the command reports a Node.js version error, check your fork's environment requirements before retrying.
5. Start the local application
Run:
yarn start
Keep this terminal running. Open the local address printed in the terminal. The current development configuration uses port 3000, normally:
http://localhost:3000
If that port is unavailable, the server may use a different port. Use the actual local address printed by the server for both your browser and the next step.
6. Add the local address to the DHIS2 CORS whitelist
The application runs locally while its data comes from your DHIS2 instance. DHIS2 must allow requests from the local application's origin.
- Open the DHIS2 instance configured in
.env. - Sign in with an account authorised to manage system settings, or ask your DHIS2 administrator to complete these steps.
- Open System Settings, then Access.
- Find CORS whitelist. Some DHIS2 versions label this CORS allowlist.
-
Add your local application's origin on its own line, keeping the existing entries. For the usual local address, add:
http://localhost:3000 -
Save or apply the setting if prompted.
- Return to the local iCapture application and reload the page.
Enter the local application's origin: its scheme, hostname, and port. Do not enter the remote DHIS2 URL or a form's page path. If you open the application using http://127.0.0.1:3000 or another port, add that exact origin instead.
DHIS2 documents the CORS setting in System Settings: Access settings.
7. Confirm the connection
Check that iCapture loads successfully and shows the datasets, programs, and organisation units available to your configured user. Open a standard form before adding any custom code.
If you change .env, stop the development server with Ctrl+C, run yarn start again, and reload the application.
Troubleshooting
| Problem | What to check |
|---|---|
| Browser reports a CORS error | The whitelist on the configured DHIS2 instance includes the exact origin used in the browser; preserve the scheme and port. |
Authentication fails or a request returns 401 |
The instance URL, username, and password are correct; try signing in to DHIS2 directly with that account. |
A request returns 403 or expected metadata is missing |
The user has the required authorities, sharing access, and organisation unit assignments. |
| The instance cannot be reached | Check the base URL, context path, network or VPN connection, and certificate trust. |
Changes to .env have no effect |
Save the file in the project root and restart yarn start. |
| The server uses another port | Open the printed address and update the CORS whitelist to match it. |
Next step
Read Extension Basics, then choose the aggregate, event, or tracker form guide.