Skip to content

Developer Guide

Getting started as a BigRAE developer.

Quick Start

  1. Local Setup - Clone, dependencies, run locally
  2. Setup - Deploy to AWS or GCP from scratch
  3. Installation Config - bigrae.yaml schema and validation
  4. CI/CD - How deployments work
  5. Secrets - What secrets exist, where they live
  6. Platform API Development - DRF endpoints, scopes, schema, and error envelopes
  7. Privacy Notice Shell - Operator-owned /privacy/ content and cookie disclosure
  8. Terraform - Infrastructure patterns
  9. Cloud Adapters - Cloud abstraction layer
  10. Principles - Engineering philosophy
  11. ADR Enforcement - Architecture guardrails and policy checks

Prerequisites

  • Python 3.12
  • Node.js LTS
  • Terraform 1.7+
  • Docker
  • Git
  • AWS: AWS CLI v2 with SSO or IAM credentials
  • GCP: gcloud CLI authenticated with target project

Cloud Access

AWS - Configure named profiles for each environment:

export PANW_SHIFTER_DEV_PROFILE="your-dev-profile-name"
export PANW_SHIFTER_PROD_PROFILE="your-prod-profile-name"

GCP - Authenticate with gcloud auth login and set the target project.

Repository Structure

shifter/
├── shifter/
│   ├── shifter_platform/       # Django web application
│   │   ├── mission_control/    # Main app (ranges, agents, terminal)
│   │   ├── cms/                # Content management (agents, scenarios)
│   │   ├── engine/             # Orchestration services
│   │   ├── documentation/      # In-app docs (you're reading this)
│   │   └── config/             # Django settings
│   └── engine/                 # Range provisioner
│       └── provisioner/        # Cloud-specific provisioning (AWS EC2, GDC VMs/pods)
├── platform/
│   ├── terraform/
│   │   ├── environments/       # AWS env configs (dev/, prod/)
│   │   ├── modules/            # AWS Terraform modules
│   │   ├── global/             # Cross-environment resources (IAM, OIDC, runners)
│   │   └── gcp/               # GCP Terraform (modules/, environments/)
│   ├── charts/shifter/        # Helm chart for the GCP control plane
│   └── deployer/gcp/          # GCP deployer image
├── scripts/                    # Bootstrap and utility scripts
├── shifter/installation/        # bigrae.yaml parser, validator, backend registry
└── .github/workflows/          # CI/CD pipelines (AWS + GCP)

Git Workflow

feature/* ──► dev ──► aws-dev ──► main ──workflow_dispatch──► prod env
              │        │
              │        ▼
              └──────► gcp-dev
                       │
                       ▼
                    gcp dev env
  • feature/* - Development work
  • dev - Integration, validation only
  • aws-dev - AWS dev deployment branch
  • gcp-dev - GCP dev deployment branch
  • main - Production code branch; prod deploys require manual dispatch

All changes go through pull requests. Never commit directly to deploy branches.

Next Steps

Start with Local Setup to get the portal running on your machine.