Flask: Improve warning about dev server use in production

[miguelgrinberg]

I'm preparing for my PyCon tutorial, for which I'm trying to look at things from the perspective of a beginner. The output of flask run is actually very confusing if you don't have a bit of background. Here is an example:

(venv) $ flask run
* Environment: production
  WARNING: Do not use the development server in a production environment.
  Use a production WSGI server instead.
* Debug mode: off
* Running on http://127.0.0.1:5000/ (Press CTRL+C to quit)

First of all, is this a development server? How would you know if you are new to Flask? And more importantly, we are told that we shouldn't use the development server in a production environment. But the line right above appears to claim the current environment is production!

I would like to propose a rewording of this warning to avoid ambiguous terms such as "environment". My proposal:

  WARNING: This is a development server. Do not use it in a production deployment.
  Use a production WSGI server instead.

Thoughts?

[davidism]

Sounds like a good first issue for the sprints. 👍

[twosigmajab]

@davidism Let me know I can help tag any of these with https://github.com/pallets/flask/labels/good%20first%20issue to make these easier to find for the sprinters!

[DamianSkrzypczak]

@davidism
@twosigmajab

I would love to take it but(!) only if you explain to me what does mean to be "sprinter" :smile: I'm pretty new to oss contribution.

[DamianSkrzypczak]

PR is created

... and I still don't know if sprinter is some kind of fast/minimal PR making person or it's related to scrum's time boxed work periods :smile: used for example for CD-like releasing purposes.

[ThiefMaster]

Sprinter = people taking part in one of the sprints at PyCon (which is currently ongoing, and I think @davidism is organizing some pallets-related sprints there)

[DamianSkrzypczak]

Wops :confused:
Sorry then ;x I wanted to get into contribution ^^.

Well, no one said that my PR must be taken into account. :smile:
I hope that I will find something else to do in project.

@ThiefMaster thanks for explanation, I would never think about that sprinter :smiley:

[DanielGoldfarb]

As a brand new Flask user, who's only experience with Flask was Miguel's tutorial last week, while the new text is somewhat clearer, it is very unclear to me what the difference is between a development vs production server. It would be nice if the message perhaps included a link to the documentation that explains the difference between a development vs. production server.

[DamianSkrzypczak]

@DanielGoldfarb
Maybe something like this?

WARNING: This is a development server. 
Do not use it in a production deployment.
(You can read more about development mode here:
http://flask.pocoo.org/docs/1.0/tutorial/factory/#run-the-application)

@ThiefMaster
I didn't found better source to link, maybe it would be good to make one?
I can it all (warning enhancement and additional page/section in sphinx)
but I need confirmation that it makes sense.

[DanielGoldfarb]

The _new_ text is this: "WARNING: This is a development server. Do not use it in a production deployment. Use a production WSGI server instead." which mentions WSGI server. The above link is about development mode, but if I am understanding this (and I'm not sure I am) this is not just about development "mode" per se, but about the fact that Flask is not meant to be a production web server. There is an interesting blog post here: https://vsupalov.com/flask-web-server-in-production/ which makes sound like Flask is really TWO servers: an application server and a web server, and while the application server portion may be well and good for production, "Flask’s built-in [web] server is not suitable for production as it doesn’t scale well and by default serves only one request at a time." Is that correct? And isn't that really what this error message is intending to warn about (i.e. not just the fact of being in "development" mode)?? If so, then I would want a link to some documentation that explains the difference between a "development server" and "a production WSGI server".

[miguelgrinberg]

Hi @DanielGoldfarb. In terms of WSGI there are WSGI servers and WSGI applications. Flask helps you build a WSGI application, and also provides a WSGI server that you can use to test this application during development. It does not provide a production scale WSGI server.

I'm not sure I like the idea of making the output of flask run even longer than it already is. The main point with this warning is to make sure people new to Flask understand that flask run is only used for development. My proposed changes clarify this a bit, and also remove the ambiguous use of the word "environment".

[DanielGoldfarb]

@miguelgrinberg. Thanks for clarifying. If the "main point with this warning is to make sure people new to Flask understand that flask run is only used for development" then I would agree that the proposed changes "clarify this a bit" ... However, I would suggest being even more explicit and getting rid of the pronoun "This" in "WARNING: This is a development server" --- and say rather " "WARNING: Flask is a development WSGI server. Do not use it in a production deployment. Use a production WSGI server instead."

[DanielGoldfarb]

please note, not meaning to belabor the point, but as a further indication that the phrase "_this_ is a development server" leads to some ambiguity as to what "_this_" is referring to, it appears that DamianSkrzypczak took it to mean that Flask was _presently_ in "development mode" (in other words, that the environment variable FLASK_ENV had a value of 'development').

[a2x]

Same thoughts here. The message shouldn’t contain anything like “environment” or “production”. It should be an explicit warning on what kind of server Flask contains and refer to the docs for building a proper understanding, which is essential to build and provide Flask app/service.

What about:
“WARNING: Flask contains a web server FOR DEVELOPMENT ONLY!
Please read the docs on how to deploy Flask apps/services http://flask.pocoo.org/docs/1.0/deploying/
“

[DamianSkrzypczak]

@DanielGoldfarb not exactly. I just didn't find any particularly good comparison of development/production modes that could be linked in this warning. I thought about http://flask.pocoo.org/docs/1.0/deploying/ and few others but I tried to find as much specific explanation as its possible... maybe that was wrong path :smile:

I agree with @miguelgrinberg about short warning and lack of detailed explanation but I also want to implement as best solution as possible.

[DanielGoldfarb]

I also now agree with @miguelgrinberg about short warning, and indeed it appears there may not be a particular document that focuses on the issue. (Furthermore, even though I was the one to bring up the idea: pointing to specific documents in an error message is NOT best practices because inevitably the link will break because sooner or later the document will be moved!) That said, I strongly stand by my earlier comment that use of the pronoun "this" is vague. If the warning is meant to convey that "Flask" itself should _never_ be used as a production _web_ service, then the warning message should say so very explicitly (and potentially the warning can do so in a way that is even a little shorter than what Miguel originally proposed, if we really want short). Once it is very explicit, googling about deploying flask is likely adequate to clarify the matter.

[DanielGoldfarb]

I just went back and re-read some earlier comments more carefully and I really like the wording by @a2x that "WARNING: Flask contains a web server FOR DEVELOPMENT ONLY!" I like the use of the word contains; I think that wording very explicitly says what the message is intended to convey. Thanks.

[DamianSkrzypczak]

@ThiefMaster what should I do? (I don't really understand rules of getting final decision yet - I had only few contrubutions.)

[alysbrooks]

I like the "WARNING: Flask contains a web server FOR DEVELOPMENT ONLY!" wording. However, I'm a little worried that by itself, it's not clear whether the built-in server is actually running or the message always appears when using Flask. (Obviously, that would be bad design, but I think we've all seen contextually inappropriate warnings.) Maybe add something like "Flask's development web server is running!"?

That would make the message:

WARNING: Flask's development web server is running! Flask contains a web server FOR DEVELOPMENT ONLY!

I was going to suggest changing the IP line from "Running on http://127.0.0.1:5000/" to "Web server running on http://127.0.0.1:5000/". However, that line comes from Werkzeug, which is actually doing the serving. In other words, it's arguably more accurate to say that Flask contains Werkzeug which contains a webserver... I don't think that makes the message misleading, but it is a bit incomplete, so I thought I'd mention that.

[davidism]

Hi, thanks for all your input, please don't bikeshed this.

We're not going to be able to convey the full meaning of what WSGI is, what the distinction between Flask and Werkzeug is, and what development vs production means in a small warning message. Ideally, someone who sees this warning should be sufficiently on notice to go do a little more research, at which point they'll find official docs, Stack Overflow answers, and tutorials all discussing it in more depth.

To clarify, neither Flask nor Werkzeug are "for development only". The bundled server is for development only. The "this" in the message seems pretty clear: it's the thing you just ran that's outputting a bunch of messages.