Skip to content

QUICKSTART.md

Latest commit

 

History

History
191 lines (143 loc) · 3.67 KB

QUICKSTART.md

File metadata and controls

191 lines (143 loc) · 3.67 KB
Raw

Quick Start Guide

Get your production-ready URL shortener running in 5 minutes!

Prerequisites

  • Docker & Docker Compose installed
  • 8GB+ RAM available
  • Ports 5000, 3306, 6379, 9090, 3000 available

Step 1: Clone and Setup

# Clone the repository
git clone https://github.com/yourusername/url-shortener.git
cd url-shortener

# Create logs directory
mkdir -p logs data backups

Step 2: Generate JWT Keys

# Generate RSA keys for JWT
openssl genrsa -out private.pem 2048
openssl rsa -in private.pem -pubout -out public.pem
chmod 600 private.pem
chmod 644 public.pem

Step 3: Configure Environment

# Copy example env file
cp .env.example .env

# Edit .env and set at minimum:
# - MYSQL_PASSWORD=<strong-password>
# - SECRET_KEY=<random-string>

Step 4: Build and Start

# Build all containers
docker-compose build

# Start all services
docker-compose up -d

# Check status
docker-compose ps

Step 5: Initialize Database

# Wait for MySQL to be ready (30 seconds)
sleep 30

# Initialize schema
docker exec -i mysql-db mysql -uroot -p<your-password> urlshortener < sql/schema.sql

Step 6: Verify Installation

# Check Flask app health
curl http://localhost:5000/health

# Expected response:
# {"status": "healthy", "database": "connected", "redis": "connected"}

# Check all services
docker-compose ps

Step 7: Test the API

Sign Up

curl -X POST http://localhost:5000/auth/signup \
  -H "Content-Type: application/json" \
  -d '{"username": "testuser", "password": "Test123456"}'

Login

TOKEN=$(curl -X POST http://localhost:5000/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username": "testuser", "password": "Test123456"}' \
  | jq -r '.access_token')

Shorten a URL

curl -X POST http://localhost:5000/shorten \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"url": "https://www.google.com"}'

Test Redirect

# Copy the short_url from response and test:
curl -L http://localhost:5000/<short-code>

Access Monitoring

Common Commands

# View logs
docker-compose logs -f flask-app

# View Celery logs
docker-compose logs -f celery-worker

# Stop all services
docker-compose down

# Restart a service
docker-compose restart flask-app

# Scale workers
docker-compose up -d --scale celery-worker=5

Troubleshooting

Database Connection Error

# Check MySQL is ready
docker-compose exec db mysqladmin ping -h localhost -u root -p

Redis Connection Error

# Check Redis
docker-compose exec redis redis-cli ping

Port Already in Use

# Change ports in docker-compose.yml:
ports:
  - "5001:5000"  # Use 5001 instead of 5000

View All Container Logs

docker-compose logs --tail=100

Next Steps

  1. Read DEPLOYMENT.md for production deployment
  2. Review IMPROVEMENTS.md for all features
  3. Configure monitoring dashboards in Grafana
  4. Set up automated backups
  5. Configure SSL/TLS for production

Production Checklist

Before deploying to production:

  • Change all default passwords
  • Generate strong SECRET_KEY
  • Configure proper CORS_ORIGINS
  • Set up SSL/TLS certificates
  • Configure automated backups
  • Set up monitoring alerts
  • Review security settings
  • Test disaster recovery
  • Configure log aggregation
  • Set up health check monitoring

Support

  • 📖 Full Documentation: DEPLOYMENT.md
  • 🐛 Issues: GitHub Issues
  • 💬 Questions: Discussions

Happy shortening! 🚀