How to deploy a Flask app without Docker

Flask is small enough that it's often a team's first deployment, and that means hitting several production questions at once with no framework opinion to lean on. Django would have told you what to do. Flask assumes you know.

Here's the short version of what you need to know, in the order it matters. No Dockerfile required — a repo with a requirements file and a WSGI entry point is enough for any platform with Python build detection. Commands are PandaStack's.

1. Stop using the development server

`flask run` is single-threaded by default, has no process supervision, and its debugger is a remote code execution vector if it ever reaches the internet. The warning it prints is not a formality.

In production you run a real WSGI server — Gunicorn is the default choice — pointed at your application object.

# A module-level app object
gunicorn "app:app" --workers 3 --timeout 60 --bind 0.0.0.0:$PORT

# An application factory — note the call syntax
gunicorn "app:create_app()" --workers 3 --bind 0.0.0.0:$PORT

# Async views or a lot of I/O waiting? Threads are cheaper than processes
gunicorn "app:create_app()" --workers 2 --threads 4 --bind 0.0.0.0:$PORT

2. Use an application factory

A module-level `app = Flask(__name__)` works and gets awkward fast: configuration is bound at import time, tests share one instance, and extensions get initialised in whatever order the imports happen to run.

A factory function makes configuration explicit and testable, and Gunicorn calls it directly.

import os
from flask import Flask

def create_app(config=None):
    app = Flask(__name__)

    # Fail loudly at startup if a required secret is missing, rather than
    # silently running with a default that makes sessions forgeable
    app.config["SECRET_KEY"] = os.environ["SECRET_KEY"]
    app.config["SQLALCHEMY_DATABASE_URI"] = os.environ["DATABASE_URL"]
    if config:
        app.config.update(config)

    from .routes import bp
    app.register_blueprint(bp)
    return app

3. Understand what multiple workers break

This is the part that catches people, because everything works locally with one process and fails intermittently in production with three.

• Module-level dictionaries used as caches. Each worker has its own, so a value written by one is invisible to the others. Symptom: a cache that works about a third of the time.
• In-memory rate limiters. Three workers means three times your intended limit. Use Redis.
• Filesystem-backed sessions. Each worker writes to its own view of disk on an ephemeral filesystem. Use signed cookies or a shared store.
• Background threads started at import. Each worker starts its own, so a periodic job runs three times as often. This is how duplicate emails happen.
• SQLAlchemy engines created before fork. Connections get shared across processes and corrupt in ways that are extremely confusing to debug. Create the engine inside the factory, or dispose the pool in a post-fork hook.

4. Configuration from the environment

Read secrets from environment variables, and read them without a default. A SECRET_KEY that falls back to a hard-coded string means anyone who has read your repository can forge sessions, and the app will never tell you it's happening.

# Pin the interpreter, then deploy from git
echo "3.12" > .python-version

pandastack apps create --name api \
  --git-url https://github.com/acme/flask-api \
  --build-cmd 'pip install -r requirements.txt' \
  --start-cmd 'gunicorn "app:create_app()" --workers 3 --bind 0.0.0.0:$PORT'

# Secrets as environment variables — never in the repository
pandastack apps env set api SECRET_KEY="$(openssl rand -hex 32)"

5. Database connections

Your total connection count is pool size × workers × instances. Three workers with a pool of five across two instances is thirty connections, which is fine — until you scale to eight instances and discover the database's limit is a hundred and something else needed connections too.

Set the pool size explicitly rather than accepting the default, and make sure the session is removed at the end of each request so connections return to the pool.

6. Log to stdout, and give yourself a request id

Flask's default logging is aimed at development. In production your platform collects stdout and stderr, so anything written to a file inside the instance is invisible and disappears at the next deploy. Configure logging to stdout explicitly and at INFO rather than the default WARNING, or you will eventually debug an incident with nothing to look at.

Emitting JSON rather than free text is worth it if your platform indexes logs, because structured fields let you filter by user or route during an incident instead of scrolling. More useful still is a request id: generate one per request, attach it to every log line, and return it in a response header. When a customer reports an error at 14:32, that identifier is the difference between finding the request in ten seconds and never finding it.

Before real traffic

1. Confirm the debugger is off. Flask's debug mode reachable from the internet is remote code execution, not a rough edge.
2. Run with the production worker count and hit an endpoint that uses any module-level state. If behaviour varies between requests, you found a per-worker state bug.
3. Multiply pool size by workers by instances and compare to the database's limit.
4. Deploy while sending traffic and watch for 502s during the flip — that's shutdown handling.
5. Check that no secret has a default value in code. Grep for os.environ.get with a fallback.

The short version

Gunicorn instead of the development server, an application factory, secrets from the environment with no defaults, and an honest audit of anything stored at module level — because that's what multiple workers turn from a convenience into an intermittent bug. None of it needs a Dockerfile, and all of it takes about an hour the first time.