Spaces:
Runtime error
Download docs/MIGRATION_GUIDE.md from junaidte14/django-admin-dashboard: direct link, hf CLI and curl.
- Browser
- Download file 8.4 kB
-
https://huggingface.co/spaces/junaidte14/django-admin-dashboard/resolve/main/docs/MIGRATION_GUIDE.md
- Command line
-
hf download hf://spaces/junaidte14/django-admin-dashboard/docs/MIGRATION_GUIDE.md
-
curl -L -o MIGRATION_GUIDE.md https://huggingface.co/spaces/junaidte14/django-admin-dashboard/resolve/main/docs/MIGRATION_GUIDE.md
Migration Guide: React Admin to Django Admin
Overview
This guide helps you migrate from the React-based admin dashboard to the Django-based admin dashboard without disrupting your FastAPI backend.
Before You Start
β What stays the same:
- FastAPI backend (no changes needed)
- Database schema (Django reads from existing tables)
- API endpoints (remain unchanged)
- User authentication in FastAPI (JWT still works)
β What changes:
- Admin interface moves from React (port 3000) to Django (port 8001)
- Session-based auth for admin dashboard (separate from API JWT)
- Server-side rendering instead of SPA
Migration Steps
Phase 1: Setup Django Admin (No Downtime)
1. Install Django admin alongside existing React app:
# In your project root
cd backend/
git clone <django-admin-repo> django_admin
cd django_admin
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt
2. Configure environment:
cp .env.example .env
# Edit .env with your existing database credentials
nano .env
3. Create Django superuser:
python manage.py createsuperuser
# Use same credentials as your existing admin user
4. Start Django admin (different port):
python manage.py runserver 8001
5. Test in parallel:
- React Admin: http://localhost:3000/admin
- Django Admin: http://localhost:8001/
- FastAPI: http://localhost:8000/api/v1
Both admin interfaces work simultaneously!
Phase 2: Data Verification
Verify Django can read all data:
python manage.py shell
from apps.core.models import User, Conversation, Message, Agent
# Check data
print(f"Users: {User.objects.count()}")
print(f"Conversations: {Conversation.objects.count()}")
print(f"Messages: {Message.objects.count()}")
print(f"Agents: {Agent.objects.count()}")
# Test a query
user = User.objects.first()
print(f"First user: {user.username}")
Phase 3: User Migration
Map existing users to Django admin access:
# In Django shell
from apps.core.models import User
# Option 1: Grant admin access to specific users
admin_usernames = ['admin', 'john', 'jane']
for username in admin_usernames:
try:
user = User.objects.get(username=username)
user.is_staff = True
user.role = 'admin'
user.save()
print(f"β Granted admin access to {username}")
except User.DoesNotExist:
print(f"β User {username} not found")
# Option 2: Grant admin access to all existing admins
admins = User.objects.filter(role='admin')
admins.update(is_staff=True)
print(f"β Granted access to {admins.count()} admins")
Phase 4: Update Nginx Configuration
Current setup (React + FastAPI):
location /admin/ {
# React admin
proxy_pass http://localhost:3000;
}
location /api/ {
# FastAPI
proxy_pass http://localhost:8000;
}
New setup (Django + FastAPI):
location /admin/ {
# Django admin dashboard
proxy_pass http://localhost:8001;
}
location /api/ {
# FastAPI (unchanged)
proxy_pass http://localhost:8000;
}
location /static/ {
# Django static files
alias /path/to/django_admin/staticfiles/;
}
Phase 5: Cutover
Zero-downtime cutover:
- Update Nginx config:
sudo nano /etc/nginx/sites-available/your-site
# Update proxy_pass for /admin/ to point to 8001
sudo nginx -t
sudo systemctl reload nginx
- Deploy Django admin service:
sudo systemctl enable django-admin
sudo systemctl start django-admin
- Verify:
curl http://localhost:8001/
# Should return Django login page
- Stop React admin (after confirming Django works):
# Stop React dev server or PM2 process
pm2 stop react-admin
Phase 6: Cleanup (Optional)
After confirming Django admin works for 1-2 weeks:
# Archive React admin code
cd frontend/
tar -czf react-admin-backup-$(date +%Y%m%d).tar.gz admin/
rm -rf admin/
# Remove from package.json if needed
npm uninstall @tanstack/react-query recharts lucide-react
Feature Mapping
React Components β Django Templates
| React Component | Django Equivalent | Status |
|---|---|---|
AdminPanel.tsx |
templates/dashboard/home.html |
β Ready |
AnalyticsDashboard.tsx |
apps/analytics/views.py |
β Ready |
UserManagement.tsx |
templates/dashboard/users.html |
β Ready |
adminListConversations.tsx |
templates/dashboard/conversations.html |
β Ready |
RAGManager.tsx |
templates/rag/collections.html |
β Ready |
AgentList.tsx |
templates/agents/list.html |
β Ready |
Settings.tsx |
templates/dashboard/settings.html |
β Ready |
API Calls
React made direct API calls to FastAPI:
await apiService.adminListConversations(offset, limit);
Django also calls FastAPI (via httpx):
async with httpx.AsyncClient() as client:
response = await client.get(f"{FASTAPI_BASE_URL}/conversations")
No changes needed in FastAPI!
Testing Checklist
- Can login to Django admin
- Dashboard shows correct statistics
- User list displays all users
- Can view conversations
- RAG collections are visible
- Agents list shows all agents
- Can create/edit/delete resources
- Charts render correctly
- Pagination works
- Search/filters work
- Mobile responsive
Rollback Plan
If issues occur, rollback is simple:
1. Revert Nginx:
# Change proxy_pass back to React (port 3000)
sudo nano /etc/nginx/sites-available/your-site
sudo nginx -t
sudo systemctl reload nginx
2. Restart React admin:
cd frontend/admin
npm start
# or
pm2 start react-admin
3. Stop Django admin:
sudo systemctl stop django-admin
Everything returns to previous state in ~2 minutes.
Common Issues & Solutions
Issue: "User not found" on login
Solution: User needs is_staff=True or role='admin'
user = User.objects.get(username='john')
user.is_staff = True
user.save()
Issue: Static files not loading
Solution: Collect static files
python manage.py collectstatic --noinput
Issue: Can't connect to database
Solution: Check credentials match FastAPI
psql -h localhost -U postgres -d chatbot_db
# If this works, Django should work too
Issue: Charts not rendering
Solution: Check Chart.js loaded
<!-- Should be in base.html -->
<script src="https://cdn.jsdelivr.net/npm/chart.js@4.4.0/dist/chart.umd.min.js"></script>
Issue: FastAPI endpoints timing out
Solution: Increase timeout in Django settings
# settings.py
FASTAPI_TIMEOUT = 60 # seconds
Performance Comparison
| Metric | React Admin | Django Admin |
|---|---|---|
| Initial Load | ~2-3s (SPA bundle) | ~500ms (SSR) |
| Page Navigation | ~100ms (client) | ~200ms (server) |
| Data Refresh | Real-time | Cache (5min) |
| Memory Usage | ~150MB (browser) | ~50MB (server) |
| Mobile Performance | Good | Excellent |
Docker Migration
If using Docker, update docker-compose.yml:
services:
# Remove React admin service
# react_admin:
# build: ./frontend/admin
# ports:
# - "3000:3000"
# Add Django admin service
django_admin:
build: ./backend/django_admin
ports:
- "8001:8001"
depends_on:
- postgres
- fastapi
Post-Migration
Monitor for 1 week:
- Check error logs:
tail -f logs/django.log - Monitor response times
- Gather user feedback
- Watch for any missing features
After 2 weeks of stable operation:
- Remove React admin code
- Update documentation
- Archive old configs
- Celebrate! π
Need Help?
Common commands:
# Check Django admin status
sudo systemctl status django-admin
# View logs
tail -f logs/django.log
journalctl -u django-admin -f
# Restart Django admin
sudo systemctl restart django-admin
# Check database connection
python manage.py dbshell
# Clear cache
python manage.py shell
>>> from django.core.cache import cache
>>> cache.clear()
Conclusion
This migration:
- β Zero downtime possible
- β Easy rollback
- β No FastAPI changes
- β No database changes
- β Better performance
- β Easier maintenance
- β Production-ready from day 1