Environment setup for local product development - Ubuntu and Mac OSX

This page documents, how to set up your local development machine so that you can contribute to Avni products. If you are familiar with Docker, you can also refer to this page: Set up Avni locally with Docker

This setup documentation assumes that the user knows how to install and use some of the commonly used utilities. There is enough documentation on the Internet for installing and using them (putting in your version of Ubuntu would give you better results). We may link these docs in some places but not always. Exact commands are indicated as this always. Please ensure you have the following software setup.

  • Git
  • Github account
  • You OS user has sudo access
  • Curl
  • nvm
  • (Optional) Automatically set node version when you change your directory based on the .nvmrc file present in that directory. Place the function code as it in the file.

Other information

  • The Github organization for Avni is here - https://github.com/avniproject which has all the repositories.
  • The Linux user using which installation has to be done is expected to be a sudo user

Server Side Components


  • Install postgresql-server, postgresql-contrib packages (version >= 9.6.11 and <= 9.6.17)
  • Change postgres login access from peer to trust - Edit /etc/postgresql/PG.VER/main/pg_hba.conf. As in line 2 and 9 of this file.
  • Restart postgres - sudo systemctl restart postgresql.service
  • Create OpenCHS database, user and install extension - make build_db su=postgres


  • Install JDK 8

Avni Server

  • Clone avni-server from Github
  • Start Avni Server by running the command make start_server from the home directory of the avni-server project. (the first time it may take a few minutes to download Gradle, maven dependencies, and all the database migrations. wait till you see Started OpenCHS....)
  • Verify Avni server is running - curl http://localhost:8021/concept - should give you a few concepts in the JSON response.
  • Ensure tests are running fine - make test_server su=postgres (if you have installed Postgres as another user then you can replace the value)

Avni Rules Server

  • Clone rules-server from Github
  • Use nvm to install node version requires - nvm install from the rules-server directory. It would pick up the .nvmrc file to install the correct version.
  • Use make deps to install dependencies
  • Use make start for starting the server

Deploy Implementation

Avni is a platform and without the deployment of an implementation onto it, it doesn't do anything. If you want to understand how the whole system functions (app, web app, server), it is recommended you choose the sample implementation.

  • Clone the code of the implementation repository
  • Create a file by name secrets.json in the parent directory of the implementation directory like here.
  • run make deps deploy-dev-all su=postgres (you need to have avni-server running when you run this command)

Conceptual note

Avni authenticates against an external system (Cognito User Pools) which is a common resource. In developer environments, we do not use authentication because that would mean creating and sharing users on the user pool. If we use common user across developer machines the token issued and user status (locked, password) become shared data - leading to one developer blocking another user. This can hamper productivity. Hence for now, instead of engineering a solution around it, in developer environments, we can bypass authentication. This is sub-optimal but useful at a small scale (number of developers).

Bypassing authentication leaves one problem behind - how does the server know which user is sending the requests. As you will see later that we tell the server about the user, hence the server assumes that when no user is supplied to it, it should use that default user.

Start the server with the default user as implementation by running it is as: [email protected] make start_server

Field app components

Android SDK

  • Install Android SDK Manager
  • Use SDK Manager to install - platforms;android-28 and build-tools;28.0.3
  • Set ANDROID_HOME environment variable
  • Modify PATH to include $ANDROID_HOME/tools and $ANDROID_HOME/tools/bin

Android Emulator

  • Install Genymotion or Android studio.
  • Create a virtual android device and start it

Avni Android Client

  • Clone avni-client from Github
  • Use nvm to install node version requires - nvm install from the avni-client directory. It would pick up the .nvmrc file to install the correct version.
  • Install node dependencies - make deps (this would take some time in installing all the node dependencies)
  • Verify unit tests are running fine - make test
  • Launch app in android device
    • cp packages/openchs-android/config/env/dev.json.template packages/openchs-android/config/env/dev.json.
    • From the avni-client folder, perform make run_packager in one terminal and perform make run_app in another terminal. After the app loads up in the emulator, press the sync button in the app. This should download all the configuration and master data that has been set up for this implementation.

Web app components


Note: This is optional and is relevant only if you are working on features related to Avni onpremise deployment. We do not require Cognito or Keycloak access for most work (see conceptual note).

Setting up an implementation

Avni completed setup will create a blank slate. In this blank slate, you can create a new organization and configure the organization by setting up the applications, locations, users, etc. But if that is too much for you to get a feel of what is possible in Avni, then you can apply an implementation after creating the organization and an organization admin user. All the steps to follow below are from avni-web-app.

  • Create a new organization (note that you are a super admin when you are doing this)
  • Switch to the organization by choosing the org in the dropdown near the top right
  • Create an organization admin user (by filling only the mandatory fields and setting the org admin value correctly)
  • Get access to bundle export of an existing implementation by downloading it from another environment
  • Install the bundle by uploading it

Common tasks

  • Debugging avni-client

    • Use console.log(). You will be able to see the logs by running make log.
    • Debugging or testing changes done in avni-models
      • Since avni-models is an npm dependency in avni-client, you will have to build it locally and copy over the code in node_modules. Build it from avni-models repo by running make build and copy it to client by running cp -r dist/**/* ../avni-client/packages/openchs-android/node_modules/openchs-models/dist.
  • Debugging avni-webapp

    • Use chrome/firefox debugger or console.log().
    • Debugging or testing changes done in avni-models
      • Same as how it's done in avni-client. Shown above.