healthforge/kaji repository overview

⁠About

Kaji is a general-purpose clinical data repository supporting a large portion of the FHIR STU3 spec. It is written in Scala with Finagle for performance and uses a PostgreSQL backend to take advantage of advanced features such as jsonb storage and table inheritance.

For more information read our blog post⁠

⁠Try

A public Kaji sandbox is made available to the community for testing and educational purposes. Data is cleared on a daily basis.

https://kaji.healthforge.io/⁠

⁠Usage

⁠Docker Compose

Example docker-compose.yml:

version: '3'
services:
  kaji:
    image: healthforge/kaji
    ports:
      - "8080:8080"
      - "9990:9990"
    depends_on:
      - postgres
    networks:
      - database
    environment:
      - MASTER_POSTGRES_HOST=postgres
      - POSTGRES_TLS=false
  postgres:
    image: postgres:9
    networks:
      - database
    environment:
      - POSTGRES_USER=fhir
      - POSTGRES_PASSWORD=fhir
networks:
  database:

Start with docker-compose up

Admin console should be available on http://localhost:9990/admin⁠

⁠Create example tenant

Example tenant.json:

{
  "baseUrl": "http://localhost:8080",
  "postgresHost": "postgres",
  "postgresDatabase": "fhir",
  "postgresUsername": "fhir",
  "postgresPassword": "fhir"
}

Note that this configuration is reusing the master database to avoid additional configuration. They do not conflict as there is only one master table, however additional tenants would require their own database.

POST config to admin tenants endpoint

curl -d "@tenant.json" -H "Content-Type: application/json" -X POST http://localhost:9990/admin/tenants

Note that creation is asynchronous and there may be a short delay before the tenant is accessible

Newly created tenant should be visible at http://localhost:9990/admin/tenants⁠

FHIR API for tenant should be available on http://localhost:8080⁠

⁠Sample requests

Create patient

curl -d '{"resourceType": "Patient", "name": {"family": "Smith", "given": ["John"]}}' \
    -H "Content-Type: application/json" -X POST http://localhost:8080/Patient

Get all patients

curl http://localhost:8080/Patient

⁠AWS CloudFormation

An example stack for Kaji.

IMPORTANT: This is intended as a demo and not suitable for production use. See notes below

• Download⁠
• Launch Stack⁠

⁠Notes

• Kaji is deployed on Fargate with no autoscaling. Default 1 instance.

• A public load balancer exposes the FHIR API on port 80 (no encryption).

• The FHIR API has no authentication and by default is exposed to the world (0.0.0.0/0).

• A single postgres database (fhir) and admin credentials are used for the master and tenant tables.

• Will create a new VPC and related infrastructure by default, but can also be deployed into an existing VPC.

⁠Post Launch

After deploying the stack the database must be initialised. There is an initialisation task definition (InitTaskDefinition) which can be run to do this which:

• Drops any existing fhir database

• Creates a new fhir database

• Initialises the master schema

• Creates an example tenant which will be available on the load balancer's default hostname (see LoadBalancerUrl in stack output)

The init task must have the same environment as the normal instances, in particular:

• Must use the same VPC

• Must have the ContainerSecurityGroup

• Must have access to the public internet (requires a public IP address in the deployed VPC)

⁠Environment variables

Kaji can be configured with the following environment variables

⁠HTTP_INTERFACE (0.0.0.0)

IP address of interface that the API should bind to.

⁠HTTP_PORT (8080)

Port number to expose API on.

⁠MASTER_POSTGRES_HOST (localhost)

Hostname of PostgreSQL server.

⁠MASTER_POSTGRES_PORT (5432)

Port number that PostgreSQL server is listening on.

⁠MASTER_POSTGRES_DATABASE (fhir)

Name of master database.

⁠MASTER_POSTGRES_USERNAME (fhir)

Username for master database.

⁠MASTER_POSTGRES_PASSWORD (fhir)

Password for master database.

⁠POSTGRES_TLS

Whether to use TLS in database connection.

Defaults to false when connecting to localhost and true for other hosts.

⁠CONNECTION_MAX_LIFETIME (3600)

Maximum connection lifetime in seconds.

Defaults to 1 hour

⁠CONNECTION_MAX_IDLE (300)

Maximum connection idle time in seconds.

Defaults to 5 minutes

⁠RESOURCE_LIMIT_MAX (1000)

Maximum number of resources returned.

⁠RESOURCE_LIMIT_DEFAULT (1000)

Default number of resources returned.

⁠License

Kaji is released under the MIT license⁠.

As with all Docker images, these likely also contain other software which may be under other licenses (such as Bash, etc from the base distribution, along with any direct or indirect dependencies of the primary software being contained).

As for any pre-built image usage, it is the image user's responsibility to ensure that any use of this image complies with any relevant licenses for all software contained within.