Getting Started

Welcome! This guide will help you get the QR Code Generator up and running quickly.

🎯 What You'll Build

By the end of this guide, you'll have:

• A fully functional QR code generation system
• Web dashboard for managing QR codes
• REST API for programmatic access
• Comprehensive monitoring with Grafana dashboards
• Production-ready security with Traefik

📋 Prerequisites

• Docker (20.10+) and Docker Compose (2.0+)
• Git for cloning the repository
• 4GB RAM minimum (8GB recommended for monitoring stack)
• Linux/macOS/Windows with Docker Desktop

🚀 Quick Setup (5 Minutes)

1. Clone the Repository

git clone https://github.com/gsinghjay/mvp_qr_gen.git
cd mvp_qr_gen

2. Configure Environment

# Copy the example environment file
cp .env.example .env

# Edit the configuration (optional for quick start)
nano .env

Key settings for quick start:

# Basic configuration
BASE_URL="https://localhost"

# Security (change in production!)
AUTH_USER=admin_user
AUTH_PASS=strongpassword

# Monitoring
GRAFANA_ADMIN_PASSWORD=admin123

3. Start the System

# Start all services
docker-compose up --build -d

# Check service status
docker-compose ps

4. Verify Installation

Check service health:

# All services should show "healthy"
docker-compose ps

# Check logs if needed
docker-compose logs api

🌐 Access Your System

Once running, access these endpoints:

Service	URL	Credentials	Purpose
Web Dashboard	https://localhost/	admin_user:strongpassword	QR management
API Documentation	https://localhost/docs	None	Interactive API docs
Grafana Monitoring	http://localhost:3000/	admin:admin123	System monitoring
Prometheus Metrics	http://localhost:9090/	None	Raw metrics

🎯 Create Your First QR Code

Via Web Interface

1. Access Dashboard: Go to https://localhost/
2. Login: Use admin_user / strongpassword
3. Create QR Code: Click "Create New QR Code"
4. Configure:
   • Type: Static (for permanent content) or Dynamic (for updatable URLs)
   • Content: Enter URL or text
   • Customize: Colors, size, error correction
5. Generate: Click "Create QR Code"
6. Download: Get PNG, SVG, or other formats

Via API

# Create a static QR code
curl -X POST "https://localhost/api/v1/qr/static" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "https://example.com",
    "title": "My First QR Code",
    "description": "Test QR code from API"
  }' -k

# Create a dynamic QR code
curl -X POST "https://localhost/api/v1/qr/dynamic" \
  -H "Content-Type: application/json" \
  -d '{
    "redirect_url": "https://example.com",
    "title": "Dynamic QR Code",
    "description": "Updatable QR code"
  }' -k

📊 Explore Monitoring

Grafana Dashboards

Access Grafana at http://localhost:3000/ (admin/admin123):

1. QR System Health Overview - System status and performance
2. QR Analytics Deep Dive - Usage patterns and scan analytics
3. QR Infrastructure Deep Dive - Resource usage and health

Key Metrics to Watch

• Response Times: Should be <30ms for QR redirects
• Error Rates: Should be <1% under normal conditions
• Scan Counts: Track QR code usage patterns
• System Resources: CPU, memory, and disk usage

🔧 Basic Configuration

Environment Variables

Key settings in .env:

# Application
BASE_URL="https://your-domain.com"
LOG_LEVEL=INFO

# Security
ALLOWED_REDIRECT_DOMAINS="your-domain.com,trusted-site.com"
AUTH_USER=your_admin_user
AUTH_PASS=your_secure_password

# Database
POSTGRES_PASSWORD=secure_db_password

# Monitoring
GRAFANA_ADMIN_PASSWORD=secure_grafana_password

Traefik Security

For production, update dynamic_conf.yml:

# Update IP allowlist for admin access
ip-whitelist:
  ipWhiteList:
    sourceRange:
      - "your.trusted.ip.range/24"
      - "10.0.0.0/8"  # Internal networks

🧪 Test Your Setup

Health Checks

# Check application health
curl https://localhost/health -k

# Check all services
docker-compose ps

# View logs
docker-compose logs --tail=50

Create Test QR Codes

# Test static QR code
curl -X POST "https://localhost/api/v1/qr/static" \
  -H "Content-Type: application/json" \
  -d '{"content": "Hello World!", "title": "Test"}' -k

# Test dynamic QR code
curl -X POST "https://localhost/api/v1/qr/dynamic" \
  -H "Content-Type: application/json" \
  -d '{"redirect_url": "https://github.com", "title": "GitHub"}' -k

Test QR Scanning

1. Create a dynamic QR code via the web interface
2. Note the short URL (e.g., /r/abc123)
3. Test redirect: curl -I https://localhost/r/abc123 -k
4. Should return 302 Found with Location header

🚨 Troubleshooting

Common Issues

Services won't start:

# Check Docker resources
docker system df
docker system prune  # If needed

# Check logs
docker-compose logs

Can't access web interface:

# Check Traefik routing
docker-compose logs traefik

# Verify certificates
openssl s_client -connect localhost:443 -servername localhost

Database connection issues:

# Check PostgreSQL
docker-compose logs postgres

# Test database connection
docker-compose exec api python -c "
from app.core.database import get_db_session
with get_db_session() as db:
    print('Database connection successful!')
"

Getting Help

• Logs: docker-compose logs [service_name]
• Service Status: docker-compose ps
• Resource Usage: docker stats
• Wiki: Check the Troubleshooting page
• Issues: Create an issue on GitHub

🎉 Next Steps

Now that you have the system running:

1. Explore the Web Interface - Learn all dashboard features
2. API Documentation - Integrate with your applications
3. Configure Monitoring - Set up alerts and dashboards
4. Security Setup - Harden for production use
5. Performance Tuning - Optimize for your workload

📚 Learn More

• System Architecture - Understand how it all works
• Docker Deployment - Production deployment guide
• Observatory-First Monitoring - Deep dive into monitoring

---

Congratulations! 🎉 You now have a fully functional QR Code Generator with enterprise-grade monitoring. The system is ready for both development and production use.