Skip to main content
Mapagam

Implementing uWSGI Support (Python)

1. Setting uWSGI Pass

Directive Description Example
uwsgi_pass Specifies the uWSGI server address to forward requests to. uwsgi_pass unix:/tmp/myapp.socket;
uwsgi_param Sets custom uWSGI parameters to pass to the application. uwsgi_param HTTP_X_FORWARDED_FOR $proxy_add_x_forwarded_for;

Example: Basic uWSGI Pass Configuration

location / {
    uwsgi_pass unix:/tmp/myapp.sock;
    include uwsgi_params;
}
Note: Ensure the uWSGI socket or HTTP address is correctly configured in your uWSGI setup.

2. Configuring uWSGI Params

Parameter Description Default Value Notes
uwsgi_param Defines a parameter to be passed to the uWSGI server - Used in Nginx to pass variables to uWSGI
uwsgi_pass Specifies the uWSGI server address - Can be a socket or HTTP address
uwsgi_read_timeout Timeout for reading a response from uWSGI 60s Prevents hanging connections
uwsgi_connect_timeout Timeout for connecting to uWSGI 60s Used when establishing connection to uWSGI server
uwsgi_send_timeout Timeout for sending a request to uWSGI 60s Controls how long Nginx waits for uWSGI to send a response

Example: Basic uWSGI Configuration

location / {
    uwsgi_pass unix:/var/run/uwsgi/app/myapp.socket;
    uwsgi_param UWSGI_PYTHON /usr/bin/python3;
    uwsgi_param UWSGI_SCRIPT myapp.wsgi;
    uwsgi_read_timeout 300s;
    uwsgi_connect_timeout 300s;
}
Note: Ensure that the uWSGI socket path matches the one configured in your uWSGI setup.

3. Including uWSGI Config

Directive Description Example
uwsgi_pass Specifies the uWSGI server to pass requests to uwsgi_pass unix:/tmp/myapp.socket;
uwsgi_param Sets a parameter to be passed to the uWSGI server uwsgi_param HTTP_X_REAL_IP $remote_addr;
uwsgi_read_timeout Defines the timeout for reading a response from the uWSGI server uwsgi_read_timeout 30s;

Example: Basic uWSGI Configuration

location / {
    uwsgi_pass unix:/tmp/myapp.socket;
    uwsgi_param UWSGI_PYTHON /usr/bin/python3;
    uwsgi_param UWSGI_SCRIPT myapp;
    uwsgi_param UWSGI_CALLABLE app;
}
Note: Ensure the uWSGI socket path matches your application's configuration.

4. Using Unix Socket

Directive Values Description
uwsgi_pass unix:/path/to/socket.sock Specifies the Unix socket to connect to uWSGI.

Example: Nginx configuration with Unix socket

server {
    listen 80;
    server_name example.com;

    location / {
        uwsgi_pass unix:/var/run/uwsgi/app/myapp.socket;
        include uwsgi_params;
    }
}
Note: Ensure the socket file path matches the one configured in your uWSGI setup.

5. Setting uWSGI Timeouts

Timeout Option Default Value Description
socket-timeout 60 Timeout for socket operations in seconds
harakiri 0 Kills the process if it exceeds this time (in seconds)
http-timeout 60 Timeout for HTTP requests in seconds
max-requests 0 Restart the worker after this many requests (0 = never)

Example: Configuring uWSGI Timeouts

[uwsgi]
socket-timeout = 30
harakiri = 120
http-timeout = 60
max-requests = 1000

6. Configuring uWSGI Buffering

Directive Description Default Notes
buffer-size Size of the buffer used for reading responses from uWSGI 4096 Adjust based on expected response size to avoid frequent reallocations
post-buffering Enables post buffering of response content 0 Set to 1 to enable buffering of response content
post-buffering-bufsize Size of the buffer used for post buffering 1024 Used in conjunction with post-buffering

Example: Enabling uWSGI Post Buffering

location / {
    uwsgi_pass unix:/tmp/myapp.sock;
    uwsgi_post_buffering on;
    uwsgi_buffer_size 1024;
}
Note: Post buffering can help reduce the number of small writes to the client, improving performance for large responses.

7. Using uWSGI Cache

Directive Description Default Notes
uwsgi_cache Defines the cache zone to be used for storing cached responses. none Must be defined in the http, server, or location context.
uwsgi_cache_key Defines the key used to store and retrieve cached responses. $scheme$host$request_uri Can include variables like $query_string, $cookie_....
uwsgi_cache_valid Sets the cache validity time for different response codes. none Can be set multiple times for different status codes, e.g., 200 1h.
uwsgi_cache_min_uses Minimum number of requests before a response is cached. 1 Useful to avoid caching responses for rare or test requests.
uwsgi_cache_use_stale Defines when a stale cached response can be served. none Can include error, timeout, updating, etc.
uwsgi_cache_lock Enables locking to prevent multiple requests from generating the same cache entry. off Useful in high-concurrency environments to avoid cache stampede.

Example: Basic uWSGI Cache Configuration

location / {
    uwsgi_pass unix:/tmp/uwsgi.sock;
    uwsgi_cache my_cache;
    uwsgi_cache_key $scheme$host$request_uri;
    uwsgi_cache_valid 200 1h;
    uwsgi_cache_min_uses 2;
    uwsgi_cache_use_stale error timeout updating 5m;
    uwsgi_cache_lock on;
}
Note: The uwsgi_cache directive must be defined in the same context as the location block where it is used, or in a higher-level context like http.
Warning: If uwsgi_cache_lock is enabled, it may introduce slight delays in response times due to locking overhead.

8. Setting uWSGI Buffer Sizes

Directive Values Description
uwsgi_buffer_size 4k|8k Size of the buffer used for reading the response from the uWSGI application
uwsgi_buffers number size Number and size of buffers used for reading the response from the uWSGI application
uwsgi_busy_buffers_size size Maximum size of buffers that can be filled at the same time

Example: Configuring uWSGI Buffer Settings

location / {
    uwsgi_pass unix:/tmp/myapp.sock;
    uwsgi_buffer_size 16k;
    uwsgi_buffers 4 16k;
    uwsgi_busy_buffers_size 32k;
}

9. Handling uWSGI Errors

Error Type Description Resolution
uwsgi_error Generic uWSGI error indicating internal failure Check uWSGI logs for detailed stack trace; verify Python app is valid
app_error Python application error (e.g., unhandled exception) Review Python app logs; ensure proper exception handling
socket_error Socket connection issues between Nginx and uWSGI Verify uWSGI is running; check socket path or port config in Nginx
timeout_error Request timeout from uWSGI to Python app Increase uwsgi_read_timeout in Nginx config; optimize Python app

Example: Error Log Configuration

error_log /var/log/nginx/error.log debug;

Example: uWSGI Log Configuration

[uwsgi]
logto = /var/log/uwsgi/app.log
log-maxsize = 1000000
Note: Enable debug logging in uWSGI to capture detailed error information for troubleshooting.
Warning: Avoid exposing sensitive error details in production logs to prevent security risks.

10. Configuring uWSGI for Django

Option Values Notes
module myproject.wsgi:application Path to WSGI module
master true Enable master process
processes 2 Number of worker processes
socket /tmp/myproject.sock Unix socket for Nginx to connect
chmod-socket 666 Socket permissions for Nginx
vacuum true Remove socket on exit

Example: Basic uWSGI Configuration for Django

[uwsgi]
module = myproject.wsgi:application
master = true
processes = 2
socket = /tmp/myproject.sock
chmod-socket = 666
vacuum = true
die-on-term = true
Note: Ensure the socket path is accessible to Nginx and has appropriate permissions.

11. Configuring uWSGI for Flask

Configuration Option Description Example Value
module Python module to load app:application
callable Name of the WSGI callable application
socket Unix socket or TCP address to bind to /tmp/uwsgi.sock
chmod-socket Permissions for the socket file 666
vacuum Clear socket on exit true
die-on-term Exit when receiving SIGTERM true

Example: Basic uWSGI Configuration for Flask App

[uwsgi]
module = app:application
callable = application
socket = /tmp/uwsgi.sock
chmod-socket = 666
vacuum = true
die-on-term = true
Note: Ensure that the Flask app's WSGI entry point is correctly defined as application.

12. Implementing uWSGI Cache Zones

Directive Description Values Notes
uwsgi_cache Defines the cache zone to be used for storing cached responses zone_name Must be defined with uwsgi_cache_zone
uwsgi_cache_key Defines the cache key for storing and retrieving cached responses string Can include variables like $uri, $args
uwsgi_cache_valid Sets the cache validity time for different response codes time Can specify multiple time values for different status codes
uwsgi_cache_min_uses Minimum number of requests before a response is cached number Default is 1
uwsgi_cache_use_stale Defines when to serve stale cached content error, timeout, invalid, updating, expired Can combine multiple values with spaces
uwsgi_cache_lock Enables locking to prevent multiple requests from caching the same content on, off Default is off

Example: Basic uWSGI Cache Configuration

location / {
    uwsgi_pass unix:/tmp/uwsgi.sock;
    uwsgi_cache my_cache_zone;
    uwsgi_cache_key $uri;
    uwsgi_cache_valid 200 1h;
    uwsgi_cache_min_uses 2;
    uwsgi_cache_use_stale error timeout updating;
}

Example: Advanced uWSGI Cache with Locking

uwsgi_cache_zone my_cache_zone 10m;

location /api/ {
    uwsgi_pass unix:/tmp/uwsgi.sock;
    uwsgi_cache my_cache_zone;
    uwsgi_cache_key $uri$args;
    uwsgi_cache_valid 200 30m;
    uwsgi_cache_valid 404 1m;
    uwsgi_cache_min_uses 3;
    uwsgi_cache_use_stale error timeout updating expired;
    uwsgi_cache_lock on;
}
Note: The uwsgi_cache_zone directive must be defined at the http level to be used in location blocks.
Warning: Using uwsgi_cache_lock can lead to performance bottlenecks under high load. Use with caution.

Was this article helpful?

Related Cheat Sheets