Local Development Setup
Prerequisites
- Docker & Docker Compose
- Node.js 18+ (for frontend hot-reload outside Docker)
- Git
1. Clone the Repository
git clone git@gitlab.com:zsaidov1988/educenter-platform.git
cd mvp-v2
2. Configure Environment
cp backend/.env.example backend/.env
Minimum required settings in backend/.env:
DATABASE_URL=postgresql+asyncpg://platform:platform@postgres:5432/platform
REDIS_URL=redis://redis:6379/0
SECRET_KEY=dev-secret-key-change-in-production
ADMIN_USERNAME=admin
ADMIN_PASSWORD=admin123
CORS_ORIGINS=http://localhost:5173
3. Start Services
docker-compose up -d
docker-compose ps # verify all containers are healthy
4. Initialize Database
# Apply all migrations
docker-compose exec backend alembic upgrade head
# Seed admin user and sample data
docker-compose exec backend python -m app.db.init_db
5. Start Frontend
# Outside Docker — recommended for hot-reload
cd frontend
npm install
npm run dev
# → http://localhost:5173
Access Points
| Service | URL |
|---|---|
| Frontend | http://localhost:5173 |
| Backend API | http://localhost:8000 |
| Swagger UI | http://localhost:8000/docs |
Default Credentials
| Role | Username | Password |
|---|---|---|
| Admin | admin | value of ADMIN_PASSWORD in .env |
| Student | student | student123 |
Common Commands
make up # Start all services
make down # Stop all services
make logs # Tail all service logs
make logs-backend # Tail backend only
make shell # Open bash in backend container
make restart # Restart backend after code changes
make migrate-up # Apply pending migrations
make migrate-new msg="add_feature" # Create new Alembic migration
make migrate-current # Show current migration version
make db-seed # Re-seed initial data
make test # Run pytest suite
make test-v # Verbose output
make smoke-test-local # Smoke test against localhost:8000
Run make help to see all available targets.
Troubleshooting
Backend won't start
docker-compose logs backend
# Check for missing env vars or migration errors
Migration fails
docker-compose exec backend alembic current
docker-compose exec backend alembic history
Frontend can't reach API
Verify VITE_API_URL in frontend/.env:
VITE_API_URL=http://localhost:8000
LXD not reachable
LXD runs on a separate server (65.109.236.163). For local dev, sandbox and exam features require the LXD certificates in backend/.lxd/ and network access to the LXD host. See LXD Architecture for details.