Set up Smartbox locally
This tutorial will guide you through Smartbox installation and accepting developer SMART application process
Go to the Aidbox user portal and request 2 "self-hosted" Aidbox licenses for Portal and Develop Sandbox. It is a long string like
This string is your license key.
GCP Cloud Storage is used in Bulk API for storing and distributing exported data. To enable bulk API, you need to create GCP Cloud Storage, set up GCP Service Account, and provide full access to the service account on this Cloud Storage.
In this guide
mailgunis 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.
docker-compose.yamlfile and paste there following content.
There are three services: aidbox-db, smartbox and developer sandbox. The first one is PostgreSQL database and the other ones are Aidboxes.
To configure Aidbox we need to pass environment variables to it. We can pass them with .env file.
# postgres image to run
# aidbox image to run
# Client to create on startup
# root user to create on startup
# db connection params
# GCP Cloud Storage
By default Aidbox logs are turned off, you can enable them by setting:
Run the following command:
docker compose pull && docker compose up
Now Smartbox is ready.
Open the admin portal http://localhost:8888/ and login using credentials from the .env file
On the admin portal you can manage apps, patients and other admins.
To make Sandbox respect tokens issued by Patient Portal:
- Open the admin portal http://localhost:9999/ and login using credentials from the .env file
- Click the REST Console menu item in the left side bar
- Create TokenIntrospector resource like example below
iss: http://localhost:8888 # Patient portal base_url value
jwks_uri: http://localhost:8888/.well-known/jwks.json # Patient portal jwks URL
Submit developer registration form
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.
To get and the Growth Chart downloaded and start it
git clone [email protected]:smart-on-fhir/growth-chart-app.git
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
- Submit the new app form
- Click the Submit for Review button to send the application to review
After Growth Chart is registered copy its
Open the file
growth-chart-app/launch.htmland fill the
client_idproperty. Then save changes to the file.
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
In order to register a tenant your 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
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.
- 1.Go to Aidbox REST Console. You may open it from admin portal
- 2.Run the following import:POST /$loadContent-Type: text/yamlsource: 'https://storage.googleapis.com/aidbox-public/smartbox/rows.ndjson.gz'merge:meta:tenant:id: my-clinicresourceType: 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.
In order to enroll your patient, you need to create User resource. Open Aidbox REST Console and run the following command:
email: [email protected]
- type: patient
Go to My Clinic's patient portal and login as the user, created above with
[email protected]login and
passwordpassword. Loaunch samrt app and provide requested consent.
In this tutorial we learned how to install Smartbox and to get your first SMART app approved.