Simple Counter App with Rails, AWS, and LocalStack

A Rails web application that implements a simple counter and sends count updates to other app instances via AWS SQS, all running in a LocalStack development environment within devcontainers.

🏗️ Project Structure

simple-app-localstack/
├── .devcontainer/ # VS Code devcontainer configuration
│ └── devcontainer.json # Container setup with Rails, AWS CLI, Terraform
├── app/ # Rails application
│ ├── Gemfile # Ruby dependencies
│ ├── config/ # Rails configuration
│ └── ... # Standard Rails structure
├── infrastructure/ # Terraform configuration
│ ├── main.tf # Provider and LocalStack configuration
│ ├── sqs.tf # SQS queue definitions
│ └── outputs.tf # Terraform outputs
├── scripts/ # Setup and utility scripts
│ └── setup.sh # Development environment setup
├── app-docker-images/ # Dockerfiles for app images (dev/prod)
└── README.md # This file

🚀 Getting Started

Prerequisites

• Docker and Docker Compose
• VS Code with the following extensions:
  • Dev Containers extension
  • AWS Toolkit
  • LocalStack Toolkit

Setup

1. Open in VS Code: Open this project in VS Code
2. Reopen in Container: When prompted, click "Reopen in Container" or use the Command Palette (Cmd+Shift+P) and select "Dev Containers: Reopen in Container"
3. Wait for Setup: The devcontainer will automatically:
   • Build the development environment
   • Install all dependencies
   • Set up LocalStack infrastructure
   • Configure the Rails application

Development Workflow

Once the devcontainer is running:

1. Start the Rails server:

   cd /workspace/app
   rails server

2. Access the application: http://localhost:3000

3. Access LocalStack: http://localhost:4566

4. Monitor SQS queues:

   aws --endpoint-url=http://localstack:4566 sqs list-queues

🏢 Architecture

Services

• Rails App: Main web application with counter functionality
• LocalStack: Local AWS services emulation (SQS)
• Redis: Session store and Sidekiq backend
• Sidekiq: Background job processing

AWS Resources (via LocalStack)

• SQS Queue: counter-queue for inter-app communication
• SQS DLQ: counter-queue-dlq for failed messages

🔧 Configuration

Environment Variables

The devcontainer automatically sets up these environment variables:

AWS_DEFAULT_REGION=us-east-1
AWS_ACCESS_KEY_ID=test
AWS_SECRET_ACCESS_KEY=test
LOCALSTACK_ENDPOINT=http://localstack:4566
COUNTER_QUEUE_URL=http://localstack:4566/000000000000/counter-queue
REDIS_URL=redis://redis:6379/0

Terraform Configuration

Infrastructure is defined in the infrastructure/ directory:

• LocalStack provider configuration
• SQS queue and DLQ creation
• Outputs for queue URLs

📝 Next Steps

After setting up the basic structure, you'll want to:

1. Generate Rails components:

   rails generate controller Counter index
   rails generate model CounterEvent count:integer message:text

2. Implement the counter logic:

   • Counter controller with increment/decrement actions
   • SQS message publishing
   • Background job for message processing

3. Add views and styling:

   • Counter display
   • Action buttons
   • Real-time updates (via ActionCable or polling)

🛠️ Useful Commands

Rails

rails server # Start the Rails server
rails console # Rails console
rails generate --help # See available generators
rails db:migrate # Run database migrations

Terraform

cd infrastructure
terraform plan # Preview changes
terraform apply # Apply changes
terraform destroy # Destroy infrastructure

AWS CLI (LocalStack)

# List SQS queues
aws --endpoint-url=http://localstack:4566 sqs list-queues
# Send a test message
aws --endpoint-url=http://localstack:4566 sqs send-message \
--queue-url http://localstack:4566/000000000000/counter-queue \
--message-body "Test message"# Receive messages
aws --endpoint-url=http://localstack:4566 sqs receive-message \
--queue-url http://localstack:4566/000000000000/counter-queue

Docker

./scripts/start-supporting-services.sh # starts Redis and registry via docker run
./scripts/registry-bridge.sh status # show registry status and list images## 🧰 Devcontainer image and developer tooling
This repository now builds the devcontainer from a Dockerfile (`.devcontainer/Dockerfile`) so we can bake developer tools into the image.
- Tools installed in the devcontainer image:
- `redis-cli` (provided by `redis-tools`) — quick Redis checks and troubleshooting
- `jq` — JSON CLI processor
- `http` (HTTPie) — friendlier HTTP client than curl for quick API calls
### Rebuild the devcontainer
After pulling the repo changes you'll need to rebuild the devcontainer so the new Dockerfile is used. In VS Code:1. Open the Command Palette (Ctrl/Cmd+Shift+P)2. Select `Dev Containers: Rebuild and Reopen in Container`Or using the Dev Container CLI:```bashnpm i -g @devcontainers/clidevcontainer build --workspace-folder . --file .devcontainer/Dockerfiledevcontainer up --workspace-folder .

Quick checks inside the devcontainer

which redis-cli jq http You can use the helper scripts to manage supporting services (registry and Redis) and the Local Docker registry:

./scripts/start-supporting-services.sh # starts Redis and registry via docker run
./scripts/registry-bridge.sh start # starts the local registry only (if needed)
./scripts/registry-bridge.sh status # show registry status and list images
./scripts/registry-bridge.sh clean # remove registry container & data

Use the helper script to start local supporting services (Redis and a local Docker registry):

./scripts/start-supporting-services.sh

If you need to stop/remove them:

docker rm -f redis registry ||true

## 🐛 Troubleshooting
### LocalStack not responding
```bash
# Check LocalStack health
curl http://localhost:4566/health
# Restart LocalStack (example using Docker)
docker restart <localstack-container-name>
# Or if you use the LocalStack CLI or supervisor, restart via that tool

Rails server issues

# Check if gems are installed
bundle check
# Reinstall gems
bundle install
# Check database
rails db:create db:migrate

Port conflicts

• Rails: 3000
• LocalStack: 4566
• Redis: 6379

Make sure these ports are available on your host machine.

📚 Technologies Used

• Ruby on Rails 7.0: Web framework
• LocalStack: Local AWS development
• Terraform: Infrastructure as Code
• Docker: Containerization
• Sidekiq: Background job processing
• Redis: In-memory data store
• AWS SDK: AWS service integration
• SQLite: Development database