A VS Code devcontainer template for local AWS development with LocalStack, Terraform, Docker-in-Docker (dinD), and supporting tools. Perfect for bootstrapping any app (Next.js, Python, Go, etc.) that needs local AWS emulation – no Ruby/Rails assumptions.

• LocalStack (SQS, S3, DynamoDB, etc.) via Docker.
• Terraform with example modules (SQS/S3/DynamoDB).
• dinD for running AWS services + local Docker registry (ECR sim).
• Tools: AWS CLI, Terraform, awslocal (awscli-local), jq, httpie, Node 20.
• VS Code: AWS Toolkit, LocalStack Toolkit, Terraform, Prettier/ESLint/TS.
• Scripts: setup.sh, start/stop-localstack.sh, start-supporting-services.sh (registry).

• Clone/fork this repo.
• Reopen in Container (Dev Containers extension).

./scripts/setup.sh

• Starts LocalStack (4566), Docker registry (5001).
• Runs terraform init/apply (empty by default; uncomment modules).

npx create-next-app@latest my-app --typescript --tailwind --eslint --app --src-dir --import-alias "@/*"
cd my-app
npm run dev  # http://localhost:3000

# Health check
curl http://localhost:4566/health

# awslocal (pip-installed awscli-local)
awslocal sqs list-queues

# AWS CLI
aws --endpoint-url=http://localhost:4566 s3 ls

cd infrastructure
terraform init
terraform plan  # Empty/no-op by default
# Edit main.tf to uncomment modules, then apply
terraform apply

.
├── .devcontainer/     # Dev env (Node/Terraform/AWS/LocalStack)
├── infrastructure/    # Terraform (provider + modules/sqs|s3|dynamodb)
├── scripts/           # Utils (setup, localstack, registry, CI/CD)
├── docs/              # Documentation (Deploy Runner guide)
├── README.md
└── [your-app/]        # Bootstrap here (e.g., Next.js)

LocalStack Services: SQS/S3/DynamoDB ready (add endpoints in main.tf).

Registry: localhost:5001 (push/pull images for ECR sim).

This project includes GitLab CE with a two-runner architecture:

• Build Runner (DinD): Isolated image builds with Docker-in-Docker
• Deploy Runner (Host Docker): Deployments with access to devcontainer-network

See Deploy Runner Documentation for details.

GitLab Management:

# Normal workflow (stop/start preserves data, auto-registers runners)
./scripts/start-gitlab.sh      # Start + register runners
./scripts/stop-gitlab.sh       # Stop + unregister runners

# Fresh setup (first time or after removing data)
./scripts/setup-gitlab.sh      # Full setup: project + SSH + runners

# Nuclear option (clean slate)
./scripts/stop-gitlab.sh --remove-data  # Remove all data
./scripts/start-gitlab.sh               # Start fresh

Pipeline Stages: build_ci_images → validate → deploy_infra → deploy_app → build_backend → deploy_backend

1. Uncomment modules in infrastructure/main.tf.
2. Set vars (e.g., terraform apply -var="queue_name=my-queue").
3. Outputs in outputs.tf / module outputs.

Example SQS:

module "my_sqs" {
  source = "./modules/sqs"
  queue_name = "my-app-queue"
  ...
}

• LocalStack down: ./scripts/start-localstack.sh --remove
• Ports conflict: Kill on 4566/3000/5001.
• Terraform state: rm infrastructure/terraform.tfstate*
• Rebuild devcontainer: Cmd+Shift+P > "Dev Containers: Rebuild..."

• Base: Debian Bookworm + Node 20, Terraform latest.
• LocalStack 3.x, AWS CLI, awslocal.
• dinD (Buildx/Compose v2).

1. GitHub Setup:

   • Push this repo.
   • Repo Settings > Template repository > Save.

2. VSCode:

   • Cmd+Shift+P > "Dev Containers: Add Dev Container Configuration Files..."
   • Search "LocalStack" or your repo name.
   • Or clone template repo > Reopen in Container.

3. Test:

   npx @devcontainers/cli@latest up --workspace-folder .
   

See containers.dev for more.

Fork & customize! 🚀