Getting Started

Getting Started

Before you begin

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

• Terraform installed, to apply the export.
• The AWS CLI or the gcloud CLI installed, for whichever cloud you target.
• A cloud account with credentials and billing set up, GCP or AWS (see Providers for GCP's project and API setup). 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 and gcloud 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                    # builds from the repo, http://127.0.0.1:8000

Or pull the published image:

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

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:

redstackpro serve                    # http://127.0.0.1:8000
cd frontend && npm install && npm run dev

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            # bash / Git Bash

$env:REDSTACKPRO_API="http://127.0.0.1:8787"      # PowerShell

Your first topology

1. Open the canvas and click Load blueprint to open a shipped starting point (for example goad-light).
2. Choose your cloud in the toolbar provider selector (GCP or AWS).
3. Edit it if you want. A shipped lab opens read-only so the baseline is safe. See Library and Templates 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.
5. Press Download. You get a zip of a complete working directory.

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

What the export contains

A complete working directory you unzip and run:

• 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
• 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

See Deploying a Range for the deploy flow.