Gunicorn as WSGI server in Django - Step-by-Step Execution

Concept Flow - Gunicorn as WSGI server

Start Gunicorn Command

↓

Gunicorn Loads WSGI App

↓

Gunicorn Creates Worker Processes

↓

Workers Listen for HTTP Requests

↓

Request Received

↓

Worker Calls Django WSGI Application

↓

Django Processes Request

↓

Response Returned to Worker

↓

Worker Sends HTTP Response to Client

↓

End

Gunicorn starts, loads the Django WSGI app, creates workers that listen for requests, then workers handle requests by calling Django and sending back responses.

Execution Sample

Django

gunicorn myproject.wsgi:application
# Gunicorn starts and runs Django app
# Listens for HTTP requests
# Handles requests with workers

This command starts Gunicorn as the WSGI server to run the Django application and handle incoming HTTP requests.

Execution Table

Step	Action	Gunicorn State	Worker State	Django App State	Output
1	Run 'gunicorn myproject.wsgi:application'	Starting master process	No workers yet	Not loaded	Gunicorn master process starts
2	Gunicorn loads WSGI application	Master process loaded app	No workers yet	WSGI app loaded	Ready to spawn workers
3	Gunicorn spawns worker processes	Master running	Workers spawned and listening	WSGI app ready	Workers ready for requests
4	HTTP request arrives	Master running	Worker receives request	Waiting for call	Request received by worker
5	Worker calls Django WSGI app	Master running	Worker processing request	Processing request	Django app processes request
6	Django returns response	Master running	Worker has response	Response ready	Response generated
7	Worker sends HTTP response	Master running	Worker sends response to client	Idle	Client receives HTTP response
8	Wait for next request	Master running	Workers listening	Idle	Ready for next request
9	Shutdown command received	Master shutting down	Workers terminating	App closing	Gunicorn stops

💡 Gunicorn stops when shutdown command is received or process is killed

Variable Tracker

Variable	Start	After Step 2	After Step 3	After Step 5	After Step 7	Final
Gunicorn Master	Not running	Running, app loaded	Running, workers spawned	Running	Running	Stopped
Worker Processes	None	None	Spawned, listening	Processing request	Sent response	Terminated
Django WSGI App	Not loaded	Loaded	Loaded	Processing request	Idle	Closed
HTTP Request	None	None	None	Received	Responded	None

Key Moments - 3 Insights

Why does Gunicorn create multiple worker processes?

Gunicorn creates multiple workers (see Step 3) so it can handle many requests at the same time without waiting for one to finish before starting another.

What happens when a worker receives an HTTP request?

At Step 4, the worker listens and receives the request, then calls the Django WSGI app to process it (Step 5), ensuring the request is handled properly.

Why does the Django app appear 'idle' after sending a response?

After sending the response (Step 7), the Django app waits for the next request, so it is idle until called again by a worker.

Visual Quiz - 3 Questions

Look at the execution table, what is the state of the worker processes after Step 3?

A Spawned and listening for requests

B Not created yet

C Processing a request

D Terminated

💡 Hint

Check the 'Worker State' column at Step 3 in the execution table.

At which step does the Django WSGI app process the HTTP request?

A Step 4

B Step 6

C Step 5

D Step 7

💡 Hint

Look at the 'Django App State' column to see when it is 'Processing request'.

If Gunicorn did not spawn multiple workers, what would change in the execution table?

A Django app would never load

B Workers would be 'None' after Step 3

C Master process would not start

D HTTP requests would be processed faster

💡 Hint

Refer to the 'Worker Processes' variable in variable_tracker after Step 3.

Concept Snapshot

Gunicorn is a WSGI server that runs Django apps.
It starts a master process and spawns multiple worker processes.
Workers listen for HTTP requests and call the Django WSGI app.
Django processes requests and returns responses via workers.
Multiple workers allow handling many requests at once.
Gunicorn stops when shutdown is triggered.

Full Transcript

Gunicorn acts as a WSGI server for Django by starting a master process that loads the Django WSGI application. It then creates multiple worker processes that listen for incoming HTTP requests. When a request arrives, a worker receives it and calls the Django WSGI app to process the request. Django generates a response which the worker sends back to the client. After sending the response, the worker waits for the next request. This setup allows handling many requests concurrently. Gunicorn stops when a shutdown command is received.

Practice

1. What is the primary role of Gunicorn when used with a Django project?

easy

A. It replaces the Django ORM for database queries.

B. It acts as a bridge between the web server and the Django application.

C. It manages static files like CSS and JavaScript.

D. It compiles Django templates into HTML.

Solution

1. Step 1: Understand Gunicorn's purpose

   Gunicorn is a WSGI server that connects web requests to the Django app code.

2. Step 2: Identify what Gunicorn does not do

   Gunicorn does not handle database queries, static files, or template compilation directly.

3. Final Answer:

   It acts as a bridge between the web server and the Django application. -> Option B

4. Quick Check:

   Gunicorn = bridge server [OK]

Hint: Gunicorn connects web requests to Django code [OK]

Common Mistakes:

• Thinking Gunicorn manages static files
• Confusing Gunicorn with Django ORM
• Assuming Gunicorn compiles templates

2. Which of the following is the correct command to start Gunicorn for a Django project named myproject with the default WSGI application?

easy

A. gunicorn myproject.settings:application

B. gunicorn myproject.manage:application

C. gunicorn myproject.urls:application

D. gunicorn myproject.wsgi:application

Solution

1. Step 1: Identify the WSGI application path

   In Django, the WSGI app is located at projectname.wsgi:application.

2. Step 2: Match the correct command format

   The correct Gunicorn command uses gunicorn myproject.wsgi:application.

3. Final Answer:

   gunicorn myproject.wsgi:application -> Option D

4. Quick Check:

   WSGI app path = myproject.wsgi:application [OK]

Hint: Gunicorn command uses <project>.wsgi:application [OK]

Common Mistakes:

• Using manage or settings instead of wsgi
• Confusing URLs module with WSGI
• Omitting the ':application' part

3. Given the command gunicorn --workers 3 --bind 0.0.0.0:8000 myproject.wsgi:application, what will happen when you run it?

medium

A. Gunicorn will start 1 worker and listen only on localhost at port 8000.

B. Gunicorn will fail because the bind address is invalid.

C. Gunicorn will start 3 worker processes and listen on all network interfaces at port 8000.

D. Gunicorn will start 3 workers but will not bind to any port.

Solution

1. Step 1: Analyze the --workers option

   The command specifies 3 workers, so Gunicorn will start 3 worker processes.

2. Step 2: Analyze the --bind option

   Binding to 0.0.0.0:8000 means listening on all network interfaces at port 8000.

3. Final Answer:

   Gunicorn will start 3 worker processes and listen on all network interfaces at port 8000. -> Option C

4. Quick Check:

   --workers 3 + --bind 0.0.0.0:8000 = Gunicorn will start 3 worker processes and listen on all network interfaces at port 8000. [OK]

Hint: 0.0.0.0 binds all interfaces, workers set process count [OK]

Common Mistakes:

• Assuming 0.0.0.0 is invalid
• Thinking workers default to 1 always
• Ignoring the bind port

4. You run gunicorn myproject.wsgi:application --workers two and get an error. What is the likely cause?

medium

A. The workers option must be a number, not a word.

B. The WSGI application path is incorrect.

C. Gunicorn does not accept the --workers option.

D. The command is missing the --bind option.

Solution

1. Step 1: Check the --workers option value

   The value 'two' is a word, but --workers expects an integer number.

2. Step 2: Confirm Gunicorn option requirements

   Gunicorn requires a numeric value for workers; using a word causes an error.

3. Final Answer:

   The workers option must be a number, not a word. -> Option A

4. Quick Check:

   --workers needs number, not text [OK]

Hint: Workers count must be numeric, not text [OK]

Common Mistakes:

• Assuming WSGI path error causes this
• Thinking --workers is unsupported
• Believing --bind is mandatory for this error

5. You want to deploy your Django app with Gunicorn on a server accessible only on port 8080 and use 4 workers for better performance. Which command correctly achieves this?

hard

A. gunicorn --workers 4 --bind 0.0.0.0:8080 myproject.wsgi:application

B. gunicorn --workers 4 --bind 127.0.0.1:8080 myproject.wsgi:application

C. gunicorn --workers 1 --bind 0.0.0.0:8080 myproject.wsgi:application

D. gunicorn --bind 0.0.0.0:80 myproject.wsgi:application

Solution

1. Step 1: Set the correct number of workers

   The requirement is 4 workers, so use --workers 4.

2. Step 2: Bind to port 8080 on all interfaces

   Binding to 0.0.0.0:8080 makes the app accessible on port 8080 from any network interface.

3. Step 3: Verify the WSGI application path

   The path myproject.wsgi:application is the correct WSGI app for Django.

4. Final Answer:

   gunicorn --workers 4 --bind 0.0.0.0:8080 myproject.wsgi:application -> Option A

5. Quick Check:

   4 workers + bind 0.0.0.0:8080 = gunicorn --workers 4 --bind 0.0.0.0:8080 myproject.wsgi:application [OK]

Hint: Use --workers 4 and bind 0.0.0.0:8080 for access [OK]

Common Mistakes:

• Binding only to localhost (127.0.0.1) limits access
• Using wrong port number
• Setting wrong number of workers