junaidte14's picture
deploying v1
0ad3564
|
Raw History Blame Contribute Delete
13.7 kB

Django Admin Dashboard - Setup & Deployment Guide

Quick Start

1. Prerequisites

# System requirements
- Python 3.11+
- PostgreSQL 14+
- Redis 7+
- Node.js 18+ (for Tailwind CSS compilation in production)

2. Installation

# 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

# 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

mkdir -p logs staticfiles media

5. Run Development Server

# 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:


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

# 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

# /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):

[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):

[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

# 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

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

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

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

python manage.py createsuperuser

Update Database Models (if you add managed models)

python manage.py makemigrations
python manage.py migrate

Collect Static Files

python manage.py collectstatic --noinput

Clear Cache

python manage.py shell
>>> from django.core.cache import cache
>>> cache.clear()

View Logs

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

# 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

# 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

# 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

# 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:

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:

# Already configured in settings.py when DEBUG=True
# Access at: http://localhost:8001/__debug__/

Error Tracking

Sentry is configured. Add DSN to .env:

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

# 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

# Check database connectivity
python manage.py dbshell
# Or
psql -h localhost -U postgres -d chatbot_db

Static files not loading

python manage.py collectstatic --clear --noinput

502 Bad Gateway

# 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.