Set up Smartbox locally

This tutorial will guide you through Smartbox installation and accepting developer SMART application process

Get licenses

Go to the Aidbox user portal and request 2 "self-hosted" Aidbox licenses for Portal and Develop Sandbox. It is a long string like

eyJhbGciOiJ...

This string is your license key.

Install Docker and Docker Compose

Follow the official Docker guide to install Docker and Docker Compose

Configure cloud storage

Aidbox bulk API supports GCP, AWS and Azure cloud storages. To pass the Inferno tests cloud storage should be properly set up.

Set up email provider

In this guide mailgun is used to send email. Also Smartbox supports different email providers and SMTP

Email provider (mailgun) is used to communicate with users (developers, patients). It sends emails for resetting a password, email verification, etc.

Create docker-compose.yaml

Create a docker-compose.yaml file and paste there following content.

# docker-compose.yaml
version: '3.7'
services:
  aidbox-db:
    image: "${PGIMAGE}"
    ports:
      - "${PGHOSTPORT}:${PGPORT}"
    volumes:
    - "./pgdata:/data"
    environment:
      POSTGRES_USER:     "${PGUSER}"
      POSTGRES_PASSWORD: "${PGPASSWORD}"
      POSTGRES_DB:       "${PGDATABASE}"

  portal:
    image: "${AIDBOX_IMAGE}"
    depends_on: ["aidbox-db"]
    links:
      - "aidbox-db:database"
      - "sandbox:sandbox"
    ports:
      - "8888:8888"
    env_file:
      - .env
    environment:
      PGHOST: "database"
      PGDATABASE: "portal"
      BOX_AUTH_LOGIN__REDIRECT: "/admin/portal"
      BOX_PROJECT_ENTRYPOINT: "smartbox.portal/box"
      AIDBOX_LICENSE: "${PORTAL_LICENSE}"
      AIDBOX_BASE_URL: "http://localhost:8888"
      BOX_SMARTBOX_SANDBOX__URL: "http://sandbox:8888"
      BOX_SMARTBOX_SANDBOX__BASIC: "${AIDBOX_CLIENT_ID}:${AIDBOX_CLIENT_SECRET}"

  sandbox:
    image: "${AIDBOX_IMAGE}"
    depends_on: ["aidbox-db"]
    links:
      - "aidbox-db:database"
    ports:
      - "9999:8888"
    env_file:
      - .env
    environment:
      PGHOST: "database"
      PGDATABASE: "sandbox"
      BOX_AUTH_LOGIN__REDIRECT: "/"
      BOX_PROJECT_ENTRYPOINT: "smartbox.dev-portal/box"
      AIDBOX_LICENSE: "${SANDBOX_LICENSE}"
      AIDBOX_BASE_URL: "http://localhost:9999"

There are three services: aidbox-db, smartbox and developer sandbox. The first one is PostgreSQL database and the other ones are Aidboxes.

Create .env file

To configure Aidbox we need to pass environment variables to it. We can pass them with .env file.

PORTAL_LICENSE=<YOUR_PORTAL_LICENSE>
SANDBOX_LICENSE=<YOUR_SANDBOX_LICENSE>

# postgres image to run
PGIMAGE=healthsamurai/aidboxdb:14.5

# aidbox image to run
AIDBOX_IMAGE=healthsamurai/smartbox:edge

# Client to create on startup
AIDBOX_CLIENT_ID=root
AIDBOX_CLIENT_SECRET=secret

# root user to create on startup
AIDBOX_ADMIN_ID=admin
AIDBOX_ADMIN_PASSWORD=password

# db connection params
PGPORT=5432
PGHOSTPORT=5437
PGUSER=postgres
PGPASSWORD=postgres
PGDATABASE=postgres
AIDBOX_PORT=8888

# Mailgun
BOX_PROVIDER_DEFAULT_TYPE=mailgun
BOX_PROVIDER_DEFAULT_FROM=<YOUR_MAILGUN_FROM_EMAIL>
BOX_PROVIDER_DEFAULT_USERNAME=<YOUR_MAILGUN_USERNAME>
BOX_PROVIDER_DEFAULT_PASSWORD=<YOUR_MAILGUN_PASSWORD>
BOX_PROVIDER_DEFAULT_URL=<YOUR_MAILGUN_URL>

# GCP Cloud Storage
BOX_BULK__STORAGE_BACKEND=gcp
BOX_BULK__STORAGE_GCP_SERVICE__ACCOUNT=gcp-acc
BOX_BULK__STORAGE_GCP_SERVICE__ACCOUNT__EMAIL=<YOUR_SERVICE_ACCOUNT_EMAIL>
BOX_BULK__STORAGE_GCP_SERVICE__ACCOUNT__PRIVATE__KEY=<YOUR_SERVICE_ACCOUNT_PRIVATE_KEY>
BOX_BULK__STORAGE_GCP_BUCKET=<YOUR_GCP_BUCKET_NAME>

By default Aidbox logs are turned off, you can enable them by setting:

• AIDBOX_STDOUT_JSON=true

To use alternative email provider see the document

Launch Aidbox

Run the following command:

docker compose pull && docker compose up

Now Smartbox is ready.

Admin portal

Open the admin portal http://localhost:8888/ and login using credentials from the .env file AIDBOX_ADMIN_ID and AIDBOX_ADMIN_PASSWORD.

On the admin portal you can manage apps, patients and other admins.

Register developer

Submit developer registration form

• Open Developer Sandbox on http://localhost:9999
• Click the Sign Up button

• Register a new developer

Once you submitted the developer registration form, you should receive an email with the verification link.

• Follow the link to confirm your email address.

• You will be redirected on creation password form

• Create a password, submit it.

Now you can Sign In as developer to the Developer Sandbox.

Create a SMART app in developer sandbox

Get and deploy Growth Chart

To get and the Growth Chart downloaded and start it

git clone [e-mail]:smart-on-fhir/growth-chart-app.git
cd growth-chart-app
npm install
npm start

Register a SMART App

Once you launched the Growth Chart app, you can register it in the Sandbox.

• Click the Create app button

• Populate the form:

  • App name: Growth Chart

  • Confidentiality: public

  • Redirect URL: http://localhost:9000/
  • Launch URL: http://localhost:9000/launch.html
• Submit the new app form

• Click the Submit for Review button to send the application to review

After Growth Chart is registered copy its Client ID.

Update Growth Chart client_id

Open the file growth-chart-app/launch.html and fill the client_id property. Then save changes to the file.

Approve SMART App Publishing Request

Go back to admin portal on http://localhost:8888. You will see list of SMART App waiting for review.

• Open the review request, made on the previous step,

• click the Approve button.

Now the smart app is available for your patients

Enable FHIR API for tenant

Register a tenant

In order to register a tenant you need to create Tenant resource in Aidbox.

1. Open admin portal.

2. Go to tenants page.

3. Create new tenant named My Clinic (id will be my-clinic).

Once you created tenant, you enabled FHIR API for patient, practitioners and bulk clients. Patient portal is related to the tenant as well. The approved smart app is available for patient in that tenant.

Populate test data

1. Go to Aidbox REST Console. You may open it from admin portal

2. Run the following import:

   POST /$load
   Content-Type: text/yaml
   
   source: 'https://storage.googleapis.com/aidbox-public/smartbox/rows.ndjson.gz'
   merge:
     meta:
       tenant:
         id: my-clinic
         resourceType: Tenant

Once you saw 200 OK, Patient resource (id=test-pt-1) and corresponding resources had been uploaded into Aidbox. New we can create a User which has access to that data.

Create User resource

In order to enroll your patient, you need to create User resource. Open Aidbox REST Console and run the following command:

POST /User

email: [e-mail]
name:
  givenName: Amy
  familyName: Shaw
active: true
fhirUser:
  id: test-pt-1
  resourceType: Patient
roles:
- type: patient
password: password
meta:
  tenant:
    id: my-clinic
    resourceType: Tenant

Sign in as a User

Go to My Clinic's patient portal and login as the user, created above with [e-mail] login and password password. Launch smart app and provide requested consent.

That's it

In this tutorial we learned how to install Smartbox and to get your first SMART app approved.