Getting Started

Getting Started

Before you begin

These are separate from redStackPRO itself; redStackPRO only generates the files that need them.

• Terraform 1.5 or newer installed, to apply the export.
• Python 3.8 or newer, ssh, and tar on the machine you deploy from. macOS and Linux ship ssh and tar; on Windows, Git for Windows supplies them and Git Bash. Install a real Python, not the Microsoft Store stub.
• The AWS CLI, the gcloud CLI, or the Azure CLI installed, for whichever cloud you target. On Windows, winget installs each; the Export panel gives the command.
• A cloud account with credentials and billing set up, GCP, AWS, or Azure (see Providers for GCP's project and API setup, and Azure's subscription and resource providers). You will authenticate to it when you deploy; see Deploying a Range.

For the permissions your cloud identity needs, the exact local tools, and AWS CLI, gcloud, and Azure CLI auth quick-starts, see Cloud Prerequisites.

The canvas itself only needs Docker, or Python and Node, below.

Run with Docker

The whole canvas in one container, the API and the web app on one port:

docker compose up                    # runs the pinned 0.10.0 image, http://127.0.0.1:8000
docker compose up --build            # build the image from this checkout instead

Or pull the published image:

docker run -p 8000:8000 -v redstackpro-data:/data ghcr.io/devzero-security/redstackpro:latest

The canvas listens on 8000 inside the container. To serve it on a different host port, change the left half of the mapping (-p 8787:8000), or set REDSTACKPRO_PORT for compose:

REDSTACKPRO_PORT=8787 docker compose up           # bash / Git Bash

$env:REDSTACKPRO_PORT=8787; docker compose up     # PowerShell

The image is the composition layer only. It carries no Terraform, Ansible, or cloud SDK, and never holds your credentials. You run the export it produces yourself.

For a shared deployment, Compose has an optional Postgres backend:

REDSTACKPRO_DATABASE_URL=postgresql+psycopg://redstackpro:redstackpro@db:5432/redstackpro \
  docker compose --profile postgres up

PowerShell:

$env:REDSTACKPRO_DATABASE_URL="postgresql+psycopg://redstackpro:redstackpro@db:5432/redstackpro"
docker compose --profile postgres up

Run from source

Python 3.11 or newer, and Node 24 for the canvas.

git clone https://github.com/devZero-Security/redStackPRO.git
cd redStackPRO
python -m venv .venv
. .venv/bin/activate            # bash (Linux / macOS)
.venv\Scripts\Activate.ps1      # PowerShell (Windows)
pip install -e ".[dev]"

The canvas is two processes, the API and the web app. Start the API:

redstackpro serve                    # the API, http://127.0.0.1:8000

It keeps that terminal busy. In a second terminal, from the repo root:

cd frontend
npm install
npm run dev                          # the canvas, http://localhost:5173

Open the canvas at http://localhost:5173. Port 8000 serves the canvas only after a npm run build in frontend/.

redstackpro serve --port 8787 moves the API to a different port. Point the canvas dev server at it:

REDSTACKPRO_API=http://127.0.0.1:8787 npm run dev                # bash / Git Bash, in frontend/

$env:REDSTACKPRO_API = 'http://127.0.0.1:8787'; npm run dev      # PowerShell, in frontend/

Your first topology

1. Open the canvas, pick Defense in the mode switch at the top, and click Load blueprint. Choose GOAD-Light (or, in Offense, a stack such as redStack).
2. Choose your cloud in the toolbar provider selector (GCP, AWS, or Azure).
3. Edit it if you want. A shipped lab opens read-only so the baseline is safe. See Library and Blueprints for what loading, saving, and publishing each do.
4. Open the Export tab. The canvas compiles as you go, validating first and listing any findings. Set Deploy from to the system you will deploy from (Windows, or macOS / Linux).
5. Press Download (the button names the deploy target). You get a zip of a complete working directory.
6. Follow the steps the Export panel lists: extract the zip to its own folder and run every step from there, make the SSH key, set the deploy.tfvars fields it names for your provider, install the cloud CLI (on Windows, the winget command it gives; on macOS and Linux, a link to its install steps) and log in, then run the deploy. DEPLOYMENT-GUIDE.md in the export has the long version, and Deploying a Range covers each step.

Skip the canvas

From a source checkout (see Run from source), compile a shipped blueprint from the command line with the same compiler:

redstackpro compile frontend/public/goad/goad-light.json -o export

The command line defaults to GCP. Pass --provider aws or --provider azure for the other clouds, and --hostname <your domain> for a blueprint with a redirector. -o replaces the folder it writes to, but refuses one that holds terraform/terraform.tfstate or a key in keys/, so a recompile cannot delete a deployed range's state and key: pick a new folder, or pass --force to replace it anyway.

What the export contains

A complete working directory you extract to its own folder and run from there:

• DEPLOYMENT-GUIDE.md at the export root: the step-by-step deploy guide for this export. Open it first.
• Terraform for the cloud (a root module and modules/)
• Ansible for everything that happens on the hosts
• deploy.tfvars at the export root: the one file you edit before deploying. deploy.sh copies it into terraform/terraform.tfvars at apply time.
• deploy.sh (and deploy.ps1 for Windows PowerShell) to apply and provision
• manage.sh (and manage.ps1) with status, start, stop, and teardown to check on, pause, resume, and tear down the range; run it with no command for its help screen
• a mode-named briefing (DEFENSE-BRIEFING.md for a defense range, OFFENSE-BRIEFING.md for attack infrastructure) with the credentials and what is planted where
• verify.py, to check the deployed range: python verify.py stack . (the range over SSH from the jumpbox) and, on attack infrastructure, python verify.py doors . (the redirector front doors, from outside). It needs PyYAML (python -m pip install pyyaml). Use python3 in place of python on macOS and Linux; Deploying a Range covers a pip that refuses the install.

See Deploying a Range for the deploy flow.