ronaldoalencar/sqs-handler repository overview

⁠SQS Handler

Web UI to manage Amazon SQS queues — against LocalStack (development) or real AWS (test/staging/production).

A single image bundling the frontend (React + Nginx) and the backend (Node.js + Express + AWS SDK v3), managed by supervisord. Nginx already proxies /api to the backend, so publishing port 80 is enough.

⁠Features

• 📋 List all available SQS queues
• 👀 Inspect queue messages (up to 10 at a time), pretty-printed as JSON
• 📤 Send JSON messages with dynamic faker variables (faker.person.fullName, faker.internet.email, faker.finance.accountNumber, UUID, and more)
• 🗑️ Delete individual messages
• 🧹 Purge all messages from a queue
• 📎 Copy a message's JSON to the clipboard
• 🔀 Switch between LocalStack and real AWS with a single environment variable

⁠Quick start

⁠LocalStack (Linux)

docker run -d --name sqs-handler \
  -p 8080:80 \
  -e USE_LOCALSTACK=true \
  -e LOCALSTACK_ENDPOINT=http://172.17.0.1:4566 \
  -e AWS_REGION=us-east-1 \
  your-user/sqs-handler:latest

⁠Real AWS

docker run -d --name sqs-handler \
  -p 8080:80 \
  -e USE_LOCALSTACK=false \
  -e AWS_REGION=us-east-1 \
  -e AWS_ACCESS_KEY_ID=your-access-key \
  -e AWS_SECRET_ACCESS_KEY=your-secret-key \
  your-user/sqs-handler:latest

Then open http://localhost:8080⁠.

⁠Environment variables

If AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY are omitted, the AWS SDK falls back to its default credential chain (environment variables → ~/.aws/credentials → IAM role on EC2/ECS/Lambda).

⁠Ports

⁠docker-compose

services:
  sqs-handler:
    image: your-user/sqs-handler:latest
    container_name: sqs-handler
    restart: unless-stopped
    ports:
      - "8080:80"
    environment:
      - NODE_ENV=production
      - PORT=3001
      - USE_LOCALSTACK=false
      - AWS_REGION=us-east-1
      - AWS_ACCESS_KEY_ID=${AWS_ACCESS_KEY_ID}
      - AWS_SECRET_ACCESS_KEY=${AWS_SECRET_ACCESS_KEY}
    extra_hosts:
      - "host.docker.internal:host-gateway"

docker compose up -d

⁠API

The backend exposes the following endpoints (also reachable under /api on port 80):

⁠Healthcheck

The image ships with a HEALTHCHECK that polls http://localhost:3001/api/queues every 30s.

⁠Image details

• Base: node:18-alpine
• Build: multi-stage (Vite frontend → Nginx; backend with production-only dependencies)
• Processes: supervisord running Nginx and the Node backend (the backend runs as the non-root user appuser)

⁠Stack

React 18 · TypeScript · Vite · TailwindCSS · Node.js · Express · AWS SDK v3 · Nginx