orbit-oss/flask
4
4
Fork 2
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

[pre-commit.ci lite] apply automatic fixes

Browse source
This commit is contained in:
pre-commit-ci-lite[bot] 2025-04-11 03:04:22 +00:00 • committed by GitHub
parent b3ae3117f9
commit 3d83d8138c
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
102 changed files with 26790 additions and 26749 deletions
Download patch file Download diff file Expand all files Collapse all files

185
flask-docs/deploying/gunicorn.html
View file

@ -5,7 +5,7 @@
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>Gunicorn &#8212; Flask Documentation (3.2.x)</title>
<title>nginx &#8212; Flask Documentation (3.2.x)</title>
<link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=6625fa76" />
<link rel="stylesheet" type="text/css" href="../_static/flask.css?v=b87c8d14" />
<script src="../_static/documentation_options.js?v=56528222"></script>
@ -15,8 +15,8 @@
<link rel="icon" href="../_static/shortcut-icon.png"/>
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="next" title="Waitress" href="waitress.html" />
<link rel="prev" title="Deploying to Production" href="index.html" />
<link rel="next" title="Apache httpd" href="apache-httpd.html" />
<link rel="prev" title="Tell Flask it is Behind a Proxy" href="proxy_fix.html" />
</head><body>
<div class="related" role="navigation" aria-label="Related">
<h3>Navigation</h3>
@ -28,123 +28,80 @@
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="waitress.html" title="Waitress"
<a href="apache-httpd.html" title="Apache httpd"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="index.html" title="Deploying to Production"
<a href="proxy_fix.html" title="Tell Flask it is Behind a Proxy"
accesskey="P">previous</a> |</li>
<li class="nav-item nav-item-0"><a href="../index.html">Flask Documentation (3.2.x)</a> &#187;</li>
<li class="nav-item nav-item-1"><a href="index.html" accesskey="U">Deploying to Production</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">Gunicorn</a></li>
<li class="nav-item nav-item-this"><a href="">nginx</a></li>
</ul>
</div>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<section id="gunicorn">
<h1>Gunicorn<a class="headerlink" href="#gunicorn" title="Link to this heading"></a></h1>
<p><a class="reference external" href="https://gunicorn.org/">Gunicorn</a> is a pure Python WSGI server with simple configuration and
multiple worker implementations for performance tuning.</p>
<ul class="simple">
<li><p>It tends to integrate easily with hosting platforms.</p></li>
<li><p>It does not support Windows (but does run on WSL).</p></li>
<li><p>It is easy to install as it does not require additional dependencies
or compilation.</p></li>
<li><p>It has built-in async worker support using gevent or eventlet.</p></li>
</ul>
<p>This page outlines the basics of running Gunicorn. Be sure to read its
<a class="reference external" href="https://docs.gunicorn.org/">documentation</a> and use <code class="docutils literal notranslate"><span class="pre">gunicorn</span> <span class="pre">--help</span></code> to understand what features
are available.</p>
<section id="installing">
<h2>Installing<a class="headerlink" href="#installing" title="Link to this heading"></a></h2>
<p>Gunicorn is easy to install, as it does not require external
dependencies or compilation. It runs on Windows only under WSL.</p>
<p>Create a virtualenv, install your application, then install
<code class="docutils literal notranslate"><span class="pre">gunicorn</span></code>.</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ cd hello-app
$ python -m venv .venv
$ . .venv/bin/activate
$ pip install . # install your application
$ pip install gunicorn
</pre></div>
</div>
</section>
<section id="running">
<h2>Running<a class="headerlink" href="#running" title="Link to this heading"></a></h2>
<p>The only required argument to Gunicorn tells it how to load your Flask
application. The syntax is <code class="docutils literal notranslate"><span class="pre">{module_import}:{app_variable}</span></code>.
<code class="docutils literal notranslate"><span class="pre">module_import</span></code> is the dotted import name to the module with your
application. <code class="docutils literal notranslate"><span class="pre">app_variable</span></code> is the variable with the application. It
can also be a function call (with any arguments) if you’re using the
app factory pattern.</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span># equivalent to &#39;from hello import app&#39;
$ gunicorn -w 4 &#39;hello:app&#39;
# equivalent to &#39;from hello import create_app; create_app()&#39;
$ gunicorn -w 4 &#39;hello:create_app()&#39;
<section id="nginx">
<h1>nginx<a class="headerlink" href="#nginx" title="Link to this heading"></a></h1>
<p><a class="reference external" href="https://nginx.org/">nginx</a> is a fast, production level HTTP server. When serving your
application with one of the WSGI servers listed in <a class="reference internal" href="index.html"><span class="doc">Deploying to Production</span></a>, it is
often good or necessary to put a dedicated HTTP server in front of it.
This “reverse proxy” can handle incoming requests, TLS, and other
security and performance concerns better than the WSGI server.</p>
<p>Nginx can be installed using your system package manager, or a pre-built
executable for Windows. Installing and running Nginx itself is outside
the scope of this doc. This page outlines the basics of configuring
Nginx to proxy your application. Be sure to read its documentation to
understand what features are available.</p>
<section id="domain-name">
<h2>Domain Name<a class="headerlink" href="#domain-name" title="Link to this heading"></a></h2>
<p>Acquiring and configuring a domain name is outside the scope of this
doc. In general, you will buy a domain name from a registrar, pay for
server space with a hosting provider, and then point your registrar
at the hosting provider’s name servers.</p>
<p>To simulate this, you can also edit your <code class="docutils literal notranslate"><span class="pre">hosts</span></code> file, located at
<code class="docutils literal notranslate"><span class="pre">/etc/hosts</span></code> on Linux. Add a line that associates a name with the
local IP.</p>
<p>Modern Linux systems may be configured to treat any domain name that
ends with <code class="docutils literal notranslate"><span class="pre">.localhost</span></code> like this without adding it to the <code class="docutils literal notranslate"><span class="pre">hosts</span></code>
file.</p>
<div class="literal-block-wrapper docutils container" id="id2">
<div class="code-block-caption"><span class="caption-text"><code class="docutils literal notranslate"><span class="pre">/etc/hosts</span></code></span><a class="headerlink" href="#id2" title="Link to this code"></a></div>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="mf">127.0.0.1</span> <span class="n">hello</span><span class="o">.</span><span class="n">localhost</span>
</pre></div>
</div>
</div>
</section>
<section id="configuration">
<h2>Configuration<a class="headerlink" href="#configuration" title="Link to this heading"></a></h2>
<p>The nginx configuration is located at <code class="docutils literal notranslate"><span class="pre">/etc/nginx/nginx.conf</span></code> on
Linux. It may be different depending on your operating system. Check the
docs and look for <code class="docutils literal notranslate"><span class="pre">nginx.conf</span></code>.</p>
<p>Remove or comment out any existing <code class="docutils literal notranslate"><span class="pre">server</span></code> section. Add a <code class="docutils literal notranslate"><span class="pre">server</span></code>
section and use the <code class="docutils literal notranslate"><span class="pre">proxy_pass</span></code> directive to point to the address the
WSGI server is listening on. We’ll assume the WSGI server is listening
locally at <code class="docutils literal notranslate"><span class="pre">http://127.0.0.1:8000</span></code>.</p>
<div class="literal-block-wrapper docutils container" id="id3">
<div class="code-block-caption"><span class="caption-text"><code class="docutils literal notranslate"><span class="pre">/etc/nginx.conf</span></code></span><a class="headerlink" href="#id3" title="Link to this code"></a></div>
<div class="highlight-nginx notranslate"><div class="highlight"><pre><span></span><span class="k">server</span><span class="w"> </span><span class="p">{</span>
<span class="w"> </span><span class="kn">listen</span><span class="w"> </span><span class="mi">80</span><span class="p">;</span>
<span class="w"> </span><span class="kn">server_name</span><span class="w"> </span><span class="s">_</span><span class="p">;</span>
Starting gunicorn 20.1.0
Listening at: http://127.0.0.1:8000 (x)
Using worker: sync
Booting worker with pid: x
Booting worker with pid: x
Booting worker with pid: x
Booting worker with pid: x
<span class="w"> </span><span class="kn">location</span><span class="w"> </span><span class="s">/</span><span class="w"> </span><span class="p">{</span>
<span class="w"> </span><span class="kn">proxy_pass</span><span class="w"> </span><span class="s">http://127.0.0.1:8000/</span><span class="p">;</span>
<span class="w"> </span><span class="kn">proxy_set_header</span><span class="w"> </span><span class="s">X-Forwarded-For</span><span class="w"> </span><span class="nv">$proxy_add_x_forwarded_for</span><span class="p">;</span>
<span class="w"> </span><span class="kn">proxy_set_header</span><span class="w"> </span><span class="s">X-Forwarded-Proto</span><span class="w"> </span><span class="nv">$scheme</span><span class="p">;</span>
<span class="w"> </span><span class="kn">proxy_set_header</span><span class="w"> </span><span class="s">X-Forwarded-Host</span><span class="w"> </span><span class="nv">$host</span><span class="p">;</span>
<span class="w"> </span><span class="kn">proxy_set_header</span><span class="w"> </span><span class="s">X-Forwarded-Prefix</span><span class="w"> </span><span class="s">/</span><span class="p">;</span>
<span class="w"> </span><span class="p">}</span>
<span class="p">}</span>
</pre></div>
</div>
<p>The <code class="docutils literal notranslate"><span class="pre">-w</span></code> option specifies the number of processes to run; a starting
value could be <code class="docutils literal notranslate"><span class="pre">CPU</span> <span class="pre">*</span> <span class="pre">2</span></code>. The default is only 1 worker, which is
probably not what you want for the default worker type.</p>
<p>Logs for each request aren’t shown by default, only worker info and
errors are shown. To show access logs on stdout, use the
<code class="docutils literal notranslate"><span class="pre">--access-logfile=-</span></code> option.</p>
</section>
<section id="binding-externally">
<h2>Binding Externally<a class="headerlink" href="#binding-externally" title="Link to this heading"></a></h2>
<p>Gunicorn should not be run as root because it would cause your
application code to run as root, which is not secure. However, this
means it will not be possible to bind to port 80 or 443. Instead, a
reverse proxy such as <a class="reference internal" href="nginx.html"><span class="doc">nginx</span></a> or <a class="reference internal" href="apache-httpd.html"><span class="doc">Apache httpd</span></a> should be used
in front of Gunicorn.</p>
<p>You can bind to all external IPs on a non-privileged port using the
<code class="docutils literal notranslate"><span class="pre">-b</span> <span class="pre">0.0.0.0</span></code> option. Don’t do this when using a reverse proxy setup,
otherwise it will be possible to bypass the proxy.</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ gunicorn -w 4 -b 0.0.0.0 &#39;hello:create_app()&#39;
Listening at: http://0.0.0.0:8000 (x)
</pre></div>
</div>
<p><code class="docutils literal notranslate"><span class="pre">0.0.0.0</span></code> is not a valid address to navigate to, you’d use a specific
IP address in your browser.</p>
</section>
<section id="async-with-gevent-or-eventlet">
<h2>Async with gevent or eventlet<a class="headerlink" href="#async-with-gevent-or-eventlet" title="Link to this heading"></a></h2>
<p>The default sync worker is appropriate for many use cases. If you need
asynchronous support, Gunicorn provides workers using either <a class="reference external" href="https://www.gevent.org/">gevent</a>
or <a class="reference external" href="https://eventlet.net/">eventlet</a>. This is not the same as Python’s <code class="docutils literal notranslate"><span class="pre">async/await</span></code>, or the
ASGI server spec. You must actually use gevent/eventlet in your own code
to see any benefit to using the workers.</p>
<p>When using either gevent or eventlet, greenlet&gt;=1.0 is required,
otherwise context locals such as <code class="docutils literal notranslate"><span class="pre">request</span></code> will not work as expected.
When using PyPy, PyPy&gt;=7.3.7 is required.</p>
<p>To use gevent:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ gunicorn -k gevent &#39;hello:create_app()&#39;
Starting gunicorn 20.1.0
Listening at: http://127.0.0.1:8000 (x)
Using worker: gevent
Booting worker with pid: x
</pre></div>
</div>
<p>To use eventlet:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ gunicorn -k eventlet &#39;hello:create_app()&#39;
Starting gunicorn 20.1.0
Listening at: http://127.0.0.1:8000 (x)
Using worker: eventlet
Booting worker with pid: x
</pre></div>
</div>
<p>Then <a class="reference internal" href="proxy_fix.html"><span class="doc">Tell Flask it is Behind a Proxy</span></a> so that your application uses these headers.</p>
</section>
</section>
@ -156,20 +113,18 @@ Booting worker with pid: x
<span id="sidebar-top"></span>
<div class="sphinxsidebar" role="navigation" aria-label="Main">
<div class="sphinxsidebarwrapper">
<p class="logo"><a href="../index.html">
<img class="logo" src="../_static/flask-vertical.png" alt="Logo of Flask"/>
</a></p>
<h3>Contents</h3>
<ul>
<li><a class="reference internal" href="#">Gunicorn</a><ul>
<li><a class="reference internal" href="#installing">Installing</a></li>
<li><a class="reference internal" href="#running">Running</a></li>
<li><a class="reference internal" href="#binding-externally">Binding Externally</a></li>
<li><a class="reference internal" href="#async-with-gevent-or-eventlet">Async with gevent or eventlet</a></li>
<li><a class="reference internal" href="#">nginx</a><ul>
<li><a class="reference internal" href="#domain-name">Domain Name</a></li>
<li><a class="reference internal" href="#configuration">Configuration</a></li>
</ul>
</li>
</ul>
@ -179,8 +134,8 @@ Booting worker with pid: x
<ul>
<li><a href="index.html">Deploying to Production</a>
<ul>
<li>Previous: <a href="index.html" title="previous chapter">Deploying to Production</a>
<li>Next: <a href="waitress.html" title="next chapter">Waitress</a></ul>
<li>Previous: <a href="proxy_fix.html" title="previous chapter">Tell Flask it is Behind a Proxy</a>
<li>Next: <a href="apache-httpd.html" title="next chapter">Apache httpd</a></ul>
</li>
</ul>
</li>
@ -204,4 +159,4 @@ Booting worker with pid: x
Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 8.1.3.
</div>
</body>
</html>
</html>