# fallout

**Repository Path**: mirrors_datastax/fallout

## Basic Information

- **Project Name**: fallout
- **Description**: Distributed System Testing as a Service
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2020-08-08
- **Last Updated**: 2025-12-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Fallout

Fallout is a tool for running local or large scale remote based distributed correctness, verification and performance tests. Fallout is run in production at DataStax facilitating mission critical testing of Apache Cassandra™, Apache Pulsar™, and many other products.

This repository contains the core framework and components of fallout: you can use it to run performance tests on Google Kubernetes Engine.  At DataStax, we have an internal version that builds on this code and integrates with our internal infrastructure.

Below are some resources covering Fallout's architecture and design (best consumed in order, shortest to longest):
- [Overview Video](https://www.youtube.com/watch?v=eSz8ypKQWp8) - Covers Fallout's history, architecture, CI usage, & learnings. This video is a summary of;
- [Fallout: Distributed Systems Testing as a Service](https://arxiv.org/abs/2110.05543) - Paper submitted to 2021 BenchCouncil International Symposium on Benchmarking, Measuring and Optimizing (Bench'21).
- [Recorded Workshop](https://www.youtube.com/watch?v=45iTmTBjU0M) - Covers the project's intent, architecture, and simple examples.

## Getting Started

The easiest way to get started is to use the [published docker image](https://hub.docker.com/r/datastax/fallout) (which bundles all the support tools with Fallout), and the `fallout exec` command which runs a single test definition:

```
$ docker run datastax/fallout:latest fallout exec --help
usage: java -jar fallout-0.1.0-SNAPSHOT-all.jar
       exec [--params TEMPLATE-PARAMS-YAML-FILE]
       [--use-unique-output-dir] [--config FILE] [-h] test-yaml-file
       creds-yaml-file output-dir [template-params [template-params ...]]

Run a single testrun in a standalone fallout process and exit

positional arguments:
  test-yaml-file         Test definition YAML file
  creds-yaml-file        Credentials YAML file
  output-dir             Where to write  testrun  artifacts;  it's an error
                         if the directory isn't empty
  template-params        Template params  for  test-yaml-file  in  the form
                         param=value

named arguments:
  --params TEMPLATE-PARAMS-YAML-FILE
                         Template parameters YAML file
  --use-unique-output-dir
                         Write     testrun     artifacts     to     output-
                         dir/TEST_NAME/TESTRUN_ID instead of  directly into
                         output-dir (default: false)
  --config FILE          Application configuration file
  -h, --help             show this help message and exit
```

For an example, see the Pulsar tests at https://github.com/datastax/pulsar-fallout.

## Running a Server

Fallout can be run as a multi-user service (that's how we deploy it at DataStax).  Before describing how to do this, one important caveat: **please do not run Fallout as a service on the public internet**.  In its current form, it is not secure.

You can use `docker compose` to run [`docker-compose.yml`](docker/docker-compose.yml).  When starting for the first time you'll want to create a default admin user; you can do this by setting the `FALLOUT_ADMIN_CREDS` environment variable to `<USERNAME>:<EMAIL>:<PASSWORD>` on the very first start-up:

```
FALLOUT_ADMIN_CREDS=admin:admin@fallout.example.com:admin \
  docker compose --file fallout-oss/docker/docker-compose.yml up
```

...and connect to http://localhost:8080.

The `docker-compose.yml` defines two volumes to persist the Fallout artifacts and cassandra data, so the next time you start, the data will still be there; also you won't need the `FALLOUT_ADMIN_CREDS`:

```
docker compose --file fallout-oss/docker/docker-compose.yml up
```

### Single-user Mode

If you set the environment variable `FALLOUT_AUTH_MODE` to `SINGLE_USER`, then fallout will automatically log you in as the user defined in `FALLOUT_ADMIN_CREDS` above.  In this case, you have to specify both environment variables every time you start:

```
FALLOUT_AUTH_MODE=SINGLE_USER \
FALLOUT_ADMIN_CREDS=admin:admin@fallout.example.com:admin \
  docker compose --file fallout-oss/docker/docker-compose.yml up
```


## The Future

We intend to move more functionality into this, the core repository, as time goes on.  There will be better documentation, and more examples.

## Building, Contributing and Issues

See [BUILDING.md](BUILDING.md) for how to build and run the project.

Contributions are welcome, please see [CONTRIBUTING](CONTRIBUTING.md) for guidance.

If you encounter any bugs, please file a GitHub issue.