Setup Wizard

Version: 0.1.0

The setup wizard (terraform/setup.sh) is an interactive script that provisions cloud infrastructure and deploys DecisionBox in one flow. It handles Terraform configuration, cloud authentication, Kubernetes setup, and Helm deployment.

Quick Start

cd terraform
./setup.sh

Flags

Flag	Description
--help	Show usage guide and exit
--dry-run	Generate config files (tfvars + Helm values) without applying
--resume	Resume from Helm deploy — skips Terraform, reloads config from existing terraform.tfvars
--destroy	Tear down everything — Helm releases, K8s namespace, Terraform resources

9-Step Flow

Step 1: Prerequisites

Verifies all required tools are installed with version info:

• terraform (1.5+)
• gcloud (for GCP) or aws (for AWS)
• kubectl
• helm (3.7+)
• openssl

If any tool is missing, the wizard shows an install link and exits.

Step 2: Cloud Provider

Select your cloud provider:

• GCP — Google Cloud Platform
• AWS — Amazon Web Services

Step 3: Secrets Configuration

Configure the secret namespace prefix used to scope secrets. Format: {namespace}-{projectID}-{key}.

Choose between:

• Cloud Secret Manager (GCP Secret Manager or AWS Secrets Manager) — recommended for production
• MongoDB encrypted secrets — uses AES-256 encryption with SECRET_ENCRYPTION_KEY

Step 4: Cloud Provider Settings

GCP:

• Project ID (validated against GCP naming rules)
• Region (default: us-central1)
• GKE cluster name (default: decisionbox-prod)
• Kubernetes namespace (default: decisionbox)
• Node pool: machine type, min/max nodes per zone (numeric validation, min <= max check)
• BigQuery IAM (optional — for data warehouse access)
• Vertex AI IAM (optional — for Claude via Vertex or Gemini)

AWS:

• Region (default: us-east-1)
• EKS cluster name (default: decisionbox-prod)
• Kubernetes namespace (default: decisionbox)
• Node group: instance type, min/max/desired nodes (numeric validation)
• Redshift IAM (optional)

Step 5: Authentication

GCP — choose how Terraform authenticates:

• User credentials (ADC): If ADC already exists and is a user credential, offers to reuse. Otherwise prompts for interactive login with --no-browser mode.
• Service account key file: Provide a JSON key file path. Sets GOOGLE_APPLICATION_CREDENTIALS.
• Verifies 4 GCP permissions: GKE, Storage, IAM, Compute.

AWS — choose how Terraform authenticates:

• AWS CLI profile: Use an existing profile (default or named).
• Environment variables: Set AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY.
• Verifies identity via aws sts get-caller-identity.

Step 6: Terraform State

GCP: Configure a GCS bucket for remote state:

• Bucket name (default: {project-id}-terraform-state)
• State prefix / environment name (default: prod)
• Auto-creates the bucket with versioning if it doesn't exist

AWS: Configure an S3 bucket for remote state with native locking:

• S3 bucket name (default: {account-id}-terraform-state)
• State key (default: prod/terraform.tfstate)
• Auto-creates the bucket with versioning if it doesn't exist
• Uses S3-native locking (use_lockfile=true, Terraform 1.10+)

Step 7: Review

Displays all collected configuration for review before proceeding. Type back to change any value.

Step 8: Generate Config Files

Generates two files:

terraform/gcp/prod/terraform.tfvars — Terraform variables:

project_id   = "my-project"
region       = "us-central1"
cluster_name = "decisionbox-prod"
machine_type = "e2-standard-2"
min_node_count = 1
max_node_count = 2
k8s_namespace = "decisionbox"
enable_gcp_secrets  = true
secret_namespace    = "decisionbox"
enable_bigquery_iam  = false
enable_vertex_ai_iam = false

helm-charts/decisionbox-api/values-secrets.yaml — Helm values:

When cloud secrets are enabled:

serviceAccountAnnotations:
  iam.gke.io/gcp-service-account: "cluster-api@project.iam.gserviceaccount.com"
env:
  SECRET_PROVIDER: "gcp"
  SECRET_GCP_PROJECT_ID: "my-project"

When using MongoDB secrets:

env:
  SECRET_PROVIDER: "mongodb"

Step 9: Terraform & Deploy

1. Terraform init — initializes with remote backend (spinner + elapsed time)
2. Terraform plan — shows changes, prompts for approval
3. Terraform apply — provisions infrastructure (shows elapsed time)
4. kubectl credentials — configures cluster access
5. Helm deploy — deploys API + Dashboard with dependency build
6. Ingress wait — waits for IP assignment, health checks, and HTTP 200
7. Completion — shows dashboard URL and total elapsed time

Navigation

Type back at any prompt to return to the previous step. The (back) hint is shown on every prompt. Steps 2-7 support back navigation. Steps 8-9 are sequential.

Resume Mode

If the Helm deployment fails (e.g., missing chart dependencies, image pull errors), use --resume to retry without re-running Terraform:

./setup.sh --resume

Resume mode:

1. Reads config from existing terraform.tfvars (auto-detects GCP or AWS)
2. Validates the cluster is reachable
3. Checks if Helm releases already exist (asks before re-deploying)
4. Automatically adds Bitnami Helm repo if missing
5. Runs helm dependency build before deploying
6. On failure, suggests ./setup.sh --resume again

Dry Run

Generate config files without applying any changes:

./setup.sh --dry-run

Shows the manual commands to apply afterwards.

Destroy

Tear down all infrastructure:

./setup.sh --destroy

Destroy mode:

1. Reads config from existing terraform.tfvars (auto-detects GCP or AWS)
2. Requires typing destroy to confirm (safety check)
3. Uninstalls Helm releases (dashboard, API)
4. Deletes the Kubernetes namespace
5. Disables deletion protection (GCP only — GKE requires this before destroy)
6. Runs terraform destroy to remove all cloud resources
7. Leaves the state bucket intact (contains state history)

Terminal Features

• Animated spinner with elapsed time for all long operations
• Color output (auto-disabled for non-TTY / piped output)
• Graceful cancel — Ctrl+C cleans up tfplan and stops spinners
• Input validation — numeric checks, boolean checks, choice validation
• Permission verification — checks GCP IAM or AWS identity before proceeding
• ADC type detection — warns if GCP Application Default Credentials use a service account instead of user credentials

Generated Files

File	Gitignored	Purpose
terraform/{gcp,aws}/prod/terraform.tfvars	Yes	Terraform input variables
helm-charts/decisionbox-api/values-secrets.yaml	Yes	Helm values with secret provider config

Both files are gitignored to prevent committing environment-specific values.

Next Steps

• Terraform GCP — GKE module variables and details
• Terraform AWS — EKS module variables and details
• Kubernetes (Helm) — Manual Helm deployment guide
• Production Considerations — Scaling, monitoring, backups