Docker vs Flask Comparison for Beginners

# app.py — a minimal Flask API
# The "what" you build before worrying about Docker.

from flask import Flask, jsonify, request

app = Flask(__name__)

# In-memory store, replaced by a database later
todos = []


@app.get("/health")
def health():
    return jsonify(status="ok", service="flask-todos")


@app.get("/todos")
def list_todos():
    return jsonify(todos)


@app.post("/todos")
def create_todo():
    data = request.get_json()
    if not data or "title" not in data:
        return jsonify(error="title is required"), 400
    todo = {"id": len(todos) + 1, "title": data["title"]}
    todos.append(todo)
    return jsonify(todo), 201


if __name__ == "__main__":
    app.run(host="0.0.0.0", port=5000)


# Why this matters for the Flask-first path:
# - You have a real running app in minutes: `python app.py`.
# - You can test it in a browser at http://localhost:5000.
# - You now have a "what" you can containerise with Docker.
#
# What you learn here:
# - How Flask routes requests to functions
# - How to return JSON and set status codes
# - Why a health endpoint is a natural first test

# Dockerfile — packaging the Flask app above
# This file only makes sense because there is a Flask app to package.

FROM python:3.11-slim

ENV PYTHONDONTWRITEBYTECODE=1 \
    PYTHONUNBUFFERED=1

WORKDIR /app

COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY . .

EXPOSE 5000

CMD ["gunicorn", "--bind", "0.0.0.0:5000", "app:app"]

# Why this makes sense only after Flask:
# - You already know that "app" is the Flask module.
# - You know what port Flask runs on.
# - You know what gunicorn is (a WSGI server) and why it replaces `flask run` in production.
# - You know why requirements.txt exists.
#
# What you learn here:
# - How a base image, working directory, and copy layer work
# - How dependencies are installed inside the container
# - How to set the command that runs when the container starts
# - Why the same image runs the same way everywhere

# docker-compose.yml — Flask + Postgres in one command
# This is the real "Flask + Docker" workflow you will see in every team.

version: "3.9"

services:
  web:
    build: .
    command: gunicorn --bind 0.0.0.0:5000 app:app
    volumes:
      - .:/app
    ports:
      - "5000:5000"
    environment:
      - DATABASE_URL=postgresql://postgres:postgres@db:5432/todos
    depends_on:
      - db

  db:
    image: postgres:16
    environment:
      - POSTGRES_USER=postgres
      - POSTGRES_PASSWORD=postgres
      - POSTGRES_DB=todos
    volumes:
      - postgres_data:/var/lib/postgresql/data
    ports:
      - "5432:5432"

volumes:
  postgres_data:

# Why this is the right next step after Flask + Dockerfile:
# - You can bring up a database with the same command as the app.
# - The same setup works for every developer on the team.
# - You stop hearing "it works on my machine".
#
# What you learn here:
# - How services talk to each other by name
# - How environment variables configure apps
# - Why volumes matter for database data
# - How one command replaces hours of environment setup