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