Setup Devbox

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.
Get your license
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.
Install Devbox
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.
1
git clone https://github.com/Aidbox/devbox.git
Copied!
Create the .env file with your Devbox parameters.
1
cd devbox && cp .env.tpl .env
Copied!
docker-compose.yaml file is parameterized with environment variables that can be stored by convention in the .env file (read more about env & docker-compose).
docker-compose.yaml
1
version: '3.1'
2
services:
3
  devbox:
4
    image: "${AIDBOX_IMAGE}"
5
    depends_on:
6
      - "devbox-db"
7
    links:
8
      - "devbox-db:database"
9
    ports:
10
      - "${AIDBOX_PORT}:${AIDBOX_PORT}"
11
    env_file:
12
      - .env
13
    environment:
14
      PGHOST: database
15
  devbox-db:
16
    image: "${PGIMAGE}"
17
    ports:
18
      - "${PGHOSTPORT}:${PGPORT}"
19
    volumes:
20
    - "./pgdata:/data"
21
    environment:
22
      POSTGRES_USER:     "${PGUSER}"
23
      POSTGRES_PASSWORD: "${PGPASSWORD}"
24
      POSTGRES_DB:       "${PGDATABASE}"
Copied!
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
1
AIDBOX_LICENSE_ID=<your-license-id>
2
AIDBOX_LICENSE_KEY=<your-license-key>
3
​
4
AIDBOX_CLIENT_ID=root
5
AIDBOX_CLIENT_SECRET=secret
6
​
7
AIDBOX_ADMIN_ID=admin
8
AIDBOX_ADMIN_PASSWORD=secret
9
​
10
AIDBOX_PORT=8888
11
AIDBOX_FHIR_VERSION=4.0.0
12
​
13
PGPORT=5432
14
PGHOSTPORT=5437
15
PGUSER=postgres
16
PGPASSWORD=postgres
17
PGDATABASE=devbox
18
​
19
PGIMAGE=healthsamurai/aidboxdb:13.2
20
​
21
AIDBOX_IMAGE=healthsamurai/devbox:edge
Copied!
Variable
required
Desc
AIDBOX_LICENSE_ID
true
Your license ID
AIDBOX_LICENSE_ID
true
Your license key
AIDBOX_CLIENT_ID
false
Root Client ID * (default: root)
AIDBOX_CLIENT_SECRET
false
Root Client Secret *
AIDBOX_PORT
true
Port number to access Aidbox backend
AIDBOX_BASE_URL
false
When specified, all relative links to resources will be replaced with absolute links including the base URL
AIDBOX_FHIR_VERSION
true
Version of FHIR - 1.0.2, 1.4.0, 1.8.0, 3.0.1, 3.2.0, 3.3.0, 4.0.0, 4.0.1; Currently 4.0.1 is recommended version.
AIDBOX_IMAGE
true
can be specific image tag or one of :edge or :stable
AIDBOX_ADMIN_ID
false
Id for admin user (default: admin)
AIDBOX_ADMIN_PASSWORD
false
Password for admin user
Please, find the full list of available environment variables here.
If AIDBOX_CLIENT_ID & AIDBOX_CLIENT_SECRET are provided - Aidbox will start in a secure mode with access control turned on; API Client with provided ID and secret will be created, as well as the Access Policy, which grants root privileges to this Client. In the simpliest way, you can access Aidbox API using basic auth and this client credentials.
Starting Aidbox in an open mode without AIDBOX_CLIENT_SECRET is disabled!
AIDBOX_IMAGE specifies one of the images from healthsamurai/devbox repository. Take a look at available versions at docker hub.
Run Devbox
Run Docker Compose
1
$ docker-compose up -d
Copied!
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.
We welcome your questions and comments about our products. Have an idea/question you'd like to share with our community? Submit it here.
What next?
Learn how to obtain access to the REST API by the link below.
Authentication Flows
Advanced tips
You can test your docker-compose.yaml with
1
docker-compose config # to inspect your configuration
Copied!
You can access your PostgreSQL on localhost using $PGUSER and $PGPASSWORD from env variables on $PGHOSTPORT .
1
# source variables
2
$ set -o allexport && source .env && set +o allexport
3
# run psql
4
$ psql -h localhost -p $PGHOSTPORT
5
psql (10.3, server 11.1)
6
Type "help" for help.
7
​
8
devbox=# \dt
Copied!
Or you can do it in the db container:
1
$ docker-compose exec devbox-db psql devbox
2
psql (11.1)
3
Type "help" for help.
4
​
5
devbox=#
Copied!
Inspect Aidbox logs:
1
$ docker-compose logs -f devbox
Copied!
Use curl to access API
1
$ curl localhost:$AIDBOX_PORT/\$metadata?_format=yaml
2
{message: Access Denied}
3
# ups box is secured
4
$ curl -u $AIDBOX_CLIENT_ID:$AIDBOX_CLIENT_SECRET \
5
  localhost:$AIDBOX_PORT/\$metadata?_format=yaml | less
Copied!
Be careful with the $ sign in url paths (aka /$metadata) in the shell - you have to escape it ( /$metadata); otherwise, the shell will try to interpret it as variables ;)
Stop Devbox
1
$ docker-compose stop
Copied!
Destroy Devbox
1
$ docker-compose down
Copied!
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
make update command updates all project services including dependencies.
1
update:
2
	docker-compose pull
3
	docker-compose up -d
Copied!
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