Overview

Devbox is compatible with macOS, Linux, and Windows 10 Pro.

Devbox is a lightweight version of Aidbox. It is a special version aimed at local development and in your CI. To obtain Devbox license, please use our License server.

License obtaining

1. Visit and register on the License server, then click the GET LICENSE KEY button.

1. Enter a short description of your project and select the Devbox option.

1. Congratulations! Now you have a license key.

Devbox Installation

Step 1. Install Docker Compose

The recommended way to work with Devbox is Docker Compose. Install Docker for your OS following the Get Docker page, then follow the instructions on the installing Compose page.

Step 2. Create docker-compose.yaml

Clone the official repository with the sample configuration.

$ git clone https://github.com/Aidbox/devbox.git

Create the .env file with your Devbox parameters.

$ cd devbox && cp .env.tpl .env

docker-compose.yaml
version: '3.1'
services:
  devbox:
    image: "${AIDBOX_IMAGE}"
    depends_on:
      - "devbox-db"
    links:
      - "devbox-db:database"
    ports:
      - "${AIDBOX_PORT}:${AIDBOX_PORT}"
    env_file:
      - .env
    environment:
      PGHOST: database
  devbox-db:
    image: "${PGIMAGE}"
    ports:
      - "${PGHOSTPORT}:${PGPORT}"
    volumes:
    - "./pgdata:/data"
    environment:
      POSTGRES_USER:     "${PGUSER}"
      POSTGRES_PASSWORD: "${PGPASSWORD}"
      POSTGRES_DB:       "${PGDATABASE}"

Step 3. Fill in the .env file with the following parameters

Open the .env file and insert your License ID and License KEY, specify FHIR version and decide on the box security and distribution channel ( latest vs edge).

.env
AIDBOX_LICENSE_ID=<your-license-id>
AIDBOX_LICENSE_KEY=<your-license-key>
​
AIDBOX_CLIENT_ID=root
AIDBOX_CLIENT_SECRET=secret
​
AIDBOX_ADMIN_ID=admin
AIDBOX_ADMIN_PASSWORD=secret
​
AIDBOX_PORT=8888
AIDBOX_FHIR_VERSION=4.0.0
​
PGPORT=5432
PGHOSTPORT=5437
PGUSER=postgres
PGPASSWORD=postgres
PGDATABASE=devbox
​
PGIMAGE=healthsamurai/aidboxdb:13.2
​
AIDBOX_IMAGE=healthsamurai/devbox:latest
# uncomment next line to work with edge channel
# AIDBOX_IMAGE=healthsamurai/devbox:edge

Please, find the full list of available environment variables here.

Run Devbox

Run Docker Compose

$ docker-compose up -d

That's it! Devbox is running and you can point your browser to http://localhost:8888 to see a fancy welcome page.

**Input your ADMIN_ID and ADMIN_PASSWORD and you will see your development environment. This is the way to create your best healthcare products.

What next?

Learn how to obtain access to the REST API by the link below.

Advanced tips

You can test your docker-compose.yaml with

docker-compose config # to inspect your configuration

You can access your PostgreSQL on localhost using $PGUSER and $PGPASSWORD from env variables on $PGHOSTPORT .

# source variables
$ set -o allexport && source .env && set +o allexport
# run psql
$ psql -h localhost -p $PGHOSTPORT
psql (10.3, server 11.1)
Type "help" for help.
​
devbox=# \dt

Or you can do it in the db container:

$ docker-compose exec devbox-db psql devbox
psql (11.1)
Type "help" for help.
​
devbox=#

Inspect Aidbox logs:

$ docker-compose logs -f devbox

Use curl to access API

$ curl localhost:$AIDBOX_PORT/\$metadata?_format=yaml
{message: Access Denied}
# ups box is secured
$ curl -u $AIDBOX_CLIENT_ID:$AIDBOX_CLIENT_SECRET \
  localhost:$AIDBOX_PORT/\$metadata?_format=yaml | less

Stop Devbox

$ docker-compose stop

Destroy Devbox

$ docker-compose down

By default, docker-compose file mount folder ./pgdata as a persistent volume for PostgreSQL so that it survives restarts and destruction of containers. To clean up the previous installation completely: rm -rf ./pgdata

Upgrade Devbox

$ docker-compose down
$ docker-compose pull
$ docker-compose up -d

PGIMAGE

​aidbox/db is a custom compiled Postgres which is bundled with extensions necessary for the Aidbox. One of these extensions is the jsonknife, it provides a set of functions used in FHIR search API implementation. If your Postgres image is missing the jsonknife extension, then Aidbox will try to use other tools to implement jsonknife functionality. Fallback will happen in such order: jsonpath, plv8, pure PostgreSQL. Keep in mind that alternative implementations have lower performance 2021-04-09: plv8 jsonknife engine has been deprecated

​