Set up and use configuration projects
Aidbox Configuration project requires a few things:
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_URLenvironment 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 to
git clone <url>command.
ssh. 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
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 HTTPS
BOX_PROJECT_GIT_PUBLIC__KEY— SSH public key
BOX_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:
Aidbox starts reading configuration project from a zen entrypoint. It is a namespaced symbol which is tagged with
aidbox/systemtag. It is used to bootstrap the whole system.
You can specify an entrypoint symbol via
The entrypoint file should import all the packages and other namespaces you wish to use. Its
nsvalue should correspond to its filename (with
You need to specify
AIDBOX_ZEN_ENTRYPOINTenvironment variable. This variable is formatted as
<entrypoint namespace>/<entrypoint symbol name>. Given entry file such as above, you get the following:
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__PATHenvironment 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:
You can also use Aidbox UI to reload namespaces: proceed to
Profilespage on the left sidebar and click the reload button in the upper left corner.
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
zentool 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
targetdirectory in the root of the project.
Now all you need is to set
AIDBOX_ZEN_PATHSenvironment variable. There are two ways to do it:
# 1 — provided at remote URL
# 2 — provided at filesystem path
It is also possible to provide an unpacked zip of your project:
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.