Initial commit of mtgonline project

HYBRID_SETUP.md

@@ -0,0 +1,244 @@
+# Hybrid Development Setup Guide
+
+## Prerequisites
+
+1. **Docker** (for PostgreSQL and Redis)
+   - Install: https://docs.docker.com/get-docker/
+
+2. **Python 3.12+** (for backend)
+   - Install: https://www.python.org/downloads/
+
+3. **Node.js 18+** (for frontend, Phase 2)
+   - Install: https://nodejs.org/
+
+## Setup Steps
+
+### 1. Start Database Services with Docker
+
+```bash
+# Navigate to project root
+cd /home/user/wall-o/cockatrice-web
+
+# Start PostgreSQL and Redis
+docker compose -f docker-compose.dev.yml up -d
+
+# Verify they're running
+docker compose -f docker-compose.dev.yml ps
+```
+
+**Expected output:**
+```
+NAME                  STATUS        PORTS
+cockatrice-web-postgres-1   Up   0.0.0.0:5432->5432/tcp
+cockatrice-web-redis-1      Up   0.0.0.0:6379->6379/tcp
+```
+
+### 2. Create Virtual Environment and Install Backend Dependencies
+
+```bash
+# Navigate to backend directory
+cd backend
+
+# Create virtual environment
+python -m venv venv
+
+# Activate virtual environment
+# Linux/Mac:
+source venv/bin/activate
+# Windows:
+venv\Scripts\activate
+
+# Install dependencies
+pip install -r requirements.txt
+```
+
+### 3. Configure Environment
+
+```bash
+# Copy example environment file
+cp .env.example .env
+
+# Edit .env with your configuration
+# The defaults in .env.example should work for local development
+```
+
+### 4. Verify Database Connection
+
+```bash
+# Test database connection
+python -c "
+import asyncio
+from app.core.database import async_engine
+
+async def test_connection():
+    async with async_engine.connect() as conn:
+        result = await conn.execute('SELECT 1')
+        print('Database connection successful!')
+
+asyncio.run(test_connection())
+"
+```
+
+### 5. Start the Backend Server
+
+```bash
+# With hot-reload for development
+uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
+
+# Or without reload (faster startup)
+uvicorn app.main:app --host 0.0.0.0 --port 8000
+```
+
+**Backend will be available at:**
+- API: http://localhost:8000
+- Swagger Docs: http://localhost:8000/docs
+- ReDoc: http://localhost:8000/redoc
+
+### 6. Run Tests (Optional but Recommended)
+
+```bash
+# Install test dependencies
+pip install pytest pytest-asyncio aiosqlite
+
+# Run tests
+pytest
+
+# Run with coverage
+pytest --cov=app --cov-report=html
+```
+
+### 7. Stop Services When Done
+
+```bash
+# Stop Docker services
+cd /home/user/wall-o/cockatrice-web
+docker compose -f docker-compose.dev.yml down
+
+# Deactivate virtual environment (if in backend directory)
+deactivate
+```
+
+## Troubleshooting
+
+### Port Already in Use
+
+If port 5432 or 6379 is already in use:
+
+```bash
+# Find what's using the port
+lsof -i :5432
+lsof -i :6379
+
+# Kill the process (be careful!)
+kill -9 <PID>
+
+# Or change ports in docker-compose.dev.yml
+```
+
+### Database Connection Issues
+
+```bash
+# Check if PostgreSQL is running
+docker compose -f docker-compose.dev.yml logs postgres
+
+# Restart if needed
+docker compose -f docker-compose.dev.yml restart postgres
+
+# Check environment variables
+echo $DATABASE_URL
+```
+
+### Python Dependencies
+
+```bash
+# If you get import errors
+pip install -r requirements.txt --upgrade
+
+# Check installed packages
+pip list
+```
+
+## Development Workflow
+
+### Daily Development
+
+```bash
+# 1. Start database services
+docker compose -f docker-compose.dev.yml up -d
+
+# 2. Activate backend environment
+cd backend
+source venv/bin/activate
+
+# 3. Start backend (in one terminal)
+uvicorn app.main:app --reload
+
+# 4. Start frontend (in another terminal, Phase 2)
+cd frontend
+npm run dev
+```
+
+### After Code Changes
+
+- **Backend changes**: Hot-reload automatically restarts the server
+- **Frontend changes**: Hot-reload automatically refreshes the browser
+- **Database changes**: Restart the backend server
+
+### Database Schema Changes
+
+When you modify models in `app/models/models.py`:
+
+1. Update the models
+2. Stop and restart the backend server
+3. For production, you'll need Alembic migrations (not set up yet)
+
+## Security Notes
+
+⚠️ **Important for Production:**
+
+- Change `JWT_SECRET_KEY` in `.env` to a strong random string
+- Use HTTPS in production
+- Set `DEBUG=False`
+- Configure proper CORS origins
+- Use environment variables for secrets (not `.env` file)
+
+## Next Steps
+
+- ✅ Set up hybrid development environment
+- ⏳ Run database migration setup (Alembic)
+- ⏳ Test all API endpoints
+- ⏳ Begin Phase 2: Frontend development
+
+## Useful Commands
+
+```bash
+# Check Docker status
+docker compose -f docker-compose.dev.yml ps
+
+# View Docker logs
+docker compose -f docker-compose.dev.yml logs -f
+
+# Stop and remove containers
+docker compose -f docker-compose.dev.yml down
+
+# Restart specific service
+docker compose -f docker-compose.dev.yml restart postgres
+
+# Check backend health
+curl http://localhost:8000/health
+
+# Check API docs
+open http://localhost:8000/docs
+```
+
+## Support
+
+If you encounter issues:
+1. Check the logs: `docker compose -f docker-compose.dev.yml logs`
+2. Verify environment variables: `echo $DATABASE_URL`
+3. Test database connection manually
+4. Check if ports are available: `lsof -i :5432`
+
+---
+
+**Status:** Hybrid development environment ready for use!