Run ProSA

Once you have created a binary using cargo-prosa, the next step is to run this binary.

If you’ve installed a package or a container, you don’t need to worry about the inner workings. However, if you want to execute the binary manually, this section explains the available parameters.

Command-Line Options

When you run prosa_binary -h, you’ll see output like the following:

Usage: prosa_binary [OPTIONS]

Options:
      --dry_run                   Show how the ProSA will run but doesn't start it. Write the config file if it doesn't exist
  -c, --config <CONFIG_PATH>      Path of the ProSA configuration file [default: prosa.yml]
  -n, --name <NAME>               Name of the ProSA
  -t, --worker_threads <THREADS>  Number of worker threads to use for the main [default: 1]
  -h, --help                      Print help
  -V, --version                   Print version

Dry Run

Use --dry_run to validate your configuration without actually starting ProSA:

prosa_binary -c config.yaml --dry_run

This will:

1. Parse and validate your configuration file
2. If the configuration file does not exist, write a default one with all your processors’ default settings
3. Display how ProSA would run (which processors, which adaptors)
4. Exit without starting any processor

This is particularly useful for:

• Generating a starter configuration file for a new ProSA instance
• Validating configuration changes before applying them in production

Configuration Path

The -c / --config option accepts either a single file or a directory:

# Single configuration file
prosa_binary -c /etc/prosa.yml

# Directory containing multiple configuration files
prosa_binary -c /etc/myprosa/

When pointing to a directory, both YAML/TOML files in that directory are merged together. This lets you split configuration across multiple files (e.g., one for observability, one per processor). See the Configuration chapter for details.

Environment Variables

Configuration values can also be set through environment variables. For example:

PROSA_NAME="my-prosa" prosa_binary -c config.yaml

This is useful in containerized environments where configuration is injected via environment variables.

Version Information

The -V flag provides a short version, while --version shows detailed component information:

$ prosa_binary -V
prosa 0.1.0

$ prosa_binary --version
prosa 0.1.0 - core::main::MainProc = { crate = prosa, version = 0.2.0 }
  inj
    Processor: inj::proc::InjProc = { crate = prosa, version = 0.2.0 }
    Adaptor  : inj::adaptor::InjDummyAdaptor = { crate = prosa, version = 0.2.0 }
  stub
    Processor: stub::proc::StubProc = { crate = prosa, version = 0.2.0 }
    Adaptor  : stub::adaptor::StubParotAdaptor = { crate = prosa, version = 0.2.0 }

The verbose output shows:

• The Main processor type and its crate/version
• Each Processor instance with its name, type, crate, and version
• Each Adaptor associated with its processor

This is valuable for debugging version mismatches or verifying that the correct components are compiled in.

Worker Threads

The -t / --worker_threads option controls the number of threads for the Main task’s Tokio runtime (default: 1).

Note that each processor runs in its own thread(s) independently — see Threads for details on per-processor thread configuration.

Graceful Shutdown

ProSA handles Ctrl+C (SIGINT) for graceful shutdown:

1. The Main processor receives the signal
2. A Shutdown message is sent to every registered processor
3. Each processor calls adaptor.terminate() to clean up resources
4. Each processor deregisters from the Main bus
5. The Main processor exits once all processors have stopped

This ensures that in-flight transactions are not abruptly terminated and that resources (connections, files, etc.) are properly released.