mirror of
https://github.com/frappe/gunicorn.git
synced 2026-01-14 11:09:11 +08:00
212 lines
9.0 KiB
HTML
212 lines
9.0 KiB
HTML
<!DOCTYPE html>
|
|
<html lang="en">
|
|
<head>
|
|
<meta charset="utf-8" />
|
|
<title>Green Unicorn - Command Line Usage</title>
|
|
<link rel="alternate" type="application/rss+xml" href="/feed.xml" />
|
|
<link rel="stylesheet" href="css/style.css" type="text/css" media="screen" />
|
|
</head>
|
|
<body>
|
|
<div class="container">
|
|
<div id="header">
|
|
<a href="http://gunicorn.org">
|
|
<img src="/images/logo.png" alt="Gunicorn - Green Unicorn" />
|
|
</a>
|
|
</div>
|
|
<div id="menu">
|
|
<ul id="actions">
|
|
<li><a href="install.html">Install</a></li>
|
|
<li><a href="configure.html">Configure</a></li>
|
|
<li><a href="deploy.html">Deploy</a></li>
|
|
<li><a href="faq.html">FAQ</a></li>
|
|
<li><a href="news.html">News</a></li>
|
|
</ul>
|
|
</div>
|
|
<div class="document" id="usage">
|
|
<h1 class="title">Usage</h1>
|
|
<p>After installing Gunicorn you will have access to three command line scripts
|
|
that can be used for serving the various supported web frameworks: <tt class="docutils literal">gunicorn</tt>,
|
|
<tt class="docutils literal">gunicorn_django</tt>, and <tt class="docutils literal">gunicorn_paster</tt>.</p>
|
|
<div class="section" id="commonly-used-arguments">
|
|
<h2>Commonly Used Arguments</h2>
|
|
<blockquote>
|
|
<dl class="docutils">
|
|
<dt><tt class="docutils literal"><span class="pre">-c</span> CONFIG, <span class="pre">--config=CONFIG</span></tt></dt>
|
|
<dd>Specify the path to a <a class="reference external" href="configuration.html">config file</a></dd>
|
|
<dt><tt class="docutils literal"><span class="pre">-b</span> BIND, <span class="pre">--bind=BIND</span></tt></dt>
|
|
<dd>Specify a server socket to bind. Server sockets can be any of <tt class="docutils literal">$(HOST)</tt>,
|
|
<tt class="docutils literal"><span class="pre">$(HOST):$(PORT)</span></tt>, or <tt class="docutils literal"><span class="pre">unix:$(PATH)</span></tt>. An IP is a valid <tt class="docutils literal">$(HOST)</tt>.</dd>
|
|
<dt><tt class="docutils literal"><span class="pre">-w</span> WORKERS, <span class="pre">--workers=WORKERS</span></tt></dt>
|
|
<dd>The number of worker processes. This number should generally be between 2-4
|
|
workers per core in the server. Check the <a class="reference external" href="faq.html">FAQ</a> for ideas on tuning this
|
|
parameter.</dd>
|
|
<dt><tt class="docutils literal"><span class="pre">-k</span> WORKERCLASS, <span class="pre">--worker-class=WORKERCLASS</span></tt></dt>
|
|
<dd>The type of worker process to run. You'll definitely want to read the
|
|
<a class="reference external" href="deployment.html">production page</a> for the implications of this parameter. You can set this
|
|
to <tt class="docutils literal"><span class="pre">egg:gunicorn#$(NAME)</span></tt> where <tt class="docutils literal">$(NAME)</tt> is one of <tt class="docutils literal">sync</tt>,
|
|
<tt class="docutils literal">eventlet</tt>, <tt class="docutils literal">gevent</tt>, or <tt class="docutils literal">tornado</tt>. <tt class="docutils literal">sync</tt> is the default.</dd>
|
|
<dt><tt class="docutils literal"><span class="pre">-n</span> APP_NAME, <span class="pre">--name=APP_NAME</span></tt></dt>
|
|
<dd>If <a class="reference external" href="http://pypi.python.org/pypi/setproctitle/">setproctitle</a> is installed you can adjust the name of Gunicorn process as
|
|
they appear in the process system table (which affects tools like <tt class="docutils literal">ps</tt> and
|
|
<tt class="docutils literal">top</tt>).</dd>
|
|
</dl>
|
|
</blockquote>
|
|
<p>There are various other parameters that affect user privileges, logging, etc.
|
|
You can see the complete list at the bottom of this page or as expected with:</p>
|
|
<pre class="literal-block">
|
|
$ gunicorn -h
|
|
</pre>
|
|
</div>
|
|
<div class="section" id="gunicorn">
|
|
<h2>gunicorn</h2>
|
|
<p>The first and most basic script is used to server 'bare' WSGI applications
|
|
that don't require a translation layer. Basic usage:</p>
|
|
<pre class="literal-block">
|
|
$ gunicorn [OPTIONS] APP_MODULE
|
|
</pre>
|
|
<p>Where <tt class="docutils literal">APP_MODULE</tt> is of the pattern <tt class="docutils literal"><span class="pre">$(MODULE_NAME):$(VARIABLE_NAME)</span></tt>. The
|
|
module name can be a full dotted path. The variable name refers to a WSGI
|
|
callable that should be found in the specified module.</p>
|
|
<p>Example with test app:</p>
|
|
<pre class="literal-block">
|
|
$ cd examples
|
|
$ gunicorn --workers=2 test:app
|
|
</pre>
|
|
</div>
|
|
<div class="section" id="gunicorn-django">
|
|
<h2>gunicorn_django</h2>
|
|
<p>You might not have guessed it, but this script is used to server Django
|
|
applications. Basic usage:</p>
|
|
<pre class="literal-block">
|
|
$ gunicorn_django [OPTIONS] [SETTINGS_PATH]
|
|
</pre>
|
|
<p>By default <tt class="docutils literal">SETTINGS_PATH</tt> will look for <tt class="docutils literal">settings.py</tt> in the current
|
|
directory.</p>
|
|
<p>Example with your Django project:</p>
|
|
<pre class="literal-block">
|
|
$ cd path/to/yourdjangoproject
|
|
$ gunicorn_django --workers=2
|
|
</pre>
|
|
<p>Alternatively, you can install some Gunicorn magic directly into your Django
|
|
project and use the provided command for running the server.</p>
|
|
<p>First you'll need to add <tt class="docutils literal">gunicorn</tt> to your <tt class="docutils literal">INSTALLED_APPS</tt> in the settings
|
|
file:</p>
|
|
<pre class="literal-block">
|
|
INSTALLED_APPS = (
|
|
...
|
|
"gunicorn",
|
|
)
|
|
</pre>
|
|
<p>Then you can run:</p>
|
|
<pre class="literal-block">
|
|
python manage.py run_gunicorn
|
|
</pre>
|
|
</div>
|
|
<div class="section" id="gunicorn-paster">
|
|
<h2>gunicorn_paster</h2>
|
|
<p>Yeah, for Paster-compatible frameworks (Pylons, TurboGears 2, ...). We
|
|
apologize for the lack of script name creativity. And some usage:</p>
|
|
<pre class="literal-block">
|
|
$ gunicorn_paster [OPTIONS] paste_config.ini
|
|
</pre>
|
|
<p>Simple example:</p>
|
|
<pre class="literal-block">
|
|
$ cd yourpasteproject
|
|
$ gunicorn_paste --workers=2 development.ini
|
|
</pre>
|
|
<p>If you're wanting to keep on keeping on with the usual paster serve command,
|
|
you can specify the Gunicorn server settings in your configuration file:</p>
|
|
<pre class="literal-block">
|
|
[server:main]
|
|
use = egg:gunicorn#main
|
|
host = 127.0.0.1
|
|
port = 5000
|
|
</pre>
|
|
<p>And then as per usual:</p>
|
|
<pre class="literal-block">
|
|
$ cd yourpasteproject
|
|
$ paster serve development.ini workers=2
|
|
</pre>
|
|
</div>
|
|
<div class="section" id="full-command-line-usage">
|
|
<h2>Full Command Line Usage</h2>
|
|
<pre class="literal-block">
|
|
$ gunicorn -h
|
|
Usage: gunicorn [OPTIONS] APP_MODULE
|
|
|
|
Options:
|
|
-c CONFIG, --config=CONFIG
|
|
Config file. [none]
|
|
-b BIND, --bind=BIND Adress to listen on. Ex. 127.0.0.1:8000 or
|
|
unix:/tmp/gunicorn.sock
|
|
-w WORKERS, --workers=WORKERS
|
|
Number of workers to spawn. [1]
|
|
-k WORKER_CLASS, --worker-class=WORKER_CLASS
|
|
The type of request processing to use
|
|
[egg:gunicorn#sync]
|
|
-p PIDFILE, --pid=PIDFILE
|
|
set the background PID FILE
|
|
-D, --daemon Run daemonized in the background.
|
|
-m UMASK, --umask=UMASK
|
|
Define umask of daemon process
|
|
-u USER, --user=USER Change worker user
|
|
-g GROUP, --group=GROUP
|
|
Change worker group
|
|
-n PROC_NAME, --name=PROC_NAME
|
|
Process name
|
|
--log-level=LOGLEVEL Log level below which to silence messages. [info]
|
|
--log-file=LOGFILE Log to a file. - equals stdout. [-]
|
|
--debug Debug mode. only 1 worker.
|
|
--spew Install a trace hook
|
|
--version show program's version number and exit
|
|
-h, --help show this help message and exit
|
|
</pre>
|
|
</div>
|
|
<div class="section" id="framework-examples">
|
|
<h2>Framework Examples</h2>
|
|
<p>This is an incomplete list of examples of using Gunicorn with various
|
|
Python web frameworks. If you have an example to add you're very much
|
|
invited to submit a ticket to the <a class="reference external" href="http://github.com/benoitc/gunicorn/issues">issue tracker</a> to have it included.</p>
|
|
<div class="section" id="itty">
|
|
<h3>Itty</h3>
|
|
<p>Itty comes with builtin Gunicorn support. The Itty "Hello, world!" looks
|
|
like such:</p>
|
|
<pre class="literal-block">
|
|
from itty import *
|
|
|
|
@get('/')
|
|
def index(request):
|
|
return 'Hello World!'
|
|
|
|
run_itty(server='gunicorn')
|
|
</pre>
|
|
</div>
|
|
<div class="section" id="flask">
|
|
<h3>Flask</h3>
|
|
<p>Flask applications are WSGI compatible. Given this Flask app in an importable
|
|
Python module "helloflask.py":</p>
|
|
<pre class="literal-block">
|
|
from flask import Flask
|
|
app = Flask(__name__)
|
|
|
|
@app.route("/")
|
|
def hello():
|
|
return "Hello World!"
|
|
</pre>
|
|
<p>Gunicorn can then be used to run it as such:</p>
|
|
<pre class="literal-block">
|
|
$ gunicorn helloflask:app
|
|
</pre>
|
|
<p>Remember, if you're just trying to get things up and runnign that "importable"
|
|
can be as simple as "exists in the current directory".</p>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
|
|
<div id="footer">
|
|
<p>This work is licensed under a <a rel="license" href="http://creativecommons.org/licenses/by/3.0/">Creative Commons Attribution 3.0 Unported License</a>.</p>
|
|
<p>Hosted on <a href="http://github.com/">Github</a></p>
|
|
</div>
|
|
</div>
|
|
</body>
|
|
</html> |