245 lines
4.9 KiB
Markdown
245 lines
4.9 KiB
Markdown
# 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/mtgonline-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
|
|
mtgonline-web-postgres-1 Up 0.0.0.0:5432->5432/tcp
|
|
mtgonline-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/mtgonline-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!
|