View Source Altworx Runbox
Runbox is a runtime environment for Altworx scenarios. It provides essential data structures, APIs, and tools for developing, testing, and packaging scenarios.
Check out also Toolbox, which builds on top of Runbox and provides conveniences and additional abstractions for writing scenarios.
Note that there are two types of documentation for Runbox. The main documentation (the one you are probably seeing now) covers all user-facing modules. This is the go-to documentation when writing scenarios. However, there is also the internal documentation that covers also internal modules. That documentation might be useful if you want to dig deeper into how scenarios run.
Scenario projects
Scenarios in Altworx are developed as Elixir/Mix projects, with a single project potentially containing multiple scenarios. When packaged, all scenarios in a project are bundled together.
To start a new scenario project, create a blank project using mix new project_name
, then add Runbox
as a dependency in your mix.exs
:
defp deps do
[
{:runbox, "~> 9.0", hex: :altworx_runbox}
]
end
Note that currently there is a limitation that scenario module names must start with the Scenario.
prefix, although the project or app itself can have any name.
Configuration
Runbox requires the :scenario_config_dir
environment variable under the :runbox app to be set.
This is automatically handled when running in Altworx but may need to be configured for the test
environment. You can use a dummy value for testing, like so in config/test.exs
:
import Config
config :runbox, scenario_config_dir: "/non-existing/does/not/matter"
Building scenario artefacts
Using Runbox, scenarios are packaged into artefacts (also called releases) that can be deployed to and run in Altworx. These artefacts include both the scenarios code and the runtime environment. To build a scenario artefact, make sure you have Docker installed and then run
mix altworx.scenario_release
You can then load the built scenario artifact in the Admin UI. Do not forget to restart Altworx afterwards.
Architectural details
Altworx runs in a single BEAM node and spawns a separate BEAM node for each scenario release. Both Altworx and the scenario nodes run the Runbox app, so Runbox also serves for communication between these two. On the Altworx node, it is responsible for starting the scenario nodes.
Scenario nodes can are used for:
- listing scenarios in a scenario release
- spawning components for a scenario "run"
- processing notification templates