Updated docker compose.
This commit is contained in:
407
README_DOCKER.md
Normal file
407
README_DOCKER.md
Normal file
@ -0,0 +1,407 @@
|
||||
# 🐳 Docker Deployment Documentation
|
||||
|
||||
Complete guide for deploying and testing the H2H betting platform with blockchain integration in Docker.
|
||||
|
||||
## 📚 Documentation Files
|
||||
|
||||
| File | Purpose | When to Use |
|
||||
|------|---------|-------------|
|
||||
| **DOCKER_QUICK_START.md** | Quick reference card | When you need fast commands |
|
||||
| **DOCKER_TESTING_GUIDE.md** | Comprehensive testing guide | Full deployment walkthrough |
|
||||
| **DOCKER_EXPECTED_RESULTS.md** | Visual guide of expected output | Verification and troubleshooting |
|
||||
| **test-docker.sh** | Automated test script | One-command deployment test |
|
||||
|
||||
## 🚀 Quick Start (30 seconds)
|
||||
|
||||
**Prerequisites**: Docker Desktop must be running (green icon in menu bar)
|
||||
|
||||
```bash
|
||||
# Run automated deployment test
|
||||
./test-docker.sh
|
||||
```
|
||||
|
||||
This will:
|
||||
- ✅ Build Docker images with blockchain integration
|
||||
- ✅ Start backend and frontend containers
|
||||
- ✅ Seed database with test users
|
||||
- ✅ Verify all services are working
|
||||
- ✅ Check blockchain files are present
|
||||
|
||||
**Expected time**: 3-5 minutes (first time), ~30 seconds (subsequent runs)
|
||||
|
||||
## 📖 Step-by-Step Guide
|
||||
|
||||
### 1. Ensure Docker is Running
|
||||
|
||||
Check Docker Desktop is started:
|
||||
```bash
|
||||
docker --version
|
||||
# Should show: Docker version 28.x.x
|
||||
```
|
||||
|
||||
### 2. Run Automated Tests
|
||||
|
||||
```bash
|
||||
chmod +x test-docker.sh
|
||||
./test-docker.sh
|
||||
```
|
||||
|
||||
### 3. Access Application
|
||||
|
||||
**Frontend**: http://localhost:5173
|
||||
```
|
||||
Login with:
|
||||
Email: alice@example.com
|
||||
Password: password123
|
||||
```
|
||||
|
||||
**Backend API**: http://localhost:8000/docs
|
||||
|
||||
### 4. Verify Blockchain Integration
|
||||
|
||||
In the browser, check for:
|
||||
- ⛓️ Blockchain badges on bet cards
|
||||
- "Connect Wallet" button in header
|
||||
- Gas estimate panels in bet creation/acceptance
|
||||
- "On-Chain Escrow" section in wallet (when connected)
|
||||
|
||||
### 5. Stop Services
|
||||
|
||||
```bash
|
||||
docker compose down
|
||||
```
|
||||
|
||||
## 🎯 What Gets Deployed
|
||||
|
||||
### Backend Container
|
||||
- FastAPI server on port 8000
|
||||
- SQLite database with blockchain fields:
|
||||
- `bets.blockchain_bet_id`
|
||||
- `bets.blockchain_tx_hash`
|
||||
- `bets.blockchain_status`
|
||||
- `wallets.blockchain_escrow`
|
||||
- Blockchain services:
|
||||
- `blockchain_service.py` - Web3 integration
|
||||
- `blockchain_indexer.py` - Event syncing
|
||||
- `oracle_node.py` - API data fetching
|
||||
- `oracle_aggregator.py` - Consensus mechanism
|
||||
|
||||
### Frontend Container
|
||||
- Vite dev server on port 5173
|
||||
- React application with blockchain UI:
|
||||
- Web3 wallet connection hooks
|
||||
- Gas estimate components
|
||||
- Transaction progress modals
|
||||
- Blockchain status badges
|
||||
- Modified components:
|
||||
- BetCard with blockchain badges
|
||||
- CreateBetModal with gas estimates
|
||||
- BetDetails with transaction flow
|
||||
- WalletBalance with on-chain section
|
||||
- Header with wallet connect button
|
||||
|
||||
## 🔍 Verification Checklist
|
||||
|
||||
Run through this checklist after deployment:
|
||||
|
||||
### Backend ✅
|
||||
- [ ] Container is running: `docker compose ps`
|
||||
- [ ] API docs accessible: http://localhost:8000/docs
|
||||
- [ ] Login works: Test with curl or Swagger UI
|
||||
- [ ] Blockchain files present: `docker compose exec backend ls app/blockchain/`
|
||||
|
||||
### Frontend ✅
|
||||
- [ ] Container is running: `docker compose ps`
|
||||
- [ ] App loads: http://localhost:5173
|
||||
- [ ] Login page renders
|
||||
- [ ] Can authenticate with test credentials
|
||||
- [ ] Blockchain hooks present: `docker compose exec frontend ls src/blockchain/`
|
||||
|
||||
### UI Features ✅
|
||||
- [ ] Blockchain badges visible on bet cards
|
||||
- [ ] "Connect Wallet" button in header
|
||||
- [ ] Gas estimate in Create Bet modal
|
||||
- [ ] Gas estimate panel on Bet Details
|
||||
- [ ] "On-Chain Escrow" section in Wallet
|
||||
- [ ] Transaction modals configured
|
||||
|
||||
### Integration ✅
|
||||
- [ ] No import errors in logs
|
||||
- [ ] TypeScript compiles without errors
|
||||
- [ ] All API endpoints responding
|
||||
- [ ] WebSocket connections work
|
||||
- [ ] Database has blockchain fields
|
||||
|
||||
## 🛠️ Common Commands
|
||||
|
||||
```bash
|
||||
# Start services
|
||||
docker compose up -d
|
||||
|
||||
# View logs
|
||||
docker compose logs -f
|
||||
docker compose logs -f backend
|
||||
docker compose logs -f frontend
|
||||
|
||||
# Stop services
|
||||
docker compose down
|
||||
|
||||
# Rebuild everything
|
||||
docker compose build --no-cache
|
||||
docker compose up -d
|
||||
|
||||
# Reset database
|
||||
docker compose down -v
|
||||
docker compose up -d
|
||||
docker compose exec backend python seed_data.py
|
||||
|
||||
# Shell access
|
||||
docker compose exec backend bash
|
||||
docker compose exec frontend sh
|
||||
|
||||
# Check resource usage
|
||||
docker stats
|
||||
|
||||
# Remove everything (nuclear option)
|
||||
docker compose down -v
|
||||
docker system prune -af
|
||||
```
|
||||
|
||||
## 🐛 Troubleshooting
|
||||
|
||||
### Services Won't Start
|
||||
|
||||
```bash
|
||||
# Check Docker daemon
|
||||
docker info
|
||||
|
||||
# Check port availability
|
||||
lsof -ti:8000
|
||||
lsof -ti:5173
|
||||
|
||||
# View detailed logs
|
||||
docker compose logs
|
||||
```
|
||||
|
||||
### Import Errors
|
||||
|
||||
```bash
|
||||
# Rebuild backend
|
||||
docker compose build --no-cache backend
|
||||
docker compose up -d backend
|
||||
|
||||
# Check Python imports
|
||||
docker compose exec backend python -c "from app.blockchain.services.blockchain_service import BlockchainService; print('OK')"
|
||||
```
|
||||
|
||||
### Frontend Build Errors
|
||||
|
||||
```bash
|
||||
# Rebuild frontend
|
||||
docker compose build --no-cache frontend
|
||||
docker compose up -d frontend
|
||||
|
||||
# Check TypeScript
|
||||
docker compose exec frontend npm run type-check
|
||||
```
|
||||
|
||||
### Database Issues
|
||||
|
||||
```bash
|
||||
# Reset and reseed
|
||||
docker compose down -v
|
||||
docker compose up -d
|
||||
sleep 10
|
||||
docker compose exec backend python seed_data.py
|
||||
```
|
||||
|
||||
## 📊 Performance Benchmarks
|
||||
|
||||
Expected performance in Docker:
|
||||
|
||||
| Metric | Expected Value |
|
||||
|--------|----------------|
|
||||
| Build time (first) | 3-5 minutes |
|
||||
| Build time (cached) | 10-30 seconds |
|
||||
| Startup time | 10-30 seconds |
|
||||
| Backend memory | < 200MB |
|
||||
| Frontend memory | < 500MB |
|
||||
| API response time | < 100ms |
|
||||
| Page load time | < 2s |
|
||||
|
||||
## 🔐 Security Notes
|
||||
|
||||
**Development Environment Only**
|
||||
|
||||
Current configuration is for development:
|
||||
- SQLite database (use PostgreSQL in production)
|
||||
- Hot reload enabled (disable in production)
|
||||
- Debug logging (reduce in production)
|
||||
- Default JWT secret (change in production)
|
||||
- Ports exposed (use reverse proxy in production)
|
||||
|
||||
**For Production**:
|
||||
1. Use PostgreSQL instead of SQLite
|
||||
2. Set secure JWT_SECRET
|
||||
3. Disable debug mode
|
||||
4. Use production build (not dev server)
|
||||
5. Add reverse proxy (nginx)
|
||||
6. Enable HTTPS
|
||||
7. Set up proper logging
|
||||
8. Configure monitoring
|
||||
|
||||
## 📝 Test Scenarios
|
||||
|
||||
### Scenario 1: Fresh Deployment
|
||||
|
||||
```bash
|
||||
docker compose down -v
|
||||
./test-docker.sh
|
||||
# Expected: All checks pass, can login and see UI
|
||||
```
|
||||
|
||||
### Scenario 2: Code Changes
|
||||
|
||||
```bash
|
||||
# Make code changes in your editor
|
||||
docker compose restart backend # If backend changes
|
||||
docker compose restart frontend # If frontend changes
|
||||
# Expected: Changes reflected due to volume mounts
|
||||
```
|
||||
|
||||
### Scenario 3: Database Reset
|
||||
|
||||
```bash
|
||||
docker compose down -v
|
||||
docker compose up -d
|
||||
docker compose exec backend python seed_data.py
|
||||
# Expected: Fresh database with test users
|
||||
```
|
||||
|
||||
### Scenario 4: Full Rebuild
|
||||
|
||||
```bash
|
||||
docker compose down -v
|
||||
docker compose build --no-cache
|
||||
docker compose up -d
|
||||
# Expected: Clean build with all latest changes
|
||||
```
|
||||
|
||||
## 🎓 Learning Resources
|
||||
|
||||
### Understanding the Architecture
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────┐
|
||||
│ Browser (http://localhost:5173) │
|
||||
└───────────────┬─────────────────────────┘
|
||||
│
|
||||
│ HTTP/WebSocket
|
||||
│
|
||||
┌───────────────▼─────────────────────────┐
|
||||
│ Frontend Container (Vite/React) │
|
||||
│ - Blockchain UI components │
|
||||
│ - Web3 wallet hooks │
|
||||
│ - Gas estimate displays │
|
||||
└───────────────┬─────────────────────────┘
|
||||
│
|
||||
│ API Calls
|
||||
│
|
||||
┌───────────────▼─────────────────────────┐
|
||||
│ Backend Container (FastAPI) │
|
||||
│ - Blockchain services │
|
||||
│ - Oracle system │
|
||||
│ - Web3 integration │
|
||||
│ - SQLite with blockchain fields │
|
||||
└─────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### Blockchain Integration Flow
|
||||
|
||||
```
|
||||
1. User clicks "Create Bet"
|
||||
→ Frontend shows gas estimate
|
||||
|
||||
2. User confirms
|
||||
→ useBlockchainBet hook prepares transaction
|
||||
|
||||
3. MetaMask prompts (would in production)
|
||||
→ User signs transaction
|
||||
|
||||
4. Transaction sent to blockchain (would in production)
|
||||
→ TransactionModal shows progress
|
||||
|
||||
5. Backend indexes event
|
||||
→ blockchain_indexer.py syncs to database
|
||||
|
||||
6. UI updates
|
||||
→ Blockchain badge appears on bet card
|
||||
```
|
||||
|
||||
## 📦 What's Included
|
||||
|
||||
### Smart Contract Documentation
|
||||
- BetEscrow contract design (pseudocode)
|
||||
- BetOracle contract design (pseudocode)
|
||||
- Architecture diagrams
|
||||
- Security model
|
||||
|
||||
### Backend Services
|
||||
- Web3 provider integration
|
||||
- Event indexing system
|
||||
- Oracle node implementation
|
||||
- Consensus aggregator
|
||||
- Network configuration
|
||||
|
||||
### Frontend Integration
|
||||
- MetaMask connection hooks
|
||||
- Transaction management
|
||||
- Gas estimation
|
||||
- Blockchain status badges
|
||||
- Transaction progress modals
|
||||
|
||||
### UI Enhancements
|
||||
- Bet cards with blockchain badges
|
||||
- Create modal with gas estimates
|
||||
- Detail page with transaction flow
|
||||
- Wallet with on-chain section
|
||||
- Header with wallet button
|
||||
|
||||
## 🎉 Success Criteria
|
||||
|
||||
Your Docker deployment is successful when:
|
||||
|
||||
✅ `./test-docker.sh` completes with all checks passing
|
||||
✅ Both containers show "Up" status
|
||||
✅ Can login at http://localhost:5173
|
||||
✅ API docs accessible at http://localhost:8000/docs
|
||||
✅ Blockchain badges visible in UI
|
||||
✅ Connect Wallet button in header
|
||||
✅ Gas estimates show in modals
|
||||
✅ No critical errors in logs
|
||||
✅ All blockchain files present in containers
|
||||
|
||||
## 🚢 Next Steps
|
||||
|
||||
After successful Docker deployment:
|
||||
|
||||
1. **Test Full Workflow**: Create, accept, and settle bets
|
||||
2. **Explore API**: Use Swagger UI at http://localhost:8000/docs
|
||||
3. **Check Logs**: Monitor application behavior
|
||||
4. **Verify UI**: Test all blockchain integration points
|
||||
5. **Review Code**: Examine blockchain service implementations
|
||||
6. **Plan Production**: Review BLOCKCHAIN_IMPLEMENTATION.md for deployment
|
||||
|
||||
## 📞 Support
|
||||
|
||||
If you encounter issues:
|
||||
|
||||
1. Check `DOCKER_EXPECTED_RESULTS.md` for expected output
|
||||
2. Review `DOCKER_TESTING_GUIDE.md` for detailed steps
|
||||
3. Run `./test-docker.sh` for automated diagnostics
|
||||
4. Check logs: `docker compose logs -f`
|
||||
5. Try full rebuild: `docker compose down -v && docker compose build --no-cache`
|
||||
|
||||
---
|
||||
|
||||
**Ready to deploy?** Run `./test-docker.sh` now! 🚀
|
||||
Reference in New Issue
Block a user