feat: add LocalStack-based local infrastructure automation and documentation

.gitignore

@@ -11,6 +11,7 @@ __pycache__
 !.env.e2e
 !.env.e2e-tests
 !.env.fuzz-tests
+!.env.localstack.example
 !.env.unit-tests
 .github/instructions/snyk_rules.instructions.md
 .idea

backend/.env.localstack.example

@@ -0,0 +1,30 @@
+# Backend environment variables for LocalStack provisioning.
+#
+# Copy this file to backend/.env.localstack and fill in your values.
+# make load-env-params reads .env.localstack (not .env) to avoid
+# overwriting Terraform-managed SSM parameters (DB, Redis, secrets).
+#
+# Excluded intentionally (set by Terraform or overridden by deploy-services.sh):
+#   DJANGO_DB_HOST, DJANGO_DB_NAME, DJANGO_DB_PORT, DJANGO_DB_USER,
+#   DJANGO_DB_PASSWORD, DJANGO_REDIS_HOST, DJANGO_REDIS_PORT,
+#   DJANGO_REDIS_PASSWORD, POSTGRES_*
+
+DJANGO_ALGOLIA_APPLICATION_ID=
+DJANGO_ALGOLIA_EXCLUDED_LOCAL_INDEX_NAMES=
+DJANGO_ALGOLIA_WRITE_API_KEY=
+DJANGO_CONFIGURATION=Local
+DJANGO_ELEVENLABS_API_KEY=your-elevenlabs-api-key
+DJANGO_GITHUB_APP_ID=your-github-app-id
+DJANGO_GITHUB_APP_INSTALLATION_ID=your-github-app-installation-id
+DJANGO_OPEN_AI_SECRET_KEY=your-open-ai-secret-key
+DJANGO_PUBLIC_IP_ADDRESS=127.0.0.1
+DJANGO_REDIS_AUTH_ENABLED=True
+DJANGO_RELEASE_VERSION=local
+DJANGO_SECRET_KEY=
+DJANGO_SENTRY_DSN=your-sentry-dsn
+DJANGO_SLACK_BOT_TOKEN=
+DJANGO_SLACK_CLIENT_ID=
+DJANGO_SLACK_CLIENT_SECRET=
+DJANGO_SLACK_SEARCH_TOKEN=
+DJANGO_SLACK_SIGNING_SECRET=
+GITHUB_TOKEN=your-github-token

backend/src/settings/base.py

@@ -143,6 +143,7 @@ class Base(Configuration):
     NINJA_PAGINATION_PER_PAGE = API_PAGE_SIZE
 
     REDIS_HOST = values.SecretValue(environ_name="REDIS_HOST")
+    REDIS_PORT = values.IntegerValue(environ_name="REDIS_PORT", default=6379)
     REDIS_PASSWORD = values.SecretValue(environ_name="REDIS_PASSWORD")
     REDIS_AUTH_ENABLED = values.BooleanValue(environ_name="REDIS_AUTH_ENABLED", default=True)
     REDIS_USE_TLS = values.BooleanValue(environ_name="REDIS_USE_TLS", default=False)
@@ -159,7 +160,7 @@ class Base(Configuration):
     CACHES = {
         "default": {
             "BACKEND": "django_redis.cache.RedisCache",
-            "LOCATION": f"{'rediss' if REDIS_USE_TLS else 'redis'}://{REDIS_HOST}:6379",
+            "LOCATION": f"{'rediss' if REDIS_USE_TLS else 'redis'}://{REDIS_HOST}:{REDIS_PORT}",
             "OPTIONS": REDIS_CACHE_OPTIONS,
             "TIMEOUT": 300,
         }
@@ -168,7 +169,7 @@ class Base(Configuration):
     RQ_QUEUES = {
         "ai": {
             "HOST": REDIS_HOST,
-            "PORT": 6379,
+            "PORT": REDIS_PORT,
             "PASSWORD": REDIS_PASSWORD,
             "DB": 1,
             "DEFAULT_TIMEOUT": 300,

backend/src/settings/local.py

@@ -3,16 +3,20 @@
 from configurations import values
 
 from settings.base import Base
+from settings.values import OptionalSecretValue
 
 
 class Local(Base):
     """Local configuration."""
 
     APP_NAME = "OWASP Nest Local"
 
-    ALLOWED_ORIGINS = (
-        "http://127.0.0.1:3000",
-        "http://localhost:3000",
+    ALLOWED_ORIGINS = values.ListValue(
+        environ_name="ALLOWED_ORIGINS",
+        default=[
+            "http://127.0.0.1:3000",
+            "http://localhost:3000",
+        ],
     )
     CORS_ALLOWED_ORIGINS = ALLOWED_ORIGINS
     CSRF_TRUSTED_ORIGINS = ALLOWED_ORIGINS
@@ -30,5 +34,7 @@ class Local(Base):
     SECURE_SSL_REDIRECT = False
     SESSION_COOKIE_SECURE = False
 
-    SLACK_COMMANDS_ENABLED = True
-    SLACK_EVENTS_ENABLED = True
+    SLACK_BOT_TOKEN = OptionalSecretValue(environ=False)
+    SLACK_COMMANDS_ENABLED = False
+    SLACK_EVENTS_ENABLED = False
+    SLACK_SIGNING_SECRET = OptionalSecretValue(environ=False)

cspell/custom-dict.txt

@@ -88,6 +88,7 @@ acodec
 agentic
 ahmedxgouda
 algoliasearch
+alse
 ansa
 apexcharts
 apk
@@ -121,6 +122,7 @@ dkr
 dsn
 dvo
 eddsa
+elbv
 elevenlabs
 env
 envsubst
@@ -241,6 +243,7 @@ subgrp
 superfences
 tfbackend
 tfdata
+tflocal
 tftest
 tgz
 tiktok

docker/localstack/Dockerfile

@@ -1 +1 @@
-FROM localstack/localstack:2026.6.3@sha256:49d8f376123085bb7ee1b342c26dbb7beb48ba5fd7b45fc86952aecdf08c6ae2
+FROM localstack/localstack:2026.07.1@sha256:58ac6d29304e2e472320d4279d287c3f40103d081234559a852b65db2da1e3d4

frontend/.env.localstack.example

@@ -0,0 +1,27 @@
+# Frontend environment variables for LocalStack provisioning.
+#
+# Copy this file to frontend/.env.localstack and fill in your values.
+# make load-env-params reads .env.localstack (not .env) to avoid
+# overwriting Terraform-managed SSM parameters (ALB URLs, secrets).
+#
+# NEXT_PUBLIC_* use relative URLs so the Docker image works behind the
+# ALB — the browser resolves them against the current origin.
+#
+# Excluded intentionally (set by Terraform, derived from ALB DNS name):
+#   NEXTAUTH_URL, NEXT_SERVER_CSRF_URL, NEXT_SERVER_GRAPHQL_URL
+
+NEXTAUTH_SECRET=
+NEXT_PUBLIC_API_URL=/
+NEXT_PUBLIC_CSRF_URL=/csrf/
+NEXT_PUBLIC_ENVIRONMENT=local
+NEXT_PUBLIC_GRAPHQL_URL=/graphql/
+NEXT_PUBLIC_GTM_ID=
+NEXT_PUBLIC_IDX_URL=/idx/
+NEXT_PUBLIC_IS_PROJECT_HEALTH_ENABLED=true
+NEXT_PUBLIC_POSTHOG_HOST=https://us.i.posthog.com
+NEXT_PUBLIC_POSTHOG_KEY=
+NEXT_PUBLIC_RELEASE_VERSION=
+NEXT_PUBLIC_SENTRY_DSN=
+NEXT_SERVER_DISABLE_SSR=false
+NEXT_SERVER_GITHUB_CLIENT_ID=your-github-client-id
+NEXT_SERVER_GITHUB_CLIENT_SECRET=your-github-client-secret

infrastructure/.env.example

@@ -0,0 +1 @@
+LOCALSTACK_AUTH_TOKEN=

infrastructure/Makefile

@@ -1,5 +1,6 @@
 ##@ Infrastructure
 
+include infrastructure/make/localstack.mk
 include infrastructure/make/maintenance.mk
 include infrastructure/make/security.mk
 include infrastructure/make/test.mk

infrastructure/README.md

@@ -7,9 +7,16 @@ This document provides instructions on how to setup the infrastructure for this
 Ensure you have the following setup/installed:
 
 - Setup Project: [CONTRIBUTING.md](https://github.com/OWASP/Nest/blob/main/CONTRIBUTING.md)
+- jq: [jq](https://jqlang.github.io/jq/)
+- OpenSSL: [OpenSSL](https://www.openssl.org/)
 - Terraform: [Terraform Documentation](https://developer.hashicorp.com/terraform/docs)
 - AWS CLI: [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html)
+- Docker: [Docker](https://docs.docker.com/engine/install/)
+- LocalStack CLI: [LocalStack CLI](https://www.localstack.cloud/aws/getting-started/installation/)
+- AWSLocal CLI: [AWSLocal CLI](https://github.com/localstack/awscli-local)
+- Terraform Local CLI: [Terraform Local CLI](https://github.com/localstack/terraform-local)
 - An AWS account.
+
 Note: Refer to the respective `README.md` files for more information.
 
 ## External Documentation
@@ -164,6 +171,108 @@ To do this locally:
 - Visit the AWS Console > Systems Manager > Parameter Store.
 - Populate all `DJANGO_*` secrets that have `to-be-set-in-aws-console` value.
 
+## Local Development with LocalStack
+
+These steps provision the entire infrastructure, build and push Docker images, and run ECS tasks locally using [LocalStack](https://www.localstack.cloud/).
+
+> [!NOTE]
+> All commands below are run from the project root.
+
+### Prerequisites
+
+- Docker
+- LocalStack Pro (requires `LOCALSTACK_AUTH_TOKEN`)
+- `jq`, `openssl` (usually pre-installed)
+- `awslocal`, `tflocal` (see [Prerequisites](#prerequisites) above)
+
+### 1. Create environment file
+
+Create `infrastructure/.env`:
+
+```bash
+LOCALSTACK_AUTH_TOKEN=<your-pro-token>
+```
+
+Optionally set environment variables for the provisioning script:
+
+```bash
+# infrastructure/.env or export these
+ENVIRONMENT=local
+DOMAIN_NAME=localhost
+DJANGO_CONFIGURATION=Local
+DJANGO_SETTINGS_MODULE=settings.local
+FORCE_NEW_DEPLOYMENT=true
+```
+
+### 2. Start LocalStack
+
+```bash
+make start-localstack
+```
+
+Wait for LocalStack to be ready (health check at `http://localhost.localstack.cloud:4566/_localstack/health`).
+
+### 3. Provision everything
+
+Builds and pushes Docker images, runs Terraform via `tflocal`, uploads SSM parameters, and deploys ECS services:
+
+```bash
+make deploy-on-localstack
+```
+
+> [!NOTE]
+> If you want to recreate every resource, restart LocalStack and then rerun this script
+
+This single command:
+
+- Runs Terraform (VPC, subnets, security groups, ALB, ECS clusters/services, ECR repos, RDS, ElastiCache, ACM cert, S3 buckets, SSM params). The ECS services are created with `desired_count = 0` so no task fires before its image is pushed
+- Builds the backend Docker image and pushes it to the local ECR
+- Builds the frontend Docker image (with env vars resolved against the ALB DNS name) and pushes it to the local ECR
+- Uploads local `backend/.env.localstack` and `frontend/.env.localstack` variables to the LocalStack SSM Parameter Store
+- Overwrites the SSM runtime parameters with the real LocalStack host/ports, then scales the backend and frontend ECS services up so their tasks start with the corrected SSM values; LocalStack registers each task with the ALB target groups once RUNNING
+- Waits for both target groups to report healthy
+
+> [!NOTE]
+> **Redis overrides for LocalStack compatibility:**
+> LocalStack's ElastiCache mock ignores the configured Redis port and assigns a random one from its internal port range. The Terraform variable `django_redis_port` creates the SSM parameter as a placeholder, but the deploy step discovers the actual port at runtime via `awslocal elasticache describe-replication-groups` and overwrites the SSM value.
+>
+> Similarly, `DJANGO_REDIS_HOST` is overwritten with the LocalStack container's bridge IP — the default `localhost.localstack.cloud` resolves to loopback inside ECS containers and would be unreachable.
+
+### 4. Run database tasks
+
+Run ECS tasks (migrate, load data, index data) against the local cluster. Wait for each to finish before starting the next.
+
+```bash
+make ecs-migrate
+make ecs-load-data   # ensure backend/data/nest.dump exists first
+make ecs-index-data
+```
+
+To run any other task definition (e.g. `nest-local-sync-data`):
+
+```bash
+make ecs-task TASK=sync-data
+```
+
+> [!NOTE]
+> Task definition names follow the pattern `nest-{environment}-{task-name}`.
+
+### 5. Clean up
+
+To tear down all LocalStack resources:
+
+```bash
+cd infrastructure/live
+tflocal destroy -auto-approve
+```
+
+To wipe everything (including images) and start fresh, restart LocalStack
+
+```bash
+# Stop LocalStack (Ctrl+C), then:
+make start-localstack
+```
+
 ## Populate ECR Repositories
 
 ECR Repositories are used to store images used by ECS (Frontend + Backend + Scheduled Tasks)

infrastructure/live/README.md

@@ -95,6 +95,9 @@ No resources.
 | <a name="input_db_storage_type"></a> [db\_storage\_type](#input\_db\_storage\_type) | The storage type for the RDS database. | `string` | `"gp3"` | no |
 | <a name="input_db_user"></a> [db\_user](#input\_db\_user) | The username for the RDS database. | `string` | `"nest_db_user"` | no |
 | <a name="input_django_configuration"></a> [django\_configuration](#input\_django\_configuration) | The name of the Django configuration to use (e.g., Staging, Production). | `string` | n/a | yes |
+| <a name="input_django_redis_auth_enabled"></a> [django\_redis\_auth\_enabled](#input\_django\_redis\_auth\_enabled) | Whether Redis authentication is enabled. | `bool` | `true` | no |
+| <a name="input_django_redis_port"></a> [django\_redis\_port](#input\_django\_redis\_port) | The port of the Redis cache. | `string` | `"6379"` | no |
+| <a name="input_django_redis_use_tls"></a> [django\_redis\_use\_tls](#input\_django\_redis\_use\_tls) | Whether Redis connections should use TLS. | `bool` | `true` | no |
 | <a name="input_django_release_version"></a> [django\_release\_version](#input\_django\_release\_version) | The Django release version. | `string` | `"0.0.0"` | no |
 | <a name="input_django_settings_module"></a> [django\_settings\_module](#input\_django\_settings\_module) | The location of the Django settings module to use (e.g., settings.staging, settings.production). | `string` | n/a | yes |
 | <a name="input_domain_name"></a> [domain\_name](#input\_domain\_name) | The domain name for the site. | `string` | n/a | yes |
@@ -110,6 +113,7 @@ No resources.
 | <a name="input_enable_vpc_ssm_endpoint"></a> [enable\_vpc\_ssm\_endpoint](#input\_enable\_vpc\_ssm\_endpoint) | Whether to create SSM VPC endpoint. | `bool` | `false` | no |
 | <a name="input_environment"></a> [environment](#input\_environment) | The environment (e.g., staging, production). | `string` | n/a | yes |
 | <a name="input_fixtures_bucket_name"></a> [fixtures\_bucket\_name](#input\_fixtures\_bucket\_name) | The name of the S3 bucket for fixtures. | `string` | `null` | no |
+| <a name="input_force_new_deployment"></a> [force\_new\_deployment](#input\_force\_new\_deployment) | Whether to force a new deployment on each apply. | `bool` | `false` | no |
 | <a name="input_frontend_desired_count"></a> [frontend\_desired\_count](#input\_frontend\_desired\_count) | The desired number of frontend tasks. | `number` | `1` | no |
 | <a name="input_frontend_enable_auto_scaling"></a> [frontend\_enable\_auto\_scaling](#input\_frontend\_enable\_auto\_scaling) | Whether to enable auto scaling for frontend. | `bool` | `false` | no |
 | <a name="input_frontend_image_tag"></a> [frontend\_image\_tag](#input\_frontend\_image\_tag) | The Docker frontend image tag. | `string` | n/a | yes |
@@ -138,10 +142,12 @@ No resources.
 | <a name="output_backend_cluster_name"></a> [backend\_cluster\_name](#output\_backend\_cluster\_name) | The name of the ECS backend cluster. |
 | <a name="output_backend_ecr_repository_url"></a> [backend\_ecr\_repository\_url](#output\_backend\_ecr\_repository\_url) | The URL of the backend ECR repository. |
 | <a name="output_backend_service_name"></a> [backend\_service\_name](#output\_backend\_service\_name) | The name of the ECS backend service. |
+| <a name="output_backend_target_group_arn"></a> [backend\_target\_group\_arn](#output\_backend\_target\_group\_arn) | The ARN of the backend target group. |
 | <a name="output_fixtures_bucket_name"></a> [fixtures\_bucket\_name](#output\_fixtures\_bucket\_name) | The name of the S3 bucket for database fixtures. |
 | <a name="output_frontend_cluster_name"></a> [frontend\_cluster\_name](#output\_frontend\_cluster\_name) | The name of the ECS frontend cluster. |
 | <a name="output_frontend_ecr_repository_url"></a> [frontend\_ecr\_repository\_url](#output\_frontend\_ecr\_repository\_url) | The URL of the frontend ECR repository. |
 | <a name="output_frontend_service_name"></a> [frontend\_service\_name](#output\_frontend\_service\_name) | The name of the ECS frontend service. |
+| <a name="output_frontend_target_group_arn"></a> [frontend\_target\_group\_arn](#output\_frontend\_target\_group\_arn) | The ARN of the frontend target group. |
 | <a name="output_frontend_url"></a> [frontend\_url](#output\_frontend\_url) | The URL to access the frontend. |
 | <a name="output_nat_gateway_enabled"></a> [nat\_gateway\_enabled](#output\_nat\_gateway\_enabled) | Whether a NAT Gateway is enabled. |
 | <a name="output_private_subnet_ids"></a> [private\_subnet\_ids](#output\_private\_subnet\_ids) | A list of private subnet IDs. |

infrastructure/live/main.tf

@@ -54,6 +54,7 @@ module "backend" {
   desired_count                   = var.backend_desired_count
   enable_auto_scaling             = var.backend_enable_auto_scaling
   environment                     = var.environment
+  force_new_deployment            = var.force_new_deployment
   health_check_path               = "/status/"
   image_tag                       = var.backend_image_tag
   kms_key_arn                     = module.kms.key_arn
@@ -121,6 +122,7 @@ module "frontend" {
   desired_count                   = var.frontend_desired_count
   enable_auto_scaling             = var.frontend_enable_auto_scaling
   environment                     = var.environment
+  force_new_deployment            = var.force_new_deployment
   health_check_path               = "/api/health"
   image_tag                       = var.frontend_image_tag
   kms_key_arn                     = module.kms.key_arn
@@ -182,6 +184,7 @@ module "networking" {
 module "parameters" {
   source = "../modules/parameters"
 
+  alb_dns_name                  = module.alb.alb_dns_name
   common_tags                   = local.common_tags
   db_password_arn               = module.database.db_password_arn
   django_configuration          = var.django_configuration
@@ -190,9 +193,12 @@ module "parameters" {
   django_aws_static_bucket_name = module.storage.static_s3_bucket_name
   django_db_host                = module.database.db_proxy_endpoint
   django_db_name                = var.db_name
-  django_db_port                = var.db_port
+  django_db_port                = module.database.db_port
   django_db_user                = var.db_user
+  django_redis_auth_enabled     = var.django_redis_auth_enabled
   django_redis_host             = module.cache.redis_primary_endpoint
+  django_redis_port             = var.django_redis_port
+  django_redis_use_tls          = var.django_redis_use_tls
   django_release_version        = var.django_release_version
   django_settings_module        = var.django_settings_module
   enable_additional_parameters  = var.enable_additional_parameters

infrastructure/live/outputs.tf

@@ -28,6 +28,11 @@ output "backend_service_name" {
   value       = module.backend.ecs_service_name
 }
 
+output "backend_target_group_arn" {
+  description = "The ARN of the backend target group."
+  value       = module.alb.backend_target_group_arn
+}
+
 output "fixtures_bucket_name" {
   description = "The name of the S3 bucket for database fixtures."
   value       = module.storage.fixtures_s3_bucket_name
@@ -48,6 +53,11 @@ output "frontend_service_name" {
   value       = module.frontend.ecs_service_name
 }
 
+output "frontend_target_group_arn" {
+  description = "The ARN of the frontend target group."
+  value       = module.alb.frontend_target_group_arn
+}
+
 output "frontend_url" {
   description = "The URL to access the frontend."
   value       = "https://${var.domain_name}"

infrastructure/live/terraform.production.tfvars.example

@@ -26,3 +26,4 @@ frontend_min_count              = 2
 frontend_use_fargate_spot       = false
 project_name                  = "nest"
 tasks_use_fargate_spot        = false
+force_new_deployment          = false

infrastructure/live/terraform.staging.tfvars.example

@@ -24,3 +24,4 @@ frontend_min_count              = 1
 frontend_use_fargate_spot       = true
 project_name                  = "nest"
 tasks_use_fargate_spot        = true
+force_new_deployment          = false