Docs: serving WSGI app modules from Gunicorn

[jakethedev]

I had a use case where I needed to be able to standardize how our servers are running, but the application code could vary wildly within the scope of existing as a WSGI app ala flask or django. This had to happen within a PEX context, and I was able to get it working nicely and reliably after digging through the Gunicorn source to find this approach. Now I've got a happy little scaffold for wsgi apps that is standard for our company that works well PEX files by including Gunicorn in the build, but it was a real pain to figure this out, and it would've save me a day or two of researching in circles if this was mentioned somewhere

Hope this matches appropriate formatting, I checked CONTRIBUTING and it didn't mention much about docs and Github isn't rendering the preview quite right

[tilgovi]

Thanks so much, @jakethedev. I'm fine for this to be in the documentation.

[tilgovi]

I'm not sure I see why you're doing this, though. gunicorn is that entry point. Why would you need to do python run.py vs gunicorn?

[jakethedev]

Sweet!

Initially for flexibility, and the assumption that we'd have system daemons coming out of the same build process as the Gunicorn apps. That pushed us to move that complexity into how PEX was invoked, which led to a pretty big road block. We found that PEX requires either a single pythonic entry point (like app:serve), or a script. It refuses to take two words as a command, even properly quoted off as a single command - it just can't handle something like 'pex -c "gunicorn flaskexample:app" '.

So, building a PEX around a wsgi app requires a runnable script that does all the work, and this PR is the result of climbing that mountain and arriving at "bundle gunicorn with the app and bolt them together with a script" 😅 It seems that starting Gunicorn like this is a bit like push starting a car. It's rock solid, if a bit unorthodox, so I can dig it if you think this should go undocumented as it relies on internals, but it seemed worth sending your way in case others have the same issues getting WSGI apps and PEX to play well together

Minor additional note: Setting gunicorn as the entry point for PEX and passing along the name of the WSGI instance makes sense, and we definitely tried it - PEX will build the artifact that way, but running it results in exceptions where PEX refuses to run Gunicorn on its own regardless of parameters passed to it

[tilgovi]

Thanks for the explanation! The gunicorn.app.wsgiapp module is a runnable script that does this!

[jakethedev]

Oh, sweet, that works perfectly! I'm happy to update and simplify the chunk of text I wrote in the initial commit for this if it's still relevant to add, it looks like the .wsgiapp isn't currently referenced in the docs anywhere

[tilgovi]

@jakethedev that would be great!

[jakethedev]

Cleaned it up and simplified the docs, let me know if I can clean it up further or if I missed something obvious. Thanks for clearing up the usage of wsgiapp, I'm still trying to figure out how I saw that code and didn't see the main at the bottom haha

[jakethedev]

PS I think this might resolve #1429 😄

[jakethedev]

Just finished working with the PEX maintainers to update some docs on PEX usage, and remembered that this was still open - cleaned up a bit of wording and made the PEX usage note better. Lmk if there's anything else I should tweak on this pre-merge 😄

[benoitc]

@tilgovi since you looked it at first, still OK to merge it ? Changes look good for me.

[tilgovi]

Looks good to me.

[berkerpeksag]

Thanks!