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:

```bash
npm i -g @devcontainers/cli
devcontainer build --workspace-folder . --file .devcontainer/Dockerfile
devcontainer 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