# 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](https://hex.pm/packages/altworx_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](https://hexdocs.pm/altworx_runbox) (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](https://hexdocs.pm/altworx_runbox/internal)
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`:

```elixir
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`:

```elixir
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

```sh
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