Setup Aidbox.Dev

Step by step how to install Aidbox.Dev on-premises. Estimated reading time: 7 min

Overview

You can run Aidbox.Dev on macOS, Linux and Windows 10 Pro

We are providing a lightweight version of Aidbox named Aidbox.Dev — a special version aimed at local development and in your CI. To obtain access to Aidbox.Dev, please use our License server.

License obtaining

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

2. Enter a short description of your project and select the Aidbox.Dev option.

3. Congratulations! Now you have a license key.

Aidbox.Dev Installation

Step 1. Install Docker Compose

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

Step 2. Create docker-compose.yaml

Clone our official repository with the sample configuration.

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

Create the .env file with your Aidbox.Dev parameters.

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

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
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 about 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=password
AIDBOX_PORT=8888
AIDBOX_FHIR_VERSION=3.0.1
PGPORT=5432
PGHOSTPORT=5437
PGUSER=postgres
PGPASSWORD=postgres
PGDATABASE=devbox
PGIMAGE=aidbox/db:11.1.0
AIDBOX_IMAGE=healthsamurai/devbox:0.4.1
# uncomment next line to work with edge channel
# AIDBOX_IMAGE=healthsamurai/devbox:edge

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_FHIR_VERSION

true

Version of FHIR - 1.0.2, 1.4.0, 1.8.0, 3.01, 3.2.0, 3.3.0; Currently 3.0.1 is recommended version.

AIDBOX_IMAGE

true

can be specific image tag or one of :edge or :latest

AIDBOX_ADMIN_ID

false

Id for admin user (default: admin)

AIDBOX_ADMIN_PASSWORD

false

Password for admin user

If AIDBOX_CLIENT_ID & AIDBOX_CLIENT_SECRET are provided - Aidbox will start in secured mode with access control turned on; API Client with provided ID and secret will be created as well Access Policy, which grants root privileges to this Client. In a simplest way you can access Aidbox API using basic auth and this client credentials.

Starting Aidbox in open mode without AIDBOX_CLIENT_SECRET is disabled!

AIDBOX_IMAGE specify one of image from healthsamurai/devbox repository. Take a look at available versions at docker hub.

Run Aidbox.Dev

Run Docker Compose

$ docker-compose up -d

That's it! Aidbox.Dev is running and you can point your browser to http://localhost:8888 to see a fancy welcome page. Insert your ADMIN_ID and ADMIN_PASSWORD and you will see your development environment. This is the beginning of 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.

Advanced tips

You can test your docker-compose.yaml with

docker-compose config # to inspect your configuration

You can access you 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 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

Be careful with $ sign in url paths (aka /$metadata) in shell - you have to escape it ( /\$metadata) otherwise shell will try to interpret it as variables ;)

Stop Aidbox.Dev

$ docker-compose stop

Destroy Aidbox.Dev

$ docker-compose down

By default docker-compose file mount folder ./pgdata as persistent volume for PostgreSQL, so it will survive restarts and destroy of containers. If you want to completely cleanup previous installation just rm -rf ./pgdata

Upgrade Aidbox.Dev

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