Development Setup Guide¶
This guide provides step-by-step instructions for setting up the Federated Learning Platform development environment on your local machine.
Prerequisites¶
System Requirements¶
| Component | Minimum | Recommended |
|---|---|---|
| Operating System | Linux, macOS, Windows 10+ | Ubuntu 20.04+, macOS 12+, Windows 11 |
| RAM | 8 GB | 16 GB+ |
| Storage | 20 GB free space | 50 GB+ SSD |
| CPU | 4 cores | 8+ cores |
| Network | Broadband internet | High-speed internet |
Required Software¶
1. Docker and Docker Compose¶
Docker is essential for containerized development and deployment.
2. Python 3.10+¶
Python is required for the backend services and federated learning components.
3. Node.js 18+¶
Node.js is required for the frontend development.
4. Git¶
Git is required for version control.
Project Setup¶
1. Clone the Repository¶
Expected directory structure:
flip/
├── backend/ # FastAPI backend
├── frontend/ # Next.js frontend
├── fl-core/ # Federated learning core
├── docs/ # Documentation
├── templates/ # ML project templates
├── utils/ # Utility scripts
├── docker-compose.yml
├── README.md
└── setup-*.sh # Setup scripts
2. Environment Configuration¶
Create Environment Files¶
# Backend environment
cat > backend/.env << EOF
# Database Configuration
MONGODB_URL=mongodb://localhost:27017
DATABASE_NAME=federated_learning
# JWT Configuration
SECRET_KEY=your-super-secret-key-change-in-production
ALGORITHM=HS256
ACCESS_TOKEN_EXPIRE_MINUTES=30
# CORS Configuration
ALLOWED_ORIGINS=["http://localhost:4000"]
# OpenTelemetry Configuration
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
OTEL_SERVICE_NAME=fl-backend
# Development Settings
DEBUG=true
LOG_LEVEL=INFO
EOF
# Frontend environment
cat > frontend/.env.local << EOF
# API Configuration
NEXT_PUBLIC_API_URL=http://localhost:8000
NEXT_PUBLIC_WS_URL=ws://localhost:8000
NEXT_PUBLIC_WS_PATH=/nodes/ws
# Development Settings
NODE_ENV=development
NEXT_TELEMETRY_DISABLED=1
EOF
3. Development Environment Setup¶
Option A: Docker Compose (Recommended)¶
# Start all services in development mode
./setup-local-training.sh
# Or manually with Docker Compose
docker-compose --profile orchestrator up -d
# View logs
docker-compose logs -f
# Stop services
docker-compose --profile "*" down
Option B: Local Development¶
Backend Setup:
# Navigate to backend directory
cd backend
# Create virtual environment
python3.10 -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
# Install dependencies
pip install -r requirements.txt
# Start development server
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
Frontend Setup:
# Navigate to frontend directory
cd frontend
# Install dependencies
npm install
# Start development server
npm run dev
MongoDB Setup:
# Using Docker
docker run -d \
--name mongodb \
-p 27017:27017 \
-v mongodb_data:/data/db \
mongo:latest
# Or install locally
# Ubuntu/Debian
sudo apt install mongodb
# macOS
brew install mongodb-community
Development Workflow¶
1. Code Organization¶
graph TB
subgraph "Development Structure"
DEV[Developer Workstation]
subgraph "Local Services"
FRONTEND_DEV[Frontend Dev Server<br/>npm run dev]
BACKEND_DEV[Backend Dev Server<br/>uvicorn --reload]
MONGO_DEV[MongoDB<br/>Local Instance]
end
subgraph "Containerized Services"
DOCKER_SERVICES[Docker Compose<br/>FL Services]
GRAFANA_DEV[Grafana<br/>Monitoring]
TEMPO_DEV[Tempo<br/>Tracing]
end
subgraph "Development Tools"
IDE[VS Code<br/>IDE]
GIT[Git<br/>Version Control]
BROWSER[Browser<br/>DevTools]
end
end
DEV --> FRONTEND_DEV
DEV --> BACKEND_DEV
DEV --> MONGO_DEV
DEV --> DOCKER_SERVICES
DEV --> IDE
FRONTEND_DEV --> BACKEND_DEV
BACKEND_DEV --> MONGO_DEV
BACKEND_DEV --> DOCKER_SERVICES
DOCKER_SERVICES --> GRAFANA_DEV
DOCKER_SERVICES --> TEMPO_DEV2. Hot Reloading Configuration¶
Backend Hot Reloading:
# backend/app/main.py
import os
from fastapi import FastAPI
# Enable auto-reload in development
if os.getenv("DEBUG", "false").lower() == "true":
app = FastAPI(debug=True)
else:
app = FastAPI()
# Start with: uvicorn app.main:app --reload
Frontend Hot Reloading:
// frontend/next.config.ts
const nextConfig = {
// Enable fast refresh
reactStrictMode: true,
// Enable SWC minification
swcMinify: true,
// Development-specific settings
...(process.env.NODE_ENV === 'development' && {
// Disable telemetry in development
telemetry: false,
// Enable experimental features
experimental: {
turbo: true
}
})
}
module.exports = nextConfig
3. Database Seeding¶
# Create database seeder script
cat > backend/seed_database.py << 'EOF'
import asyncio
from app.database.mongodb import MongoDB
from app.database.seeder import seed_database
async def main():
db = MongoDB()
await db.connect("mongodb://localhost:27017", "federated_learning")
await seed_database(db)
await db.close()
if __name__ == "__main__":
asyncio.run(main())
EOF
# Run seeder
cd backend
python seed_database.py
IDE Configuration¶
VS Code Setup¶
Recommended Extensions¶
// .vscode/extensions.json
{
"recommendations": [
"ms-python.python",
"ms-python.black-formatter",
"ms-python.pylint",
"bradlc.vscode-tailwindcss",
"esbenp.prettier-vscode",
"ms-vscode.vscode-typescript-next",
"ms-azuretools.vscode-docker",
"redhat.vscode-yaml",
"ms-vscode.vscode-json"
]
}
Workspace Settings¶
// .vscode/settings.json
{
"python.defaultInterpreterPath": "./backend/venv/bin/python",
"python.formatting.provider": "black",
"python.linting.enabled": true,
"python.linting.pylintEnabled": true,
"editor.formatOnSave": true,
"editor.codeActionsOnSave": {
"source.organizeImports": true
},
"typescript.preferences.importModuleSpecifier": "relative",
"tailwindCSS.includeLanguages": {
"typescript": "javascript",
"typescriptreact": "javascript"
},
"files.associations": {
"*.yml": "yaml",
"*.yaml": "yaml",
"Dockerfile*": "dockerfile"
}
}
Debug Configuration¶
// .vscode/launch.json
{
"version": "0.2.0",
"configurations": [
{
"name": "FastAPI Backend",
"type": "python",
"request": "launch",
"program": "${workspaceFolder}/backend/venv/bin/uvicorn",
"args": ["app.main:app", "--reload", "--host", "0.0.0.0", "--port", "8000"],
"cwd": "${workspaceFolder}/backend",
"env": {
"PYTHONPATH": "${workspaceFolder}/backend"
},
"console": "integratedTerminal"
},
{
"name": "Next.js Frontend",
"type": "node",
"request": "launch",
"program": "${workspaceFolder}/frontend/node_modules/.bin/next",
"args": ["dev"],
"cwd": "${workspaceFolder}/frontend",
"console": "integratedTerminal"
}
]
}
Testing Setup¶
Backend Testing¶
# Install test dependencies
cd backend
pip install pytest pytest-asyncio httpx
# Create test configuration
cat > pytest.ini << EOF
[tool:pytest]
testpaths = tests
python_files = test_*.py
python_classes = Test*
python_functions = test_*
asyncio_mode = auto
EOF
# Run tests
pytest tests/ -v
Frontend Testing¶
# Install test dependencies
cd frontend
npm install --save-dev jest @testing-library/react @testing-library/jest-dom
# Create test configuration
cat > jest.config.js << EOF
const nextJest = require('next/jest')
const createJestConfig = nextJest({
dir: './',
})
const customJestConfig = {
setupFilesAfterEnv: ['<rootDir>/jest.setup.js'],
moduleNameMapping: {
'^@/components/(.*)$': '<rootDir>/components/$1',
'^@/pages/(.*)$': '<rootDir>/pages/$1',
},
testEnvironment: 'jest-environment-jsdom',
}
module.exports = createJestConfig(customJestConfig)
EOF
# Run tests
npm test
Common Development Tasks¶
1. Adding New Dependencies¶
Backend:
Frontend:
2. Database Migrations¶
# backend/migrations/001_initial_setup.py
async def migrate_up(db):
# Create indexes
await db.users.create_index("username", unique=True)
await db.users.create_index("email", unique=True)
# Create initial admin user
admin_user = {
"username": "admin",
"email": "admin@example.com",
"password_hash": get_password_hash("admin123"),
"roles": ["admin", "user"],
"created_at": datetime.utcnow()
}
await db.users.insert_one(admin_user)
async def migrate_down(db):
# Rollback changes
await db.users.drop_index("username")
await db.users.drop_index("email")
await db.users.delete_one({"username": "admin"})
3. Environment Switching¶
# Development environment
export NODE_ENV=development
export DEBUG=true
# Production environment
export NODE_ENV=production
export DEBUG=false
# Test environment
export NODE_ENV=test
export DATABASE_NAME=federated_learning_test
Troubleshooting¶
Common Issues¶
Port Conflicts¶
# Check what's using a port
lsof -i :8000
netstat -tulpn | grep :8000
# Kill process using port
kill -9 $(lsof -t -i:8000)
Docker Issues¶
# Clean up Docker
docker system prune -a
docker volume prune
# Rebuild containers
docker-compose build --no-cache
docker-compose up -d
Permission Issues¶
# Fix Docker permissions (Linux)
sudo usermod -aG docker $USER
newgrp docker
# Fix file permissions
sudo chown -R $USER:$USER .
Node.js Issues¶
# Clear npm cache
npm cache clean --force
# Remove node_modules and reinstall
rm -rf node_modules package-lock.json
npm install
Development Logs¶
# View all service logs
docker-compose logs -f
# View specific service logs
docker-compose logs -f backend-fastapi
docker-compose logs -f frontend
# Backend application logs
tail -f backend/logs/app.log
# Frontend development logs
npm run dev 2>&1 | tee frontend/logs/dev.log
Next: Continue to Environment Configuration for detailed environment setup and configuration management.