diff --git a/docs/source/custom.rst b/docs/source/custom.rst index 20dae4db..36b2c9fd 100644 --- a/docs/source/custom.rst +++ b/docs/source/custom.rst @@ -14,3 +14,37 @@ a custom Application: .. literalinclude:: ../../examples/standalone_app.py :lines: 11-60 + +Direct Usage of Existing WSGI Apps +---------------------------------- + +If necessary, you can run Gunicorn straight from Python, allowing you to +specify a WSGI-compatible application at runtime. This can be handy for +rolling deploys or in the case of using PEX files to deploy your application, +as the app and Gunicorn can be bundled in the same PEX file. Gunicorn has +this functionality built-in as a first class citizen known as +:class:`gunicorn.app.wsgiapp`. This can be used to run WSGI-compatible app +instances such as those produced by Flask or Django. Assuming your WSGI API +package is *exampleapi*, and your application instance is *app*, this is all +you need to get going:: + + gunicorn.app.wsgiapp exampleapi:app + +This command will work with any Gunicorn CLI parameters or a config file - just +pass them along as if you're directly giving them to Gunicorn: + +.. code-block:: bash + # Custom parameters + $ python gunicorn.app.wsgiapp exampleapi:app --bind=0.0.0.0:8081 --workers=4 + # Using a config file + $ python gunicorn.app.wsgiapp exampleapi:app -c config.py + +Note for those using PEX: use ``-c gunicorn`` as your entry at build +time, and your compiled app should work with the entry point passed to it at +run time. + +.. code-block:: bash + # Generic pex build command via bash from root of exampleapi project + $ pex . -v -c gunicorn -o compiledapp.pex + # Running it + ./compiledapp.pex exampleapi:app -c gunicorn_config.py