Quickstart Guide¶

Get django-prodserver up and running in 10 minutes or less! This tutorial walks you through installation, configuration, and running your first production server.

What You’ll Accomplish¶

By the end of this guide, you’ll have:

django-prodserver installed in your Django project
A production-ready web server (Gunicorn) configured
Your Django application running in production mode
Understanding of how to deploy to production

Prerequisites¶

Python 3.8 or higher
An existing Django project (Django 3.2+)
Basic familiarity with Django and command line

Step 1: Install django-prodserver¶

Install the package using pip:

pip install django-prodserver

::::{tip} For production use, you’ll also need a server backend. We’ll use Gunicorn for this quickstart:

pip install gunicorn

::::

Step 2: Add to INSTALLED_APPS¶

Open your settings.py and add django_prodserver to INSTALLED_APPS:

# settings.py
INSTALLED_APPS = [
    'django.contrib.admin',
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.messages',
    'django.contrib.staticfiles',

    # Your apps
    # ...

    # Add django-prodserver
    'django_prodserver',
]

::::{note} No migrations are needed - django-prodserver doesn’t add any database tables. ::::

Step 3: Configure Your Production Server¶

Add the PRODUCTION_PROCESSES configuration to your settings.py:

# settings.py

# Production server configuration
PRODUCTION_PROCESSES = {
    "web": {
        "BACKEND": "django_prodserver.backends.servers.gunicorn.GunicornServer",
        "ARGS": {
            "bind": "0.0.0.0:8000",
            "workers": "2",
            "preload": None,
        }
    }
}

What this configuration does:

Creates a process named “web”
Uses Gunicorn as the server backend
Binds to all interfaces (0.0.0.0) on port 8000
Runs with 2 worker processes for handling concurrent requests
Preloads your wsgi app

Step 4: Run Your Production Server¶

Start your server with the server management command:

python manage.py server web

Deprecated since version 3.0.0: The prodserver command has been renamed to server. The old name continues to work as an alias but will be removed in django-prodserver 4.0.0.

You should see output like:

[2025-01-12 10:30:00 +0000] [12345] [INFO] Starting gunicorn 21.2.0
[2025-01-12 10:30:00 +0000] [12345] [INFO] Listening at: http://0.0.0.0:8000 (12345)
[2025-01-12 10:30:00 +0000] [12345] [INFO] Using worker: sync
[2025-01-12 10:30:00 +0000] [12347] [INFO] Booting worker with pid: 12347
[2025-01-12 10:30:00 +0000] [12348] [INFO] Booting worker with pid: 12348

Step 5: Test Your Application¶

Open your browser and visit:

http://localhost:8000

You should see your Django application running! Try navigating to different pages to verify everything works.

::::{important} You’re now running a production-ready server! This is much more robust than Django’s development server (runserver). ::::

Congratulations!¶

You’ve successfully set up django-prodserver! Your Django application is now running with:

Gunicorn: Industry-standard WSGI server
Multiple workers: Handling concurrent requests
Production-ready: Suitable for real deployments

Next Steps¶

Add Background Workers¶

Process tasks asynchronously with Celery:

# settings.py
PRODUCTION_PROCESSES = {
    "web": {
        "BACKEND": "django_prodserver.backends.servers.gunicorn.GunicornServer",
        "ARGS": {
            "bind": "0.0.0.0:8000",
            "workers": "2",
        }
    },
    "worker": {
        "BACKEND": "django_prodserver.backends.workers.celery.CeleryWorker",
        "APP": "myproject.celery.app",
        "ARGS": {
            "concurrency": "2",
        }
    }
}

See Worker for Celery setup.

Deploy with Docker¶

Containerize your application:

FROM python:3.11-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt
COPY . .
CMD ["python", "manage.py", "server", "web"]

See Docker Deployment Guide for complete Docker deployment.

Configure for Different Environments¶

Set up development, staging, and production configurations:

# settings_prod.py
from .settings import *

DEBUG = False
ALLOWED_HOSTS = ['example.com']

PRODUCTION_PROCESSES = {
    "web": {
        "BACKEND": "django_prodserver.backends.servers.gunicorn.GunicornServer",
        "ARGS": {
            "bind": "0.0.0.0:8000",
            "workers": "4",
            "timeout": "60",
        }
    }
}

See Environment-Specific Configuration for environment-specific configurations.

Try Different Backends¶

Explore other server backends:

ASGI Mode - For async Django applications
ASGI Mode - High-performance Rust-based server
Waitress - For Windows deployments
Django Tasks - Lightweight background tasks

Learn More¶

Usage - Detailed usage patterns and examples
Configuration - Complete configuration reference
Backend Reference - All available backends
Multi-Process Deployment Guide - Running multiple processes
Troubleshooting - Common issues and solutions

Common Questions¶

Q: How is this different from python manage.py runserver?

A: Django’s runserver is for development only. django-prodserver uses production-ready servers like Gunicorn that are:

Much faster (multiple workers)
More stable (automatic worker restarts)
More secure (designed for production)
Better at handling concurrent requests

Q: Can I use this in development?

A: Yes, but runserver is better for development because it auto-reloads when code changes. Use server for staging, testing production configurations, and production deployments.

Q: Do I need to configure nginx or Apache?

A: Not necessarily! Gunicorn can serve your application directly. However, for production, it’s recommended to use a reverse proxy (nginx/Apache) for:

SSL/TLS termination
Static file serving
Load balancing
Additional security features

Q: How many workers should I use?

A: A good starting point is (2 × CPU_cores) + 1. For example, on a 2-core machine:

"workers": "5"  # (2 × 2) + 1

Monitor your application and adjust based on resource usage.

Q: What if I get errors?

A: Check the Troubleshooting guide for common issues. Common problems:

Backend not installed: pip install gunicorn
Port in use: Change the port number
Settings not found: Ensure PRODUCTION_PROCESSES is in your settings

Quick Reference¶

Basic Commands¶

# Start web server
python manage.py server web

# Start with specific settings
python manage.py server web --settings=myproject.settings_prod

# Run in foreground (Ctrl+C to stop)
python manage.py server web

Basic Configuration¶

# Minimal
PRODUCTION_PROCESSES = {
    "web": {
        "BACKEND": "django_prodserver.backends.servers.gunicorn.GunicornServer",
        "ARGS": {"bind": "0.0.0.0:8000"}
    }
}

# Recommended
PRODUCTION_PROCESSES = {
    "web": {
        "BACKEND": "django_prodserver.backends.servers.gunicorn.GunicornServer",
        "ARGS": {
            "bind": "0.0.0.0:8000",
            "workers": "4",
            "timeout": "60",
        }
    }
}

Troubleshooting¶

Server won’t start:

# Check if gunicorn is installed
pip install gunicorn

# Verify settings are correct
python manage.py check

# Check if port is already in use
# On Linux/macOS:
lsof -i :8000
# On Windows:
netstat -ano | findstr :8000

ImportError: No module named ‘gunicorn’:

pip install gunicorn

Port already in use:

# Change port in settings.py
"ARGS": {
    "bind": "0.0.0.0:8001",  # Use different port
}

For more help, see Troubleshooting.

Summary¶

You’ve learned how to:

Install django-prodserver and a backend (Gunicorn)
Add django-prodserver to your Django project
Configure a production server
Run your application in production mode
Understand next steps for advanced deployments

Ready for production? You’re all set to deploy! Check out the Practical Guides for Docker, environment configs, and multi-process deployments.