Add LocalStack-based Local Infrastructure Automation and Documentation
- Dominant language
- Python
- Stars
- 451
- Forks
- 702
- Avg merge
- 22h 59m
- Merged PRs (30d)
- 91
Description
Community & Support: [LinkedIn Group](https://www.linkedin.com/groups/14656108/) · [Slack #project-nest](https://owasp.slack.com/archives/project-nest)
Active project leaders: Arkadii Yakovets -- [GitHub](https://github.com/arkid15r/) · [LinkedIn](https://www.linkedin.com/in/arkid15r/) · [Slack](https://owasp.slack.com/team/U060W3NKLTF); Kate Golovanova -- [GitHub](https://github.com/kasya/) · [LinkedIn](https://www.linkedin.com/in/kate-golovanova/) · [Slack](https://owasp.slack.com/team/U07PWB1JZ6Z)
[Contributing](https://github.com/owasp/nest/blob/main/CONTRIBUTING.md) · [Code of Conduct](https://github.com/owasp/nest/blob/main/CODE_OF_CONDUCT.md) · [GSoC Mentors](https://github.com/owasp/nest/blob/main/MENTORS.md)
---
### Summary
OWASP Nest recently gained access to [LocalStack for Open Source](https://www.localstack.cloud/localstack-open-source) (Ultimate tier via their open source support program). The next step is to add documentation and automation around local infrastructure development using LocalStack.
Currently, testing infrastructure changes requires deploying to an actual AWS environment. With LocalStack, we can provision our entire AWS Stack locally instead.
### Goals
- Create scripts that automate the entire infrastructure setup.
- Add `make` targets to run the scripts.
- Add documentation for setting up the infrastructure using LocalStack.
- Design the scripts to be simple and environment-agnostic, so the same script can run locally and in CI/CD (e.g., for future e2e tests) without requiring a separate CI-specific version.
### Acceptance Criteria
- A make target that starts LocalStack. It requires a `LOCALSTACK_AUTH_TOKEN` (Ultimate tier) to be set in `infrastructure/.env`, and fails with a clear error if it isn't provided.
- A script provisions the entire infrastructure via Terraform (using `tflocal` or `AWS_ENDPOINT_URL`).
- The script builds the local frontend and backend images and pushes them to ECR, tagging each build with a unique identifier (e.g., commit SHA or timestamp), since ECR tags are immutable. Each run always pushes a new tag rather than detecting changes.
- A separate `make` target that reads local `.env` files and uploads the variables to SSM Parameter Store. This step must be documented as an optional quality-of-life step and must not run as part of the main setup script. Note that this step will change after #5071 is completed.
- The deployment configuration defaults to production (e.g., `DJANGO_CONFIGURATION=Production`), with the option to override it.
- `make` targets are added to run the scripts.
- Separate `make` targets are added to migrate, load data into, and index the database, preferably using the ECS tasks defined in `infrastructure/modules/tasks/main.tf`. (e.g., `awslocal ecs run-task`)
- The local docker-based frontend/backend development setup remains unchanged.
- The CI/CD remains unchanged.
- Documentation is updated with prerequisites and steps to:
- start LocalStack
- provision the infrastructure
- load env vars (optional)
- migrate, load data into, and index the database
- teardown
- Running the script multiple times should not break the local setup.
- The setup script avoids hardcoded assumptions specific to a local developer environment (e.g., interactive prompts, local-only paths) so it can be reused as-is or with minimal parameters in a CI/CD pipeline.
- The OWASP Nest web application must function almost identical to nest.owasp.dev/nest.owasp.org.
### Additional Context
LocalStack for Open Source: https://www.localstack.cloud/localstack-open-source
LocalStack docs: https://docs.localstack.cloud
LocalStack Terraform integration docs: https://docs.localstack.cloud/aws/connecting/infrastructure-as-code/terraform/
tflocal: https://github.com/localstack/terraform-local
awslocal: https://github.com/localstack/awscli-local
Existing AWS infrastructure [README](https://github.com/OWASP/Nest/blob/main/infrastructure/README.md)
Please also check existing CI/CD to learn more about the deployment process.
**Are you going to work on implementing this?**
- [x] Yes
- [ ] No
Contributor guide
Assessment
This issue has not been assessed yet.