Run Aidbox locally with Docker

Aidbox project is a configuration of Aidbox instance, written in zen-lang. This getting started guide shows you how to setup a new Aidbox project.

Init & run Aidbox project
In order to run Aidbox locally, you need to have Docker & Docker compose installed. To begin with new aidbox project, 
run the following command depending on FHIR version you want to have
FHIR R4
FHIR R4B
FHIR R5
git clone \
  --branch=main \
  --depth=1 \
  https://github.com/Aidbox/aidbox-project-template.git \
  aidbox-project && \
  cd aidbox-project && \
  rm -rf .git
git clone \
  --branch=fhir-r4b \
  --depth=1 \
  https://github.com/Aidbox/aidbox-project-template.git \
  aidbox-project && \
  cd aidbox-project && \
  rm -rf .git
git clone \
  --branch=fhir-r5 \
  --depth=1 \
  https://github.com/Aidbox/aidbox-project-template.git \
  aidbox-project && \
  cd aidbox-project && \
  rm -rf .git
get your Aidbox license on aidbox.app​
and then set AIDBOX_LICENSE env variable in .env file
Once you set up the project and provided the license key, you may start Aidbox service with Docker compose by running:
docker compose up --force-recreate
Open http://localhost:8888 and see Aidbox login page. Sign in using login admin and password password.
--force-recreate argument for Docker Compose makes Docker to pull the latest Aidbox version if you have already pulled it before.
Now you are ready to use Aidbox. Let's see, what have we created.
Aidbox project structure
Aidbox project folder contains configuration files written in zen-lang and the docker-compose.yaml file to start Aidbox locally for development purposes.
aidbox-project/
├── .env
├── docker-compose.yaml
├── zen-package.edn
└── zrc/
    ├── config.edn
    └── main.edn
If you want to move zen-related files into subfolder, for example, project, you can use
BOX_PROJECT_GIT_TARGET__PATH=/project
AIDBOX_ZEN_ENTRYPOINT=main/box
in the .env file.
With these settings, the structure will be 
aidbox-project/
├── .env
├── docker-compose.yaml
└── project
    ├── zen-package.edn
    └── zrc
        └── project
            ├── config.edn
            └── main.edn
.env
Contains environment variables. At the start it has these defaults:
AIDBOX_LICENSE=<your license>
PGHOSTPORT=5437
PGUSER=postgres
PGPASSWORD=postgres
PGDATABASE=aidbox
AIDBOX_BASE_URL=http://localhost:8888
AIDBOX_PORT=8888
AIDBOX_CLIENT_SECRET=secret
AIDBOX_ADMIN_PASSWORD=password
BOX_PROJECT_GIT_TARGET__PATH=/aidbox-project
AIDBOX_ZEN_ENTRYPOINT=main/box
AIDBOX_DEV_MODE=true
AIDBOX_ZEN_DEV_MODE=true
Most of them are obvious. 
AIDBOX_ZEN_DEV_MODE enables watcher which reloads zen namespaces when they change. So if you change some file in zrc folder it will be reloaded without restarting Aidbox.
AIDBOX_DEV_MODE is used to debug access-policy.
zrc/main.edn
The main.edn file contains main/box entrypoint for your Aidbox configuration.
{ns main
 import {aidbox
         config}
 
 box
 {:zen/tags #{aidbox/system}
  :config   config/base-config
  :services {:admin-user-seed config/admin-user-seed
             :root-client-seed config/root-client-seed}}}
The config.edn file, imported by main.edn, contains configuration variables for Aidbox.
zen-package.edn
The zen-package.edn file is the project meta file. You can specify dependencies for external zen packages there.
{:deps {hl7-fhir-r4-core "https://github.com/zen-fhir/hl7-fhir-r4-core.git"}}
Troubleshooting
Could not find main/box
If you see the message in logs 
:entrypoint/error Could not find main/box
it means, Aidbox project wasn't configured correctly.
That's it
Now you have Aidbox project initialized and you ready to develop with Aidbox.
What's next
Read more on how to setup US core IG with Aidbox project.
Talk to a Health Samurai Engineer
If you'd like to learn more about using Aidbox or have any questions about this guide, connect with us on Telegram. We're happy to help.

Getting Started - Previous

Run Aidbox

Run Multibox locally with Docker

Last modified 11d ago