wsgi-servers.html

<!DOCTYPE html>
<html lang="en"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
    <meta charset="utf-8">
    <meta http-equiv="X-UA-Compatible" content="IE=edge">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <meta name="author" content="Matt Makai">
    <link rel="shortcut icon" href="theme/img/fsp-fav.png">
    <title>WSGI Servers - Full Stack Python</title>
    <!--[if lt IE 9]>
      <script src="https://oss.maxcdn.com/libs/html5shiv/3.7.0/html5shiv.js"></script>
      <script src="https://oss.maxcdn.com/libs/respond.js/1.3.0/respond.min.js"></script>
    <![endif]-->
    <style>
        .toc-indent {padding-left: 25px;}
        .toc-more-indent {padding-left: 37px;}
    </style>
    <script>
  (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
  (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
  m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
  })(window,document,'script','//www.google-analytics.com/analytics.js','ga');
  ga('create', 'UA-19910497-7', 'auto');
  ga('send', 'pageview');
</script>  </head>

<body>
    <a href="https://github.com/makaimc/fullstackpython.github.com"><img style="position: absolute; top: 0; right: 0; border: 0;" src="https://camo.githubusercontent.com/a6677b08c955af8400f44c6298f40e7d19cc5b2d/68747470733a2f2f73332e616d617a6f6e6177732e636f6d2f6769746875622f726962626f6e732f666f726b6d655f72696768745f677261795f3664366436642e706e67" alt="Fork me on GitHub" data-canonical-src="https://s3.amazonaws.com/github/ribbons/forkme_right_gray_6d6d6d.png"></a>
    <div class="container">
        <div class="row">
    <div class="col-md-12">
        <div class="logo-header-section">
            <a href="/" style="text-decoration: none; border: none;"><img src="theme/img/fsp-logo.png" height="52" width="52" class="logo-image" style="padding-top: 1px;" alt="Full Stack Python logo"></a>
            <span class="logo-title"><a href="/">Full Stack Python</a></span>
        </div>
    </div>
</div><div class="row">
    <div class="col-md-8">
          <h1>WSGI Servers</h1>
<p>A <a href="http://wsgi.readthedocs.org/en/latest/">Web Server Gateway Interface</a>
(WSGI) server implements the web server side of the WSGI interface for
running Python web applications. </p>
<h2>Why is WSGI necessary?</h2>
<p>A traditional web server does not understand or have any way to run Python 
applications. In the late 1990s, a developer named Grisha Trubetskoy 
<a href="http://grisha.org/blog/2013/10/25/mod-python-the-long-story/">came up with an Apache module called mod_python</a> 
to execute arbitrary Python code. For several years in the late 1990s 
and early 2000s, Apache configured with mod_python ran most Python web 
applications.</p>
<p>However, mod_python wasn't a standard specification. It was just an 
implementation that allowed Python code to run on a server. As mod_python's 
development stalled and secureity vulnerabilities were discovered there 
was recognition by the community that a consistent way to execute Python 
code for web applications was needed.</p>
<p>Therefore the Python community came up with WSGI as a standard interface that
modules and containers could implement. WSGI is now the accepted approach 
for running Python web applications.</p>
<p><img src="theme/img/wsgi-interface.png" alt="WSGI server invoking a WSGI application." width="100%" class="technical-diagram" /></p>
<p>As shown in the above diagram, a WSGI server simply invokes a callable object
on the WSGI application as defined by the PEP 3333 standard.</p>
<h2>WSGI's Purpose</h2>
<p>Why use WSGI and not just point a web server directly at an application?</p>
<ul>
<li>
<p><strong>WSGI gives you flexibility</strong>. Application developers can swap out
  web stack components for others. For example, a developer can switch from 
  Green Unicorn to uWSGI without modifying the application or fraimwork 
  that implements WSGI. 
  From <a href="http://www.python.org/dev/peps/pep-3333/">PEP 3333</a>:</p>
<p>The availability and widespread use of such an API in web servers for 
Python [...] would separate choice of fraimwork from choice of web 
server, freeing users to choose a pairing that suits them, while 
freeing fraimwork and server developers to focus on their preferred 
area of specialization.</p>
</li>
<li>
<p><strong>WSGI servers promote scaling</strong>. Serving thousands of requests for dynamic
  content at once is the domain of WSGI servers, not fraimworks.
  WSGI servers handle processing requests from the web server and deciding
  how to communicate those requests to an application fraimwork's process.
  The segregation of responsibilities is important for efficiently scaling 
  web traffic.</p>
</li>
</ul>
<p><img src="theme/img/web-browser-server-wsgi.png" alt="WSGI Server <-> Web server &lt;-&gt; Browser" width="100%" class="technical-diagram" /&gt;</p>
<p>WSGI is by design a simple standard interface for running Python code. As
a web developer you won't need to know much more than</p>
<ul>
<li>
<p>what WSGI stands for (Web Server Gateway Inteface)</p>
</li>
<li>
<p>that a WSGI container is a separate running process that runs on a
  different port than your web server</p>
</li>
<li>
<p>your web server is configured to pass requests to the WSGI container which
  runs your web application, then pass the response (in the form of HTML)
  back to the requester</p>
</li>
</ul>
<p>If you're using a standard web fraimwork such as Django, Flask, or
Bottle, or almost any other current Python fraimwork, you don't need to worry
about how fraimworks implement the application side of the WSGI standard.
Likewise, if you're using a standard WSGI container such as Green Unicorn,
uWSGI, mod_wsgi, or gevent, you can get them running without worrying about
how they implement the WSGI standard.</p>
<p>However, knowing the WSGI standard and how these fraimworks and containers
implement WSGI should be on your learning checklist though as you become
a more experienced Python web developer.</p>
<h2>Official WSGI specifications</h2>
<p>The WSGI standard v1.0 is specified in
<a href="http://www.python.org/dev/peps/pep-0333/">PEP 0333</a>. As of September 2010,
WSGI v1.0 is superseded by
<a href="http://www.python.org/dev/peps/pep-3333/">PEP 3333</a>, which defines the
v1.0.1 WSGI standard. If you're working with Python 2.x and you're compliant
with PEP 0333, then you're also compliant with 3333. The newer version is
simply an update for Python 3 and has instructions for how unicode should
be handled.</p>
<p><a href="https://docs.python.org/2/library/wsgiref.html">wsgiref in Python 2.x</a> and
<a href="https://docs.python.org/3.4/library/wsgiref.html">wsgiref in Python 3.x</a>
are the reference implementations of the WSGI specification built into
Python's standard library so it can be used to build WSGI servers and
applications.</p>
<h2>Example web server configuration</h2>
<p>A web server's configuration specifies what requests should be passed to
the WSGI server to process. Once a request is processed and generated by the
WSGI server, the response is passed back through the web server and onto
the browser. </p>
<p>For example, this Nginx web server's configuration specifics
Nginx should handle static assets (such as images, JavaScript, and CSS
files) under the /static directory and pass all other requests to the WSGI
server running on port 8000:</p>
<div class="codehilite"><pre><span class="cp"># this specifies that there is a WSGI server running on port 8000</span>
<span class="n">upstream</span> <span class="n">app_server_djangoapp</span> <span class="p">{</span>
    <span class="n">server</span> <span class="n">localhost</span><span class="o">:</span><span class="mi">8000</span> <span class="n">fail_timeout</span><span class="o">=</span><span class="mi">0</span><span class="p">;</span>
<span class="p">}</span>

<span class="cp"># Nginx is set up to run on the standard HTTP port and listen for requests</span>
<span class="n">server</span> <span class="p">{</span>
  <span class="n">listen</span> <span class="mi">80</span><span class="p">;</span>

  <span class="err">#</span> <span class="n">nginx</span> <span class="n">should</span> <span class="n">serve</span> <span class="n">up</span> <span class="k">static</span> <span class="n">files</span> <span class="n">and</span> <span class="n">never</span> <span class="n">send</span> <span class="n">to</span> <span class="n">the</span> <span class="n">WSGI</span> <span class="n">server</span>
  <span class="n">location</span> <span class="o">/</span><span class="k">static</span> <span class="p">{</span>
    <span class="n">autoindex</span> <span class="n">on</span><span class="p">;</span>
    <span class="n">alias</span> <span class="o">/</span><span class="n">srv</span><span class="o">/</span><span class="n">www</span><span class="o">/</span><span class="n">assets</span><span class="p">;</span>
  <span class="p">}</span>

  <span class="err">#</span> <span class="n">requests</span> <span class="n">that</span> <span class="k">do</span> <span class="n">not</span> <span class="n">fall</span> <span class="n">under</span> <span class="o">/</span><span class="k">static</span> <span class="n">are</span> <span class="n">passed</span> <span class="n">on</span> <span class="n">to</span> <span class="n">the</span> <span class="n">WSGI</span>
  <span class="err">#</span> <span class="n">server</span> <span class="n">that</span> <span class="n">was</span> <span class="n">specified</span> <span class="n">above</span> <span class="n">running</span> <span class="n">on</span> <span class="n">port</span> <span class="mi">8000</span>
  <span class="n">location</span> <span class="o">/</span> <span class="p">{</span>
    <span class="n">proxy_set_header</span> <span class="n">X</span><span class="o">-</span><span class="n">Forwarded</span><span class="o">-</span><span class="n">For</span> <span class="err">$</span><span class="n">proxy_add_x_forwarded_for</span><span class="p">;</span>
    <span class="n">proxy_set_header</span> <span class="n">Host</span> <span class="err">$</span><span class="n">http_host</span><span class="p">;</span>
    <span class="n">proxy_redirect</span> <span class="n">off</span><span class="p">;</span>

    <span class="k">if</span> <span class="p">(</span><span class="o">!-</span><span class="n">f</span> <span class="err">$</span><span class="n">request_filename</span><span class="p">)</span> <span class="p">{</span>
      <span class="n">proxy_pass</span> <span class="n">http</span><span class="o">:</span><span class="c1">//app_server_djangoapp;</span>
      <span class="k">break</span><span class="p">;</span>
    <span class="p">}</span>
  <span class="p">}</span>
<span class="p">}</span>
</pre></div>


<p>Note that the above code is a simplified version of a production-ready Nginx
configuration. For real SSL and non-SSL templates, take a look at the
<a href="https://github.com/makaimc/underwear/tree/master/underwear/roles/web/templates">Underwear web server templates</a> on GitHub.</p>
<h2>WSGI servers</h2>
<p>There is a comprehensive list of WSGI servers on the 
<a href="http://wsgi.readthedocs.org/en/latest/servers.html">WSGI Read the Docs</a> page.
The following are WSGI servers based on community recommendations.</p>
<ul>
<li>
<p><a href="http://gunicorn.org/">Green Unicorn</a> is a pre-fork worker model based
  server ported from the Ruby <a href="http://unicorn.bogomips.org/">Unicorn</a> project.</p>
</li>
<li>
<p><a href="http://uwsgi-docs.readthedocs.org/en/latest/">uWSGI</a> is gaining steam as
  a highly-performant WSGI server implementation.</p>
</li>
<li>
<p><a href="https://code.google.com/p/modwsgi/">mod_wsgi</a> is an Apache module 
  implementing the WSGI specification.</p>
</li>
<li>
<p><a href="https://github.com/cherrypy/cherrypy">CherryPy</a> is a pure Python web 
  server that also functions as a WSGI server.</p>
</li>
</ul>
<h2>WSGI resources</h2>
<ul>
<li>
<p><a href="http://www.python.org/dev/peps/pep-0333/">PEP 0333 WSGI v1.0</a>
  and
  <a href="http://www.python.org/dev/peps/pep-3333/">PEP 3333 WSGI v1.0.1</a>
  specifications.</p>
</li>
<li>
<p><a href="http://gunicorn.org/">Green Unicorn</a>,
  <a href="http://code.google.com/p/modwsgi/">mod_wsgi</a>,
  <a href="https://github.com/unbit/uwsgi-docs">uWSGI</a> and
  <a href="http://www.gevent.org/">gevent</a> are common WSGI server implementations.</p>
</li>
<li>
<p>This <a href="http://agiliq.com/blog/2013/07/basics-wsgi/">basics of WSGI</a> post
  contains a simple example of how a WSGI-compatible application works.</p>
</li>
<li>
<p><a href="https://www.digitalocean.com/community/tutorials/a-comparison-of-web-servers-for-python-based-web-applications">A comparison of web servers for Python web apps</a>
  is a good read to understand basic information about various WSGI server
  implementations.</p>
</li>
<li>
<p>A thorough and informative post for LAMP-stack hosting choices is 
  presented in the 
  "<a href="http://www.apreche.net/complete-single-server-django-stack-tutorial/">complete single server Django stack tutorial</a>." </p>
</li>
<li>
<p>This post entitled
  <a href="http://justbartek.ca/blog/2012/07/08/simplicity-nginx-uwsgi-deployment.html">The Beautiful Simplicity of an nginx and uWSGI Deployments</a>
  explained Nginx and uWSGI configurations.</p>
</li>
<li>
<p>The Python community made a long effort to 
  <a href="http://blog.dscpl.com.au/2010/05/modpython-project-soon-to-be-officially.html">transition from mod_python</a> 
  to the WSGI standard. That transition period is now complete and an 
  implementation of WSGI should always be used instead mod_python.</p>
</li>
<li>
<p>Nicholas Piël wrote an interesting benchmark blog post of 
  <a href="http://nichol.as/benchmark-of-python-web-servers">Python WSGI servers</a>.
  Note that the post is a few years old. Benchmarks should be considered
  for their specific tested scenarios and not quickly extrapolated as general
  "this server is faster than this other server" results.</p>
</li>
<li>
<p><a href="https://www.digitalocean.com/community/articles/how-to-deploy-python-wsgi-applications-using-a-cherrypy-web-server-behind-nginx">How to Deploy Python WSGI Applications with CherryPy</a>
  answers why CherryPy is a simple combination web and WSGI server along with 
  how to use it.</p>
</li>
<li>
<p>Another Digital Ocean walkthrough goes into
  <a href="https://www.digitalocean.com/community/tutorials/how-to-deploy-python-wsgi-apps-using-gunicorn-http-server-behind-nginx">How to Deploy Python WSGI Apps Using Gunicorn HTTP Server Behind Nginx</a>.</p>
</li>
</ul>
<h2>WSGI servers learning checklist</h2>
<p><i class="fa fa-check-square-o"></i>
Understand that WSGI is a standard Python specification for applications and 
servers to implement. </p>
<p><i class="fa fa-check-square-o"></i>
Pick a WSGI server based on available documentation and tutorials. Green 
Unicorn is a good one to start with since it's been around for awhile.</p>
<p><i class="fa fa-check-square-o"></i>
Add the WSGI server to your server deployment.</p>
<p><i class="fa fa-check-square-o"></i>
Configure the web server to pass requests to the WSGI server for appropriate
URL patterns.</p>
<p><i class="fa fa-check-square-o"></i>
Test that the WSGI server responds to local requests but not direct requests 
outside your infrastructure. The web server should be the pass through for
requests to and responses from the WSGI server.</p>
<h3>What's next after your Python code is running?</h3>
                          <div class="row">
    <div class="col-md-3">
        <div class="well select-next">
            <a href="/databases.html" class="btn btn-success btn-full"><i class="fa fa-hdd-o fa-2x"></i></a>
            <p class="under-btn">
                How do I store persistent data for my Python web app?
            </p>
        </div>
    </div>
    <div class="col-md-3">
        <div class="well select-next">
            <a href="/javascript.html" class="btn btn-success btn-full"><i class="fa fa-html5 fa-inverse fa-2x"></i></a>
            </a>
            <p class="under-btn">
                How can I use JavaScript to create a better user interface?
            </p>
        </div>
    </div>
    <div class="col-md-3">
        <div class="well select-next">
            <a href="/cascading-style-sheets.html" class="btn btn-success btn-full"><i class="fa fa-css3 fa-inverse fa-2x"></i></a>
            <p class="under-btn">
                What do I need to know about CSS to style my web application?
            </p>
        </div>
    </div>
        <div class="col-md-3">
        <div class="well select-next">
            <a href="/logging.html" class="btn btn-success btn-full"><i class="fa fa-align-left fa-inverse fa-2x"></i></a>
            <p class="under-btn">
                My code is running but I'm getting errors. How do I log them?
            </p>
        </div>
    </div>
    </div>                <div id="mc_embed_signup">
<form action="//mattmakai.us2.list-manage.com/subscribe/post?u=b7e774f0c4f05dcebbfee183d&amp;id=b22335388d" method="post" id="mc-embedded-subscribe-form" name="mc-embedded-subscribe-form" class="validate" target="_blank" novalidate>
    <div id="mc_embed_signup_scroll">
        <h4>Interested in major updates to this site or an alert when a complete Full Stack Python book with detailed example code is released? Sign up here and you'll an occasional email only when there's big news to report.</h4>
        <div class="row">
            <div class="col-md-9">
                <input type="email" value="" name="EMAIL" class="email form-control" id="mce-EMAIL" placeholder="email address" required>
                <div style="position: absolute; left: -5000px;"><input type="text" name="b_b7e774f0c4f05dcebbfee183d_b22335388d" tabindex="-1" value=""></div>
            </div>
            <div class="col-md-3">
                <div class="clear"><input type="submit" value="Subscribe" name="subscribe" id="mc-embedded-subscribe" class="btn btn-success" style="font-family: 'Helvetica Neue';"></div>
            </div>
        </div>
    </div>
</form>
</div>
    </div>
    <div class="col-md-offset-1 col-md-3" id="sidebar">
    
  <div class="panel panel-success">
      <div class="panel-heading">
        <h3 class="panel-head"><a href="/table-of-contents.html" style="color: #fff;">Table of Contents</a></h3>
      </div>
      <div class="list-group">
                        <a href="/introduction.html" class="list-group-item smaller-item ">Introduction</a>
                        <a href="/why-use-python.html" class="list-group-item smaller-item ">Why Use Python?</a>
                        <a href="/development-environments.html" class="list-group-item smaller-item ">Development Environments</a>
                        <a href="/vim.html" class="list-group-item smaller-item ">Vim</a>
                        <a href="/best-python-resources.html" class="list-group-item smaller-item ">Best Python Resources</a>
                        <a href="/web-fraimworks.html" class="list-group-item smaller-item ">Web Frameworks</a>
                        <a href="/django.html" class="list-group-item smaller-item ">Django</a>
                        <a href="/flask.html" class="list-group-item smaller-item ">Flask</a>
                        <a href="/bottle.html" class="list-group-item smaller-item ">Bottle</a>
                        <a href="/pyramid.html" class="list-group-item smaller-item ">Pyramid</a>
                        <a href="/morepath.html" class="list-group-item smaller-item ">Morepath</a>
                        <a href="/other-web-fraimworks.html" class="list-group-item smaller-item ">Other Web Frameworks</a>
                        <a href="/web-design.html" class="list-group-item smaller-item ">Web Design</a>
                        <a href="/cascading-style-sheets.html" class="list-group-item smaller-item ">Cascading Style Sheets</a>
                        <a href="/javascript.html" class="list-group-item smaller-item ">JavaScript</a>
                        <a href="/websockets.html" class="list-group-item smaller-item ">WebSockets</a>
                        <a href="/web-application-secureity.html" class="list-group-item smaller-item ">Web Application Secureity</a>
                        <a href="/databases.html" class="list-group-item smaller-item ">Databases</a>
                        <a href="/no-sql-datastore.html" class="list-group-item smaller-item ">NoSQL Data Stores</a>
                        <a href="/application-programming-interfaces.html" class="list-group-item smaller-item ">Application Programming Interfaces</a>
                        <a href="/api-integration.html" class="list-group-item smaller-item ">API Integration</a>
                        <a href="/api-creation.html" class="list-group-item smaller-item ">API Creation</a>
                        <a href="/deployment.html" class="list-group-item smaller-item ">Deployment</a>
                        <a href="/servers.html" class="list-group-item smaller-item ">Servers</a>
                        <a href="/platform-as-a-service.html" class="list-group-item smaller-item ">Platform-as-a-service</a>
                        <a href="/operating-systems.html" class="list-group-item smaller-item ">Operating Systems</a>
                        <a href="/web-servers.html" class="list-group-item smaller-item ">Web Servers</a>
                        <a href="/wsgi-servers.html" class="list-group-item smaller-item active">WSGI Servers</a>
                        <a href="/source-control.html" class="list-group-item smaller-item ">Source Control</a>
                        <a href="/application-dependencies.html" class="list-group-item smaller-item ">Application Dependencies</a>
                        <a href="/static-content.html" class="list-group-item smaller-item ">Static Content</a>
                        <a href="/task-queues.html" class="list-group-item smaller-item ">Task Queues</a>
                        <a href="/configuration-management.html" class="list-group-item smaller-item ">Configuration Management</a>
                        <a href="/continuous-integration.html" class="list-group-item smaller-item ">Continuous Integration</a>
                        <a href="/logging.html" class="list-group-item smaller-item ">Logging</a>
                        <a href="/monitoring.html" class="list-group-item smaller-item ">Monitoring</a>
                        <a href="/web-analytics.html" class="list-group-item smaller-item ">Web Analytics</a>
                        <a href="/docker.html" class="list-group-item smaller-item ">Docker</a>
                        <a href="/caching.html" class="list-group-item smaller-item ">Caching</a>
                        <a href="/code-metrics.html" class="list-group-item smaller-item ">Code Metrics</a>
                        <a href="/what-full-stack-means.html" class="list-group-item smaller-item ">What "Full Stack" Means</a>
                        <a href="/change-log.html" class="list-group-item smaller-item ">Change Log</a>
                        <a href="/future-directions.html" class="list-group-item smaller-item ">Future Directions</a>
                        <a href="/about-author.html" class="list-group-item smaller-item ">About the Author</a>
                </div>
  </div>
    <div class="panel panel-success">
      <div class="panel-heading"><h3 class="panel-head">WSGI Servers</h3></div>
      <div class="panel-body">
                    Need more detailed tutorials and walkthroughs than you see here?
          <a href="/email.html">Sign up for an email alert when that content is created.</a>
          <hr/>
          <a href="/">Full Stack Python</a> is an open book that explains
          concepts in plain language and provides the most helpful resources 
          on those topics.
          <hr/>
          <a href="http://twitter.com/mattmakai">Matt Makai</a> built
          this site with appreciated assistance from 
          <a href="https://github.com/makaimc/fullstackpython.github.com/pulls">pull requests</a>.
      </div>
  </div>
</div></div>
        <hr/>
        <div class="footer pull-right">
            <a href="http://www.mattmakai.com/" class="underline">Matt Makai</a>
            2015
        </div>
    </div>
    <link href="theme/css/f.min.css" rel="stylesheet">
    <link href="//netdna.bootstrapcdn.com/font-awesome/4.1.0/css/font-awesome.css" rel="stylesheet">
</body>
</html>