algorithms/QUICK_START.md

🚀 Quick Deployment Reference

Local Testing

Using Docker Compose (Recommended)

cd /Volumes/WorkSpace/Project/REMB/algorithms

# Build images
make build

# Start services
make up

# View logs
make logs

# Check health
make health

# Access services
# Backend:  http://localhost:8000
# Frontend: http://localhost:8501
# API Docs: http://localhost:8000/docs

# Stop services
make down

Manual (Without Docker)

# Terminal 1: Backend
cd /Volumes/WorkSpace/Project/REMB/algorithms/backend
pip install -r requirements.txt
uvicorn main:app --reload --port 8000

# Terminal 2: Frontend
cd /Volumes/WorkSpace/Project/REMB/algorithms/frontend
pip install -r requirements.txt
export API_URL=http://localhost:8000
streamlit run app.py --server.port 8501

---

Production Deployment

Backend → Hugging Face Spaces

cd /Volumes/WorkSpace/Project/REMB/algorithms/backend

# 1. Rename README for HF
cp README_HF.md README.md

# 2. Initialize git (if needed)
git init

# 3. Add HF remote (replace with your details)
git remote add hf https://huggingface.co/spaces/<USERNAME>/<SPACE_NAME>

# 4. Commit and push
git add .
git commit -m "Deploy to Hugging Face Spaces"
git push hf main

# 5. Monitor build at:
# https://huggingface.co/spaces/<USERNAME>/<SPACE_NAME>

Your API will be at: https://<USERNAME>-<SPACE_NAME>.hf.space

Frontend → Streamlit Cloud

cd /Volumes/WorkSpace/Project/REMB/algorithms/frontend

# 1. Push to GitHub
git init
git remote add origin https://github.com/<USERNAME>/<REPO_NAME>.git
git add .
git commit -m "Initial commit"
git branch -M main
git push -u origin main

# 2. Go to Streamlit Cloud
# https://streamlit.io/cloud

# 3. Create new app:
# - Repository: <USERNAME>/<REPO_NAME>
# - Branch: main
# - Main file: app.py

# 4. Add secrets in Streamlit Cloud settings:
# API_URL = "https://<HF_USERNAME>-<SPACE_NAME>.hf.space"

# 5. Deploy!

Your app will be at: https://<APP_NAME>.streamlit.app

---

Environment Variables

Backend (.env or HF Secrets)

API_HOST=0.0.0.0
API_PORT=7860
CORS_ORIGINS=*
LOG_LEVEL=INFO

Frontend (.env or Streamlit Secrets)

# Development
API_URL=http://localhost:8000

# Production
API_URL=https://<HF_USERNAME>-<SPACE_NAME>.hf.space

---

Troubleshooting

Docker Build Fails

# Test build locally
cd backend
docker build -t test .

# Check logs
docker logs <container_id>

# Run interactively
docker run -it test /bin/bash

Frontend Can't Connect

1. Check API_URL environment variable
2. Verify backend is running
3. Check CORS settings in backend
4. Test backend directly: curl <API_URL>/health

Port Already in Use

# Find process
lsof -i :8000
lsof -i :8501

# Kill process
kill -9 <PID>

---

Testing Deployed Services

Test Backend API

# Health check
curl https://<USERNAME>-<SPACE_NAME>.hf.space/health

# View API docs
open https://<USERNAME>-<SPACE_NAME>.hf.space/docs

# Test optimization endpoint
curl -X POST https://<USERNAME>-<SPACE_NAME>.hf.space/api/optimize \
  -H "Content-Type: application/json" \
  -d '{
    "config": {
      "spacing_min": 20,
      "spacing_max": 30,
      "population_size": 20,
      "generations": 50
    },
    "land_plots": [{
      "type": "Polygon",
      "coordinates": [[[0,0],[100,0],[100,100],[0,100],[0,0]]]
    }]
  }'

Test Frontend

1. Open https://<APP_NAME>.streamlit.app
2. Select "Sample" → "Rectangle 100x100"
3. Click "🚀 Run Optimization"
4. Wait for results
5. Download GeoJSON

---

Useful Makefile Commands

make help           # Show all available commands
make build          # Build Docker images
make up             # Start services
make down           # Stop services
make logs           # View all logs
make logs-backend   # View backend logs only
make logs-frontend  # View frontend logs only
make restart        # Restart all services
make clean          # Stop and remove volumes
make test-backend   # Test backend container
make dev-backend    # Run backend without Docker
make dev-frontend   # Run frontend without Docker
make status         # Show service status
make health         # Check service health

---

File Checklist

Before deploying, ensure these files exist:

Backend:

• Dockerfile
• .dockerignore
• requirements.txt (with production deps)
• README_HF.md (will become README.md)

Frontend:

• app.py (with environment support)
• requirements.txt (with python-dotenv)
• .streamlit/config.toml

Root:

• docker-compose.yml
• Makefile
• .env.production (template)
• DEPLOYMENT.md
• README.md (updated)

---

Quick Links

• 📖 Full Guide: DEPLOYMENT.md
• 🏠 Main README: README.md
• 🐳 Backend Dockerfile: Dockerfile
• 🎨 Frontend App: app.py
• 🔧 Docker Compose: docker-compose.yml

---

Support

• Hugging Face Spaces: https://huggingface.co/docs/hub/spaces
• Streamlit Cloud: https://docs.streamlit.io/streamlit-community-cloud
• Docker: https://docs.docker.com/

Next Step: Follow the DEPLOYMENT.md guide!