first working version
This commit is contained in:
howard
254
exam_system/SETUP.md
Normal file
254
exam_system/SETUP.md
Normal file
@@ -0,0 +1,254 @@
|
||||
# Exam System - Complete Setup Guide
|
||||
|
||||
## ✅ System Overview
|
||||
|
||||
A complete exam system with:
|
||||
- **exam_server**: Django REST API backend
|
||||
- **exam_web**: Angular SPA frontend
|
||||
- **nginx**: Reverse proxy
|
||||
- **data**: File-based storage for exams, attempts, and results
|
||||
|
||||
## 📁 Project Structure
|
||||
|
||||
```
|
||||
exam_system/
|
||||
├── exam_server/ # Django backend
|
||||
│ ├── manage.py
|
||||
│ ├── exam_server/ # Django project
|
||||
│ │ ├── settings.py
|
||||
│ │ ├── urls.py
|
||||
│ │ └── wsgi.py
|
||||
│ ├── api/ # API app
|
||||
│ │ ├── views.py
|
||||
│ │ ├── urls.py
|
||||
│ │ └── storage.py
|
||||
│ ├── Dockerfile
|
||||
│ └── requirements.txt
|
||||
│
|
||||
├── exam_web/ # Angular frontend
|
||||
│ ├── src/
|
||||
│ │ ├── app/
|
||||
│ │ │ ├── components/
|
||||
│ │ │ │ ├── exam-list/
|
||||
│ │ │ │ ├── exam-player/
|
||||
│ │ │ │ └── exam-done/
|
||||
│ │ │ ├── services/
|
||||
│ │ │ │ └── api.service.ts
|
||||
│ │ │ ├── app.module.ts
|
||||
│ │ │ └── app-routing.module.ts
|
||||
│ │ ├── index.html
|
||||
│ │ └── main.ts
|
||||
│ ├── angular.json
|
||||
│ ├── package.json
|
||||
│ └── Dockerfile
|
||||
│
|
||||
├── data/ # File-based storage
|
||||
│ ├── input/ # Exam JSON files
|
||||
│ │ └── python-basics-v1.json
|
||||
│ ├── attempts/ # Active attempts
|
||||
│ ├── output/ # Final bundles
|
||||
│ ├── progress/ # Progress snapshots
|
||||
│ └── manifest.json # Exam registry
|
||||
│
|
||||
├── nginx.conf # Nginx config
|
||||
├── Dockerfile.nginx # Nginx Dockerfile
|
||||
├── docker-compose.yml # Docker orchestration
|
||||
└── README.md
|
||||
```
|
||||
|
||||
## 🚀 Quick Start
|
||||
|
||||
### 1. Start the System
|
||||
|
||||
```bash
|
||||
cd exam_system
|
||||
docker-compose up --build
|
||||
```
|
||||
|
||||
This starts three services:
|
||||
- **exam_server**: Django API on port 8000 (internal)
|
||||
- **exam_web**: Angular app on port 4200 (internal)
|
||||
- **nginx**: Reverse proxy on port 80 (external)
|
||||
|
||||
### 2. Access the Application
|
||||
|
||||
Open your browser to: **http://localhost**
|
||||
|
||||
You should see the exam list with "Python Basics Exam" available.
|
||||
|
||||
### 3. Test the Flow
|
||||
|
||||
1. Click "Start Exam" on the Python Basics exam
|
||||
2. Answer the questions (multiple choice, true/false, essay, code)
|
||||
3. The system autosaves every 10 seconds
|
||||
4. Submit when done
|
||||
5. Check `data/output/` for the bundled result JSON
|
||||
|
||||
## 🔧 Development
|
||||
|
||||
### Backend (Django)
|
||||
|
||||
```bash
|
||||
# Shell access
|
||||
docker-compose exec exam_server bash
|
||||
|
||||
# Run migrations
|
||||
docker-compose exec exam_server python manage.py migrate
|
||||
|
||||
# Create superuser for admin
|
||||
docker-compose exec exam_server python manage.py createsuperuser
|
||||
|
||||
# Access admin
|
||||
http://localhost/admin
|
||||
```
|
||||
|
||||
### Frontend (Angular)
|
||||
|
||||
```bash
|
||||
# Shell access
|
||||
docker-compose exec exam_web sh
|
||||
|
||||
# Install new packages
|
||||
docker-compose exec exam_web npm install <package>
|
||||
|
||||
# View logs
|
||||
docker-compose logs -f exam_web
|
||||
```
|
||||
|
||||
### Add a New Exam
|
||||
|
||||
1. Create exam JSON in `data/input/your-exam.json` following the format in `docs/exam-format.md`
|
||||
|
||||
2. Update `data/manifest.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"version": "1.0.0",
|
||||
"exams": [
|
||||
{
|
||||
"examId": "your-exam",
|
||||
"path": "input/your-exam.json",
|
||||
"published": true,
|
||||
"version": "1.0.0"
|
||||
}
|
||||
],
|
||||
"users": {}
|
||||
}
|
||||
```
|
||||
|
||||
3. Refresh the browser - the new exam will appear
|
||||
|
||||
## 📊 Data Flow
|
||||
|
||||
1. **Exam Load**: Angular calls `/api/exams/` → Django reads `data/input/` and `manifest.json`
|
||||
2. **Start Exam**: POST `/api/exams/{id}/attempt/` → Creates attempt in `data/attempts/{userId}/{examId}/`
|
||||
3. **Autosave**: PUT `/api/attempts/{id}/autosave/` → Updates attempt JSON every 10 seconds
|
||||
4. **Submit**: POST `/api/attempts/{id}/submit/` → Creates bundle in `data/output/{examId}_{attemptId}.json`
|
||||
|
||||
## 🧪 Testing
|
||||
|
||||
### Test with Sample Exam
|
||||
|
||||
The system comes with a sample Python exam. To test:
|
||||
|
||||
1. Start the system: `docker-compose up`
|
||||
2. Go to http://localhost
|
||||
3. Click "Start Exam" on "Python Basics Exam"
|
||||
4. Answer a few questions
|
||||
5. Wait for autosave (watch for "Saved" status)
|
||||
6. Submit the exam
|
||||
7. Check `data/attempts/` and `data/output/` for saved files
|
||||
|
||||
### Verify API Endpoints
|
||||
|
||||
```bash
|
||||
# List exams
|
||||
curl http://localhost/api/exams/
|
||||
|
||||
# Health check
|
||||
curl http://localhost/api/health/
|
||||
```
|
||||
|
||||
## 🐛 Troubleshooting
|
||||
|
||||
### Port 80 Already in Use
|
||||
|
||||
Edit `docker-compose.yml`:
|
||||
```yaml
|
||||
nginx:
|
||||
ports:
|
||||
- "8080:80" # Change from 80:80
|
||||
```
|
||||
|
||||
Then access via http://localhost:8080
|
||||
|
||||
### Container Won't Start
|
||||
|
||||
```bash
|
||||
# Check logs
|
||||
docker-compose logs exam_server
|
||||
docker-compose logs exam_web
|
||||
docker-compose logs nginx
|
||||
|
||||
# Rebuild from scratch
|
||||
docker-compose down -v
|
||||
docker-compose up --build
|
||||
```
|
||||
|
||||
### Permission Errors on Data Folder
|
||||
|
||||
```bash
|
||||
chmod -R 755 data/
|
||||
```
|
||||
|
||||
### Angular Build Issues
|
||||
|
||||
```bash
|
||||
# Clear node_modules and rebuild
|
||||
docker-compose down
|
||||
rm -rf exam_web/node_modules
|
||||
docker-compose up --build
|
||||
```
|
||||
|
||||
## 📝 Question Types Supported
|
||||
|
||||
1. **single_choice**: Multiple choice with one correct answer
|
||||
2. **true_false**: Boolean questions
|
||||
3. **essay**: Open-ended text responses
|
||||
4. **code_simple**: Simple coding problems
|
||||
5. **code_exercise**: Complex coding exercises with test cases
|
||||
|
||||
See `docs/exam-format.md` for complete format specification.
|
||||
|
||||
## 🔐 Security Notes
|
||||
|
||||
- This is a development setup. For production:
|
||||
- Change `SECRET_KEY` in `exam_server/env.example`
|
||||
- Set `DEBUG=False`
|
||||
- Use HTTPS with proper SSL certificates
|
||||
- Add authentication/authorization
|
||||
- Secure file permissions on data folder
|
||||
|
||||
## 📚 Documentation
|
||||
|
||||
- `docs/exam-format.md` - Exam JSON format specification
|
||||
- `docs/stack-architecture.md` - System architecture
|
||||
- `docs/django-backend-spec.md` - Backend API details
|
||||
- `docs/angular-frontend-spec.md` - Frontend behavior
|
||||
- `docs/json-io-and-state.md` - State machine and file structure
|
||||
|
||||
## 🎯 Next Steps
|
||||
|
||||
1. Create your own exam JSON files
|
||||
2. Customize the Angular UI styling
|
||||
3. Add grading/scoring logic
|
||||
4. Implement user authentication
|
||||
5. Deploy to production
|
||||
|
||||
## 💡 Tips
|
||||
|
||||
- Use the sample exam as a template for creating new exams
|
||||
- The system autosaves every 10 seconds, so progress is never lost
|
||||
- Check `data/output/` for submitted exam bundles
|
||||
- All data is stored as JSON files for easy inspection and backup
|
||||
|
||||
Reference in New Issue
Block a user