Spaces:
Runtime error
Runtime error
|
Download docs/README.md from junaidte14/django-admin-dashboard: direct link, hf CLI and curl.
- Browser
- Download file 13.7 kB
-
https://huggingface.co/spaces/junaidte14/django-admin-dashboard/resolve/main/docs/README.md
- Command line
-
hf download hf://spaces/junaidte14/django-admin-dashboard/docs/README.md
-
curl -L -o README.md https://huggingface.co/spaces/junaidte14/django-admin-dashboard/resolve/main/docs/README.md
13.7 kB
| # Django Admin Dashboard - Setup & Deployment Guide | |
| ## Quick Start | |
| ### 1. Prerequisites | |
| ```bash | |
| # System requirements | |
| - Python 3.11+ | |
| - PostgreSQL 14+ | |
| - Redis 7+ | |
| - Node.js 18+ (for Tailwind CSS compilation in production) | |
| ``` | |
| ### 2. Installation | |
| ```bash | |
| # Clone or navigate to project | |
| cd django_admin_backend | |
| # Create virtual environment | |
| python -m venv venv | |
| source venv/bin/activate # On Windows: venv\Scripts\activate | |
| # Install dependencies | |
| pip install -r requirements.txt | |
| # Copy environment file | |
| cp .env.example .env | |
| # Edit .env with your database credentials | |
| nano .env | |
| ``` | |
| ### 3. Database Setup | |
| ```bash | |
| # The Django admin uses the SAME database as your FastAPI app | |
| # No need to create a new database | |
| # Create Django tables (managed models only - won't touch FastAPI tables) | |
| python manage.py migrate | |
| # Create superuser for Django admin | |
| python manage.py createsuperuser | |
| ``` | |
| ### 4. Create Required Directories | |
| ```bash | |
| mkdir -p logs staticfiles media | |
| ``` | |
| ### 5. Run Development Server | |
| ```bash | |
| # Start Django admin dashboard | |
| python manage.py runserver 8001 | |
| # In another terminal, start your FastAPI app | |
| cd ../fastapi_app | |
| uvicorn main:app --reload --port 8000 | |
| ``` | |
| Now access: | |
| - **Admin Dashboard**: http://localhost:8001/ | |
| - **Django Admin**: http://localhost:8001/admin/ | |
| - **FastAPI**: http://localhost:8000/api/v1/ | |
| --- | |
| ## Project Structure | |
| ``` | |
| django_admin_backend/ | |
| βββ manage.py | |
| βββ requirements.txt | |
| βββ .env | |
| βββ .env.example | |
| β | |
| βββ config/ # Django configuration | |
| β βββ settings.py | |
| β βββ urls.py | |
| β βββ wsgi.py | |
| β | |
| βββ apps/ | |
| β βββ core/ # Core models & auth | |
| β β βββ models.py # User, Conversation, Message, etc. | |
| β β βββ admin.py # Django admin config | |
| β β βββ views.py # Auth views | |
| β β βββ urls/ | |
| β β βββ auth.py | |
| β β | |
| β βββ dashboard/ # Main dashboard | |
| β β βββ views.py | |
| β β βββ urls.py | |
| β β | |
| β βββ analytics/ # Analytics module | |
| β β βββ views.py | |
| β β βββ urls.py | |
| β β | |
| β βββ rag/ # RAG management | |
| β β βββ views.py | |
| β β βββ urls.py | |
| β β | |
| β βββ agents/ # Agent management | |
| β βββ views.py | |
| β βββ urls.py | |
| β | |
| βββ templates/ # HTML templates | |
| β βββ base.html | |
| β βββ auth/ | |
| β β βββ login.html | |
| β βββ dashboard/ | |
| β β βββ home.html | |
| β β βββ users.html | |
| β β βββ conversations.html | |
| β βββ rag/ | |
| β β βββ collections.html | |
| β βββ agents/ | |
| β βββ list.html | |
| β βββ detail.html | |
| β | |
| βββ static/ # Static files (CSS, JS, images) | |
| βββ staticfiles/ # Collected static files (production) | |
| βββ media/ # User uploads | |
| βββ logs/ # Application logs | |
| ``` | |
| --- | |
| ## Configuration | |
| ### Database Settings | |
| Django reads from the **same PostgreSQL database** as FastAPI. The models are defined as `managed = False`, meaning Django will: | |
| - β Read data from existing tables | |
| - β Write new data to tables | |
| - β NOT create or modify table schemas | |
| ### Environment Variables | |
| ```bash | |
| # Required | |
| SECRET_KEY= # Generate with: python -c "from django.core.management.utils import get_random_secret_key; print(get_random_secret_key())" | |
| DB_NAME= # Same as FastAPI | |
| DB_USER= # Same as FastAPI | |
| DB_PASSWORD= # Same as FastAPI | |
| DB_HOST= # Usually localhost | |
| DB_PORT= # Usually 5432 | |
| # Optional | |
| DEBUG=False # Set to False in production | |
| REDIS_URL= # For caching | |
| FASTAPI_BASE_URL= # For calling FastAPI endpoints | |
| SENTRY_DSN= # For error tracking | |
| ``` | |
| --- | |
| ## Production Deployment | |
| ### Option 1: Separate Server (Recommended) | |
| #### Nginx Configuration | |
| ```nginx | |
| # /etc/nginx/sites-available/admin-dashboard | |
| # FastAPI | |
| server { | |
| listen 80; | |
| server_name api.yourdomain.com; | |
| location /api/v1/ { | |
| proxy_pass http://127.0.0.1:8000; | |
| proxy_set_header Host $host; | |
| proxy_set_header X-Real-IP $remote_addr; | |
| proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; | |
| } | |
| } | |
| # Django Admin Dashboard | |
| server { | |
| listen 80; | |
| server_name admin.yourdomain.com; | |
| location /static/ { | |
| alias /var/www/django_admin/staticfiles/; | |
| expires 30d; | |
| } | |
| location /media/ { | |
| alias /var/www/django_admin/media/; | |
| expires 7d; | |
| } | |
| location / { | |
| proxy_pass http://127.0.0.1:8001; | |
| proxy_set_header Host $host; | |
| proxy_set_header X-Real-IP $remote_addr; | |
| proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; | |
| proxy_set_header X-Forwarded-Proto $scheme; | |
| } | |
| } | |
| ``` | |
| #### Systemd Service Files | |
| **FastAPI Service** (`/etc/systemd/system/fastapi.service`): | |
| ```ini | |
| [Unit] | |
| Description=FastAPI Application | |
| After=network.target | |
| [Service] | |
| User=www-data | |
| Group=www-data | |
| WorkingDirectory=/var/www/fastapi_app | |
| Environment="PATH=/var/www/fastapi_app/venv/bin" | |
| ExecStart=/var/www/fastapi_app/venv/bin/uvicorn main:app --host 0.0.0.0 --port 8000 --workers 4 | |
| [Install] | |
| WantedBy=multi-user.target | |
| ``` | |
| **Django Admin Service** (`/etc/systemd/system/django-admin.service`): | |
| ```ini | |
| [Unit] | |
| Description=Django Admin Dashboard | |
| After=network.target | |
| [Service] | |
| User=www-data | |
| Group=www-data | |
| WorkingDirectory=/var/www/django_admin | |
| Environment="PATH=/var/www/django_admin/venv/bin" | |
| ExecStart=/var/www/django_admin/venv/bin/gunicorn config.wsgi:application --bind 0.0.0.0:8001 --workers 3 | |
| [Install] | |
| WantedBy=multi-user.target | |
| ``` | |
| #### Deployment Steps | |
| ```bash | |
| # 1. Clone to server | |
| cd /var/www | |
| git clone <your-repo> django_admin | |
| cd django_admin | |
| # 2. Setup virtual environment | |
| python3.11 -m venv venv | |
| source venv/bin/activate | |
| pip install -r requirements.txt | |
| # 3. Configure environment | |
| cp .env.example .env | |
| nano .env # Edit with production values | |
| # 4. Collect static files | |
| python manage.py collectstatic --noinput | |
| # 5. Create log directory | |
| mkdir -p logs | |
| chown www-data:www-data logs | |
| # 6. Start services | |
| sudo systemctl enable django-admin | |
| sudo systemctl start django-admin | |
| sudo systemctl enable fastapi | |
| sudo systemctl start fastapi | |
| # 7. Configure Nginx | |
| sudo ln -s /etc/nginx/sites-available/admin-dashboard /etc/nginx/sites-enabled/ | |
| sudo nginx -t | |
| sudo systemctl reload nginx | |
| # 8. Setup SSL with Let's Encrypt | |
| sudo certbot --nginx -d admin.yourdomain.com | |
| sudo certbot --nginx -d api.yourdomain.com | |
| ``` | |
| --- | |
| ### Option 2: Single Server with Path-Based Routing | |
| ```nginx | |
| server { | |
| listen 80; | |
| server_name yourdomain.com; | |
| # FastAPI API | |
| location /api/v1/ { | |
| proxy_pass http://127.0.0.1:8000; | |
| proxy_set_header Host $host; | |
| } | |
| # Django Admin Dashboard | |
| location /admin/ { | |
| proxy_pass http://127.0.0.1:8001; | |
| proxy_set_header Host $host; | |
| } | |
| # Django static files | |
| location /static/ { | |
| alias /var/www/django_admin/staticfiles/; | |
| } | |
| } | |
| ``` | |
| --- | |
| ## Docker Deployment | |
| ### docker-compose.yml | |
| ```yaml | |
| version: '3.8' | |
| services: | |
| postgres: | |
| image: postgres:16 | |
| environment: | |
| POSTGRES_DB: chatbot_db | |
| POSTGRES_USER: postgres | |
| POSTGRES_PASSWORD: your_password | |
| volumes: | |
| - postgres_data:/var/lib/postgresql/data | |
| ports: | |
| - "5432:5432" | |
| redis: | |
| image: redis:7-alpine | |
| ports: | |
| - "6379:6379" | |
| fastapi: | |
| build: ./fastapi_app | |
| command: uvicorn main:app --host 0.0.0.0 --port 8000 --workers 4 | |
| ports: | |
| - "8000:8000" | |
| depends_on: | |
| - postgres | |
| - redis | |
| environment: | |
| DATABASE_URL: postgresql://postgres:your_password@postgres:5432/chatbot_db | |
| django_admin: | |
| build: ./django_admin_backend | |
| command: gunicorn config.wsgi:application --bind 0.0.0.0:8001 --workers 3 | |
| ports: | |
| - "8001:8001" | |
| depends_on: | |
| - postgres | |
| - redis | |
| - fastapi | |
| environment: | |
| DB_HOST: postgres | |
| DB_NAME: chatbot_db | |
| DB_USER: postgres | |
| DB_PASSWORD: your_password | |
| REDIS_URL: redis://redis:6379/1 | |
| FASTAPI_BASE_URL: http://fastapi:8000/api/v1 | |
| nginx: | |
| image: nginx:alpine | |
| ports: | |
| - "80:80" | |
| - "443:443" | |
| volumes: | |
| - ./nginx.conf:/etc/nginx/nginx.conf | |
| - ./staticfiles:/var/www/static | |
| depends_on: | |
| - fastapi | |
| - django_admin | |
| volumes: | |
| postgres_data: | |
| ``` | |
| ### Dockerfile for Django Admin | |
| ```dockerfile | |
| FROM python:3.11-slim | |
| WORKDIR /app | |
| # Install dependencies | |
| COPY requirements.txt . | |
| RUN pip install --no-cache-dir -r requirements.txt | |
| # Copy project | |
| COPY . . | |
| # Collect static files | |
| RUN python manage.py collectstatic --noinput | |
| # Create logs directory | |
| RUN mkdir -p logs | |
| EXPOSE 8001 | |
| CMD ["gunicorn", "config.wsgi:application", "--bind", "0.0.0.0:8001", "--workers", "3"] | |
| ``` | |
| --- | |
| ## Common Tasks | |
| ### Create Superuser | |
| ```bash | |
| python manage.py createsuperuser | |
| ``` | |
| ### Update Database Models (if you add managed models) | |
| ```bash | |
| python manage.py makemigrations | |
| python manage.py migrate | |
| ``` | |
| ### Collect Static Files | |
| ```bash | |
| python manage.py collectstatic --noinput | |
| ``` | |
| ### Clear Cache | |
| ```bash | |
| python manage.py shell | |
| >>> from django.core.cache import cache | |
| >>> cache.clear() | |
| ``` | |
| ### View Logs | |
| ```bash | |
| tail -f logs/django.log | |
| ``` | |
| --- | |
| ## User Permissions | |
| ### Role-Based Access | |
| 1. **Superuser** (`is_superuser=True`) | |
| - Full Django admin access | |
| - Full custom dashboard access | |
| - Can manage users, agents, RAG, everything | |
| 2. **Staff/Admin** (`is_staff=True` or `role='admin'`) | |
| - Custom dashboard access | |
| - View analytics | |
| - Manage users (limited) | |
| - Manage RAG collections | |
| - Manage agents | |
| 3. **Regular User** (future) | |
| - No admin access | |
| - Can view own API keys (when implemented) | |
| - Can manage own agents (when implemented) | |
| ### Grant Admin Access to Existing User | |
| ```python | |
| # Django shell | |
| python manage.py shell | |
| from apps.core.models import User | |
| user = User.objects.get(username='john') | |
| user.is_staff = True | |
| user.role = 'admin' | |
| user.save() | |
| ``` | |
| --- | |
| ## Extending for User Self-Service | |
| When you want to allow users to manage their own resources: | |
| ### 1. Create User Dashboard Views | |
| ```python | |
| # apps/dashboard/views.py | |
| @login_required | |
| def user_dashboard(request): | |
| """User-specific dashboard.""" | |
| if request.user.is_staff: | |
| return redirect('dashboard:home') | |
| # Show user's own data | |
| user_agents = Agent.objects.filter(created_by_id=request.user.id) | |
| # ... etc | |
| return render(request, 'user/dashboard.html', {'agents': user_agents}) | |
| ``` | |
| ### 2. Add API Key Management | |
| ```python | |
| # apps/core/models.py | |
| class APIKey(models.Model): | |
| user = models.ForeignKey(User, on_delete=models.CASCADE) | |
| key = models.CharField(max_length=64, unique=True) | |
| name = models.CharField(max_length=100) | |
| created_at = models.DateTimeField(auto_now_add=True) | |
| last_used = models.DateTimeField(null=True, blank=True) | |
| is_active = models.BooleanField(default=True) | |
| ``` | |
| ### 3. Update URL Routing | |
| ```python | |
| # config/urls.py | |
| urlpatterns = [ | |
| # Admin dashboard (staff only) | |
| path('admin/', include('apps.dashboard.urls')), | |
| # User dashboard (regular users) | |
| path('my/', include('apps.user.urls')), | |
| ] | |
| ``` | |
| --- | |
| ## Monitoring & Maintenance | |
| ### Health Check Endpoint | |
| Add to `apps/dashboard/views.py`: | |
| ```python | |
| from django.http import JsonResponse | |
| from django.db import connection | |
| def health_check(request): | |
| try: | |
| with connection.cursor() as cursor: | |
| cursor.execute("SELECT 1") | |
| return JsonResponse({'status': 'healthy'}) | |
| except Exception as e: | |
| return JsonResponse({'status': 'unhealthy', 'error': str(e)}, status=500) | |
| ``` | |
| ### Performance Monitoring | |
| Use Django Debug Toolbar in development: | |
| ```python | |
| # Already configured in settings.py when DEBUG=True | |
| # Access at: http://localhost:8001/__debug__/ | |
| ``` | |
| ### Error Tracking | |
| Sentry is configured. Add DSN to `.env`: | |
| ```bash | |
| SENTRY_DSN=https://your-sentry-dsn | |
| ENVIRONMENT=production | |
| ``` | |
| --- | |
| ## Security Checklist | |
| - [ ] `DEBUG=False` in production | |
| - [ ] Strong `SECRET_KEY` generated and kept secret | |
| - [ ] `ALLOWED_HOSTS` configured properly | |
| - [ ] SSL/HTTPS enabled | |
| - [ ] Database credentials secured | |
| - [ ] Redis password set (if exposed) | |
| - [ ] CORS configured correctly | |
| - [ ] CSP headers configured | |
| - [ ] Regular security updates: `pip list --outdated` | |
| - [ ] Firewall configured (only ports 80, 443 open) | |
| - [ ] Backup strategy in place | |
| --- | |
| ## Troubleshooting | |
| ### Can't login to admin | |
| ```bash | |
| # Reset user password | |
| python manage.py shell | |
| >>> from apps.core.models import User | |
| >>> user = User.objects.get(username='admin') | |
| >>> user.set_password('newpassword') | |
| >>> user.save() | |
| ``` | |
| ### Database connection errors | |
| ```bash | |
| # Check database connectivity | |
| python manage.py dbshell | |
| # Or | |
| psql -h localhost -U postgres -d chatbot_db | |
| ``` | |
| ### Static files not loading | |
| ```bash | |
| python manage.py collectstatic --clear --noinput | |
| ``` | |
| ### 502 Bad Gateway | |
| ```bash | |
| # Check if Django is running | |
| sudo systemctl status django-admin | |
| # Check logs | |
| journalctl -u django-admin -f | |
| ``` | |
| --- | |
| ## Support | |
| For issues or questions: | |
| 1. Check logs: `tail -f logs/django.log` | |
| 2. Check system logs: `journalctl -u django-admin -f` | |
| 3. Enable DEBUG mode temporarily to see detailed errors | |
| 4. Check database connectivity | |
| 5. Verify FastAPI is running and accessible | |
| --- | |
| ## License & Credits | |
| Built with Django 5.0, Tailwind CSS, Alpine.js, and Chart.js. |