mtgonline/HYBRID_SETUP.md

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

# 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

# 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

# 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

# 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

# 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)

# 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

# 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:

# 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

# 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

# If you get import errors
pip install -r requirements.txt --upgrade

# Check installed packages
pip list

Development Workflow

Daily Development

# 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

# 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!