SMART Dev Sandbox
The SMART Dev Sandbox is an open source, Docker based version of the SMART Sandbox that can be installed locally on your machine to facilitate offline development and the use of custom data sets. Please note that it is not designed for clinical use and should not be used to store or access patient medical data.
This tool supplements the free online sandbox at https://launch.smarthealthit.org
and packages together the SMART launcher front end, DSTU2, STU3, R4 and R5 FHIR
servers based on the excellent http://hapifhir.io project, sample patient data,
an integrated web based interface to browse these sample patients, and a web based
FHIR data explorer. Additionally, these components can be set up individually from
the SMART docker images repository at https://hub.docker.com/u/smartonfhir/ (for
example, to run a local FHIR server you can type docker run -it -p 8080:8080 smartonfhir/hapi-5:r3-full
).
Check it out and please open issues on Github if you have suggestions or run into any problems!
System requirements
The hardware requirements are mostly depending on the number and kind of HAPI servers that you want to run.
We support 3 different servers for each FHIR version, each of which may require gigabytes of memory and
multiple CPU cores. These are configurable in the .env
file. You should disable servers that you don't
need and give as much resources as you can to the remaining server(s).
Configuration
The sandbox behavior is determined on startup using environment variables. These variables are defined in the
configuration file called .env
. Once you make changes, you will need to restart the sandbox using
docker-compose down
and docker-compose up
. If you change the used databases (by selecting different HAPI images)
you may also have to delete previous containers and volumes as described below.
Start the Dev Sandbox
- If you don't already have Docker on your system, download and install it from https://store.docker.com/search?type=edition&offering=community
- If you don't already have Git on your system, download and install it from https://git-scm.com/downloads
- Clone this project
git clone https://github.com/smart-on-fhir/smart-dev-sandbox.git
- Change to the new directory
cd smart-dev-sandbox
- Start the Docker containers
docker-compose up
- It might take some time to download all the images on the first run. After that, it probably takes a minute to start all the services.
- Open http://localhost:4000 in your browser to access the sandbox.
Stop the Dev Sandbox
To stop a running sandbox press Ctrl+C. Eventually, you should see something like (depends on what services you have enabled):
Stopping launcher ... done
Stopping hapi-r4 ... done
Stopping hapi-r3 ... done
Stopping hapi-r2 ... done
Stopping patient-browser ... done
Stopping home-page ... done
Stopping fhir-viewer ... done
If you don't see this output, then you will have to stop the services manually. To do so, run docker-compose down
.
FHIR Data
The HAPI FHIR servers are pre-populated with a set of sample patients and store data in Docker volumes. You can change the configuration to start the sandbox without any existing data.
Choosing a dataset
By default the servers will start with their "full database" that includes various generated datasets.
To reduce the number of pre-inserted patients (or to start with an empty database) you need to change
a configuration variable in the .env
file. The name of that variable is:
- For DSTU2 -
R2_IMAGE
- For STU3 -
R3_IMAGE
- For r4 -
R4_IMAGE
Please read the comments above that variable declaration to find out more about its possible values.
WARNING
The databases are stored in Docker volumes. Once you start a server (as part of the sandbox), a volume
will be created and persisted across further restarts. If you then decide to use a different database
and change the RX_IMAGE
(where X
is the numeric FHIR version) variable the sandbox may continue to use the already existing database
which leads to unpredictable behavior. To avoid that you need to remove the volume and the container
that created it first. For example for STU3 run:
docker container rm hapi-r3
docker volume rm smart-dev-sandbox_r3-database
Then start the sandbox as usual using docker-compose up
. Note that the same can also be used to reset
a server to its initial state and quickly discard any changes that you have made to the data.
Configuring the Patient Browser
The patient browser can filter the sample data in many ways, including by medical condition. To update the browser's autocomplete functionality after inserting or modifying patients, install NodeJS and run the following commands:
cd ./patient-browser
# run this the first time
npm i
# then, while the sandbox is running, to update conditions run:
# for STU2
node sync-conditions -s 2
# for STU3
node sync-conditions -s 3
# for R4
node sync-conditions -s 4
# When done restart the sandbox
cd ..
docker-compose down
docker-compose up
Hosting the Sandbox
By default everything runs on localhost
but you can change that by updating the HOST
variable. There could
be multiple reasons for wanting to do that. For example:
- You want the sandbox to be available on specific domain, say
sandbox.dev
. In this case add an entry to your hosts file to mapsandbox.dev
to127.0.0.1
and setHOST
in.env
tosandbox.dev
. - You want the sandbox to be accessible from every machine in your local network. Fond your LAN IP, set it
as
HOST
in your.env
file and restart the sandbox. - You want to put everything behind a proxy (perhaps to also enable SSL connections):
- Set up a proxy server (typically NginX or Apache) and configure it to pass requests up to localhost:port for each service that you enable.
- Set
HOST
in your.env
file to the domain that your proxy server is listening to. - (Re)start the sandbox.
Using Standalone Docker Images
This project composes multiple Docker images together. It is also possible to use a subset of the images
by setting the XX_ENABLED
variable to 0
where XX
is the name of the service that you want to exclude.
Since the images are available on the Docker hub at https://hub.docker.com/u/smartonfhir/ you can also use them directly. For example, to start just a local STU3 HAPI FHIR server, simply run:
docker run -it -p 8080:8080 smartonfhir/hapi-5:r3-full
Running the Dev Sandbox with TLS
In docker-compose.yml
:
-
Change the values for
LAUNCHER_BASE_URL
andBASE_URL
tohttps
-
Add a line in the
smart-launcher
section belowSTU4_ENABLED
:SSL_PORT : ${LAUNCHER_PORT}
-
change the ports line below that to:
- $LAUNCHER_PORT:$LAUNCHER_PORT
In www/template.html
:
- Search and replace
http://$HOST:$LAUNCHER_PORT
tohttps://$HOST:$LAUNCHER_PORT
And then docker compose up
normally. Your launcher and fhir proxy will now be running with a self-signed certificate (that you'll have to approve of course).