Set up and use configuration projects
Aidbox Configuration project requires a few things:
We provide a CLI tool, called
zen
, which makes working with projects easier. It is distributed as jar
file and can be downloaded from our zen Github releases.Configuration projects, which are also zen projects, work as git repositories under the hood. This means that you need to have a directory initialized as a git repo. You can either create it from scratch or clone an existing one.
java -jar path/to/zen.jar init my-project
Then you need to set
BOX_PROJECT_GIT_URL
environment variable to the location of this repository so that Aidbox knows where to find it. Note that the location can be either a local path or a remote URL, for which you can optionally specify a commit and/or branch.Aidbox can load project from an URL or read directly from its file system.
BOX_PROJECT_GIT_URL
— where to clone your project from. Aidbox substitutes it togit clone <url>
command.BOX_PROJECT_GIT_PROTOCOL
— eitherhttps
orssh
. Assumes local dir if omitted.BOX_PROJEC_GIT_TARGET__PATH
— where to clone your project to and where to read it from. Default value is a directory in/tmp
If you specify only the target path then Aidbox expects you to clone a project into this location before it starts. This allows mounting persistent file system cache and using local file system for development. See tips for development and tips for production.
If a repository you want to use as a project is under restricted access, you can provide the necessary SSH or HTTPS credentials via the following environment variables:
BOX_PROJECT_GIT_ACCESS__TOKEN
— access token for HTTPSBOX_PROJECT_GIT_PUBLIC__KEY
— SSH public keyBOX_PROJECT_GIT_PRIVATE__KEY
— SSH private key
Project’s package file,
zen-package.edn
, should be located at the root of a configuration project. It is used to specify what dependencies, which are other zen projects, you wish to use.If you don’t have any dependencies, the file should look like this:
zen-package.edn
{:deps {}}
Aidbox starts reading configuration project from a zen entrypoint. It is a namespaced symbol which is tagged with
aidbox/system
tag. It is used to bootstrap the whole system.You can specify an entrypoint symbol via
AIDBOX_ZEN_ENTRYPOINT
environment variable.The entrypoint file should import all the packages and other namespaces you wish to use.
Its
ns
value should correspond to its filename (with -
replaced by _
).As an example, consider the following config file for a system which happens to import zen-fhir US Core IG package:
zrc/system.edn
{:ns system
:import #{hl7-fhir-us-core}
box
{:zen/tags #{aidbox/system}
…}
…}
You need to specify
AIDBOX_ZEN_ENTRYPOINT
environment variable. This variable is formatted as <entrypoint namespace>/<entrypoint symbol name>
. Given entry file such as above, you get the following:AIDBOX_ZEN_ENTRYPOINT=system/box
Besides system environment variables for setting up aidbox configuration project, there are many other envs Aidbox respects as part of backward compatibility. Still they are considered as legacy.
It's more preferable to set up Aidbox with aidbox.config/config. You may provide it with
aidbox/system
zrc/system.edn
{ns system
import #{aidbox aidbox.config}
box-config
{:zen/tags #{aidbox.config/config}
,,,}
box
{:zen/tags #{aidbox/system}
:config box-config
,,,}}
This is more preferable way, than configuring Aidbox via envs.
Aidbox Configuration project is a git repository. You need to commit all the changes you’ve made otherwise Aidbox won’t see them.
cd path/to/project && git add -A && git commit -m "new commit"
Suppose that you’ve configured your Aidbox instance with some heavy dependencies. During the development phase, you may wish to reuse these dependencies downloaded data.
BOX_PROJECT_GIT_TARGET__PATH
environment variable allows you to specify a path where your project with downloaded dependencies are going to be cached. By mounting this path to a persistent file system you'll provide downloaded data to Aidbox after a restart, thus making Aidbox reusing data (Aidbox also checks for dependencies updates in this case).If you want to cache dependencies for Aidbox Docker container, you need to mount a cache directory as a volume.
By default, Aidbox requires a restart after making changes to a configuration project. If you wish to enable a hot reload, set the following environment variable:
AIDBOX_ZEN_DEV_MODE=true
You can also use Aidbox UI to reload namespaces: proceed to
Profiles
page on the left sidebar and click the reload button in the upper left corner.POST /rpc
method: aidbox.zen/reload-namespaces
params: {}
Hot reload feature is a work in progress. Please contact us if you encounter any issues.
If you are using VS Code, we have zen-lsp plugin which should help you write configs with less errors.
VS Code plugin is in the alpha phase. Please contact us if you encounter any issues.
This tip is the same as for development.
In production you may not always have an access to a git repository with your project. It can also be convenient to bundle the project together with all its dependencies. You can use our
zen
tool to address both of these concerns.Execute the following command inside the project directory to create a zip file with your project:
java -jar path/to/ zen.jar build target zen-package
It will be available inside the
target
directory in the root of the project.Now all you need is to set
AIDBOX_ZEN_PATHS
environment variable. There are two ways to do it:# 1 — provided at remote URL
AIDBOX_ZEN_PATHS=url:package-zip:https://hostname.tld/zen-package.zip
# 2 — provided at filesystem path
AIDBOX_ZEN_PATHS=path:package-zip:path/to/zen-package.zip
It is also possible to provide an unpacked zip of your project:
AIDBOX_ZEN_PATHS=path:package-dir:path/to/unpacked-zip-content
Since configuration projects are just git repositories you can publish them in any git registry and other people will be able to use them for their own configurations: either as a standalone project or as a dependency.
If your repository is available only under a restricted access, others will need to set the appropriate environment variables so that Aidbox is able to access it.
Last modified 4mo ago