App Hub for DHIS 2

Environments

Branch	Environment	URL	Build status
next	staging	https://staging.apps.dhis2.org/
master	production	https://apps.dhis2.org/

Getting started

Docker Compose

See docs in dhis2/docker-compose/app-hub.

Local Installation

1. Install dependencies with yarn install
2. Copy server/.env.template to server/.env (cp server/.env.template server/.env) and edit server/.env. For development, your config will probably look something like:

   NODE_ENV=development
   RDS_USERNAME=postgres
   RDS_PASSWORD=postgres
   NO_AUTH_MAPPED_USER_ID=true
   
3. Create database tables with yarn db:migrate.
4. Seed the database with yarn db:seed

Run

yarn start

Reset database

yarn db:reset

Backend config file

The backend config file server/.env contains credentials for the database, AWS S3 bucket and Auth0.

Available options are documented in .env.template.

See server/knexfile.js to specify which database connections/credentials or server to use depending on the value of process.env.NODE_ENV.

Frontend config

The frontend needs to know some basic information about the server to configure routes and API endpoints. This is located in client/default.config.js.

You can rename or copy this file to override the settings.

Config files are loaded in the following order:

1. default.config.js
2. config.js

Environment specific configurations are also supported, and are loaded if process.env.NODE_ENV is set to either development or production.

• development.config.js
• production.config.js

Note that the exported objects from each config file are merged with the previous, so any options not changed are kept from the previous config.

Note: If you make any changes, you will need to rebuild or restart webpack-dev-server for the changes to take effect.

Example Development Config

// development.config.js

module.exports = {
    api: {
        baseURL: 'http://localhost:3000/api/',
        redirectURL: 'http://localhost:3000/user',
    },
    routes: {
        baseAppName: '',
    },
}

Base app name

This is the basename of where the app is located, used by routes. If it's hosted at http://localhost:3000/someUrl this should be someUrl otherwise leave empty.

routes.baseAppName: ''

API BaseURL

The endpoint of the backend API to be used.

api.baseURL: 'http://localhost:3000/api/',

API Redirect URL

The URL to be used when auth0 has successfully logged in a user, and is redirected back to the page. Note that this URL needs to be whitelisted on the auth0 side aswell.

api.redirectURL: 'http://localhost:3000/user/'

Run the project

yarn start will start both the frontend and backend.

Frontend available at localhost:8080. Web API available at localhost:3000/api/v1.

Swagger UI available at localhost:3000/documentation Swagger specs available at localhost:3000/swagger.json

Clone the existing production App Hub (approved/published apps) to your own local App Hub

yarn start

and then in another terminal:

yarn run clone

Release

This application is automatically released when merging into controlled branches.

• The next branch is deployed to staging.
• The master branch is deployed to production.

So: all work should be merged to next, and then next is merged to master when we decide to cut a release.

Report an issue

The issue tracker can be found in DHIS2 JIRA under the HUB project.

Deep links:

• Client:

  • Bug
  • Feature
  • Task

• Server:

  • Bug
  • Feature
  • Task