payguard-poc/DOCKER_QUICK_START.md

PayGuard Docker-Complete Quick Start

Run the entire system (Infrastructure + API + Frontend) with a single Docker command.

What's Included

docker compose up
    ├─ Zookeeper (port 2181)
    ├─ Kafka (port 9092)
    ├─ Redis (port 6379)
    └─ React Frontend (port 3000) ✨ NEW!

Prerequisites

• Docker Desktop installed and running
• Python 3.9+ (for API and consumer - run separately)
• Terminal (you'll need 2-3 windows)

Super Quick Start (3 Steps)

Step 1: Start Docker Infrastructure + Frontend

cd /Users/pat/Projects/PAT/payguard-poc
docker compose up

Wait for output:

frontend    | ✓ Ready on http://0.0.0.0:3000

This starts:

• ✅ Zookeeper
• ✅ Kafka
• ✅ Redis
• ✅ React Frontend (auto-built and running)

Important: The frontend is configured to reach the API at http://host.docker.internal:8000 (special Docker networking that reaches your host machine from inside the container).

Step 2: Start API (New Terminal)

source venv/bin/activate
uvicorn api.main:app --reload --port 8000

Step 3: Start Consumer (New Terminal)

cd consumer
python pipeline.py

Access the System

• Frontend: http://localhost:3000
• API: http://localhost:8000
• Kafka: localhost:9092
• Redis: localhost:6379

Using the Frontend

1. Frontend loads automatically at http://localhost:3000
2. Click "Generate Token"
3. Select a scenario or enter custom transaction
4. Click "Submit Transaction"
5. Watch consumer terminal for 6-step pipeline execution

What's Different?

Before (Manual Docker)

docker compose up -d  # Just infra
npm run dev          # Frontend in dev mode
uvicorn ...          # API
cd consumer && python pipeline.py  # Consumer

Now (Complete Docker)

docker compose up  # Everything (infra + frontend)
uvicorn ...        # API (separate terminal)
python pipeline.py # Consumer (separate terminal)

Docker Compose Features

✅ Frontend Service

• Automatically built from frontend/Dockerfile
• Optimized production build (63KB gzip)
• Health checks enabled
• Auto-restart on failure
• Runs on port 3000

✅ Service Dependencies

• Frontend waits for Kafka and Redis to be healthy
• Proper startup order maintained
• All services on payguard-network

✅ Health Checks

• Zookeeper: Ready when port 2181 responds
• Kafka: Ready when broker API responds
• Redis: Ready when redis-cli ping succeeds
• Frontend: Ready when HTTP 200 on port 3000

Commands

# Start everything
docker compose up

# Start in background
docker compose up -d

# View logs
docker compose logs -f frontend
docker compose logs -f kafka
docker compose logs -f redis

# Stop all services
docker compose down

# Remove volumes (reset Redis)
docker compose down -v

# Rebuild frontend (if you change code)
docker compose up --build frontend

# View service status
docker compose ps

Benefits

✨ Single Command: Start infra + frontend with one command ✨ Faster: No manual npm dev server startup ✨ Cleaner: One window for infra, one for API, one for consumer ✨ Production-Like: Frontend runs as optimized production build ✨ Better Testing: Test the real build, not dev mode ✨ Teamwork: Non-developers just run docker compose up

Development Notes

If you need to develop the frontend:

# Option 1: Stop Docker frontend, run npm dev locally
docker compose stop frontend
cd frontend && npm run dev

# Option 2: Rebuild Docker image
docker compose up --build frontend

Troubleshooting

Frontend won't start

docker compose logs frontend
# Check for build errors
docker compose up --build frontend

Frontend can't connect to API

# Make sure API is running on host at port 8000
curl http://localhost:8000/health
# Should return: {"status": "healthy", ...}

# If API is running but frontend still fails:
# The frontend uses host.docker.internal:8000 to reach the host
# This is a Docker Desktop feature that maps to localhost on the host

# Verify it's working with:
docker exec $(docker ps -q -f name=payguard-frontend) \
  wget --spider -q http://host.docker.internal:8000
# Should work without error

Port 3000 already in use

# Find and kill process
lsof -t -i :3000

# Or use different port in docker-compose.yml
# Change: "3000:3000" to "3001:3000"

"host.docker.internal" not recognized (Linux only)

On Linux, host.docker.internal may not work. Instead:

# Option 1: Pass host IP to container
docker compose up --build
# Then edit docker-compose.yml frontend environment:
# VITE_API_URL=http://172.17.0.1:8000  (default Docker gateway)

# Option 2: Use network_mode: host (shares host network)
# Add to frontend service: network_mode: "host"
# Then remove ports, depends_on conditions

Full System Architecture

User Browser
    ↓
http://localhost:3000
    ↓
    ┌─ React Frontend ────────────────────┐
    │  (Running in Docker on port 3000)   │
    └─────────────────┬────────────────────┘
                      │ REST API calls
                      ↓
    ┌─ FastAPI Backend ──────────────────┐
    │  (Your Python process on port 8000) │
    └─────────────────┬────────────────────┘
                      │ Kafka messages
                      ↓
    ┌─ Kafka (Docker) ───────────────────┐
    │  Port: 9092                         │
    └─────────┬───────────────────────────┘
              │
    ┌─────────┴──────────┐
    ↓                    ↓
Kafka Topic        Zookeeper
                  (Docker)
    
    Consumer Pipeline (Your Python process)
    ↓
    Redis (Docker - Port 6379)

Next Steps

1. ✅ Run: docker compose up
2. ✅ View: http://localhost:3000
3. ✅ API: uvicorn api.main:app --reload
4. ✅ Consumer: cd consumer && python pipeline.py
5. ✅ Test: Use frontend to submit transactions
6. ✅ Watch: Consumer terminal for pipeline execution

---

Quick Reference:

Command	What it does
docker compose up	Start all services (infra + frontend)
docker compose up -d	Start in background
docker compose down	Stop all services
docker compose logs -f frontend	Watch frontend logs
docker compose ps	Show service status
docker compose up --build frontend	Rebuild frontend

---

Support Files:

• Full guide: FULLSTACK_GUIDE.md
• Frontend docs: frontend/README.md
• Architecture: README_IMPLEMENTATION.md