Home / MAD1 / Week 12

Week 12 · Deployment: Git, WSGI, servers and the cloud

The one-minute story

By the end of this week you can:

• use the Git workflow (init, add, commit, branch, merge, push, pull, clone) and predict what each command does;
• rebuild an environment from requirements.txt and keep secrets in environment variables;
• explain why flask run is not for production and how WSGI, gunicorn and nginx fit together;
• read a simple Dockerfile and a CI file, and tell PaaS, IaaS and SaaS apart;
• change a database model safely with Flask-Migrate, and prepare a deployment checklist and a README for your project.

Words you need

Idea 1: Git and GitHub

Git is a distributed version control system: every developer has a full copy of the whole history on their own machine, so Git works offline for everything except talking to a remote. GitHub (and GitLab, Bitbucket) is a website that hosts Git repositories and adds pull requests, issues and so on. Git and GitHub are not the same thing.

Three places a file can be:

1. Working directory: your files on disk.
2. Staging area (index): the list of changes chosen for the next commit (git add).
3. Repository: the saved commits (git commit).

A file can be in both the working directory and the staging area at the same time (that is just "staged"). git add moves a change into the staging area; it does not send anything to GitHub.

git config --global user.name  "Asha"                 # one-time identity
git config --global user.email "asha@example.com"     # exact command to change your e-mail
git init                    # turn this folder into a repo (starts on branch main or master)
git status                  # what changed, what is staged
git add app.py              # stage one file   (git add .  stages everything)
git commit -m "Add login"   # save the staged snapshot
git log --oneline           # history, one line per commit
git diff                    # unstaged changes (git diff --staged: staged ones)

Real run in a fresh folder with app.py, .gitignore and .env: git status -s first shows ?? .env, ?? .gitignore, ?? app.py (untracked). After git add app.py it shows A app.py (staged). After git commit -m first, git log --oneline shows one line: <id> first.

Branches and merging

A branch is only a pointer to a commit; creating one is nearly free. You work on a feature branch, then merge it into main.

git branch                  # list branches (* marks the current one)
git branch feature1         # CREATE a branch (does not switch)
git checkout feature1       # switch to it   (newer: git switch feature1)
git checkout -b feature2    # create AND switch in one step (newer: git switch -c feature2)
# ... edit, add, commit on the branch ...
git checkout main           # go back to main
git merge feature1          # merge feature1 INTO the branch you are standing on (main)
git branch -d feature1      # delete the merged branch

Real run: after git switch -c feature1, one commit there, and back on main, git branch printed feature1 and * main; git merge feature1 printed Fast-forward (main had no new commits of its own, so Git just moved the pointer). The log then had 2 commits.

git merge X merges X into the current branch, not into main and not into "master". So to merge feature1 and feature2 into main:

git checkout main
git merge feature1
git merge feature2

(Choosing the commands where you first git checkout feature1 and then merge feature2 is wrong: you would merge into feature1.)

Merge conflicts. If both branches changed the same lines, Git stops and marks the file:

<<<<<<< HEAD
B
=======
A
>>>>>>> a

(Real output from a test where main wrote B and branch a wrote A in x.txt: Git said CONFLICT (add/add) and Automatic merge failed.) You edit the file to keep what you want, remove the markers, then git add x.txt and git commit.

Push rejected. If a teammate pushed first and you did not pull, your git push is rejected (! [rejected] main -> main (fetch first); real run). You must git pull (merge their work), fix conflicts if any, then push. The rule is "pull before you push".

Other commands the papers ask about

The first branch of a new repo is called main (new default) or master (older Git); both answers are accepted in the papers.

.gitignore is a text file listing files Git must not track: secrets (.env), virtual environments (venv/), caches (__pycache__/), local databases (*.db), uploads.

venv/
__pycache__/
*.pyc
.env
*.db
instance/

A pull request (PR) is a GitHub request to merge your branch into another (usually main): teammates review the code, CI runs the tests, and then someone clicks Merge. Never commit passwords or API keys; if you did, change them, because Git history remembers.

Idea 2: Virtual environments, requirements and configuration

Different projects need different package versions. A virtual environment (venv) gives each project its own packages.

python -m venv venv                 # create (folder named venv)
source venv/bin/activate            # Linux/macOS      (Windows: venv\Scripts\activate)
pip install flask flask-sqlalchemy gunicorn
pip freeze > requirements.txt       # write exact installed versions to a file
pip install -r requirements.txt     # on another machine: rebuild the same set
deactivate

pip freeze lists the installed packages as name==version, which is what goes into requirements.txt (a question asks which command lists the packages installed from requirements.txt in the venv: pip freeze). Pin versions (Flask==3.0.3) so the server runs what you tested. Do not commit the venv/ folder; commit requirements.txt.

Configuration and secrets in environment variables. The same code runs on your laptop and on the server, but the settings differ (secret key, database URL, debug flag). Do not hard-code them; read them from the environment.

import os
from flask import Flask

app = Flask(__name__)
app.config["SECRET_KEY"] = os.environ.get("SECRET_KEY", "dev-only")
app.config["SQLALCHEMY_DATABASE_URI"] = os.environ.get("DATABASE_URL", "sqlite:///app.db")
app.config["DEBUG"] = os.environ.get("FLASK_DEBUG") == "1"
print(app.config["SECRET_KEY"], app.config["DEBUG"])

Real runs: python cfg.py prints dev-only False; SECRET_KEY=abc FLASK_DEBUG=1 python cfg.py prints abc True. On the server you set the real values in the environment (or a .env file that is in .gitignore, loaded with python-dotenv). One code base, different config per environment: development, testing, production.

Idea 3: Why not flask run in production? WSGI, gunicorn, nginx

flask run (or app.run()) starts Flask's built-in development server. It is great for coding, but it is not meant for real traffic: it is designed for one developer, handles few requests at a time, is not hardened for security, and with debug mode on can expose an interactive debugger that lets anyone run code. Never run debug=True in production.

WSGI (Web Server Gateway Interface) is the agreed interface: a web server calls a Python callable with the request information and gets back a response. A Flask app object is such a callable. Here is the whole idea in a few lines (real run: the client got b'Hello from /hi'):

def application(environ, start_response):
    body = ("Hello from " + environ["PATH_INFO"]).encode()
    start_response("200 OK", [("Content-Type", "text/plain"),
                              ("Content-Length", str(len(body)))])
    return [body]

Because Flask, Django and others all speak WSGI, any WSGI server can run any of them. gunicorn (Linux and macOS) and uWSGI are production WSGI servers: they start several worker processes, restart crashed workers and handle many connections.

pip install gunicorn
gunicorn -w 4 -b 127.0.0.1:8000 app:app     # 4 workers; module "app", variable "app"

app:app means "in the file app.py, use the object called app". If you use an application factory: gunicorn "app:create_app()".

Reverse proxy. In front of gunicorn we put a fast web server, nginx (or Apache), which: terminates HTTPS, serves static files directly (CSS, JS, images) without bothering Python, forwards other requests to gunicorn, and can balance load between several app servers.

server {
    listen 80;
    server_name example.com;

    location /static/ {
        alias /srv/myapp/static/;          # nginx serves these itself
    }
    location / {
        proxy_pass http://127.0.0.1:8000;  # everything else goes to gunicorn
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $remote_addr;
    }
}

The path of one request: browser, nginx (port 80/443), gunicorn (port 8000), Flask app, database, and back.

Nginx vs Apache (a real MSQ): both are open source. Apache is versatile and has many modules and dynamic per-directory configuration. Nginx is generally faster for static files and high traffic with low memory use (it is event-driven). So "Apache is better for a large volume of concurrent connections than Nginx" is the false statement.

HTTPS. HTTP sends text anyone on the network can read. HTTPS = HTTP over TLS: the traffic is encrypted and the server proves its identity with a certificate issued by a certificate authority. Let's Encrypt gives free certificates (the certbot tool installs and renews them). Browsers show a padlock; cookies marked Secure are sent only over HTTPS. Many features (service workers, geolocation) require HTTPS.

Idea 4: Docker, cloud and CI/CD

Why Docker? "It works on my machine" fails when the server has a different Python or missing libraries. A Docker image packages your app with its exact Python, libraries and settings. A container is a running instance of an image: isolated, lightweight (it shares the host's kernel, unlike a full virtual machine), and starts in seconds.

# Dockerfile
FROM python:3.12-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY . .
EXPOSE 8000
CMD ["gunicorn", "-w", "4", "-b", "0.0.0.0:8000", "app:app"]

Line by line: start from an official Python image; work in /app; copy requirements.txt first and install (Docker caches this layer so rebuilds are fast); copy the rest of the code; document port 8000; the default command is gunicorn bound to 0.0.0.0 (all interfaces, needed inside a container).

docker build -t myapp .                      # build an image named myapp
docker run -p 8000:8000 myapp                # run a container; host port 8000 to container port 8000
docker ps                                    # list running containers

docker-compose describes several containers that run together in one YAML file, for example the web app, a database and nginx:

services:
  web:
    build: .
    ports: ["8000:8000"]
    environment:
      DATABASE_URL: postgresql://user:pass@db/app
    depends_on: [db]
  db:
    image: postgres:16
    volumes: ["dbdata:/var/lib/postgresql/data"]
volumes:
  dbdata:

docker compose up starts everything; a volume keeps database files when the container is deleted (container storage is temporary).

Cloud service models

Cloud means renting computing by the hour instead of buying machines; benefits: scalability, pay-as-you-use, reliability. For a student project, PaaS is the easiest.

CI/CD. Continuous integration (CI): every push is automatically built and tested, and the result reported, so errors are found early. Continuous delivery: after the tests pass, a release package is produced automatically and is ready to deploy. Continuous deployment: every passing change is automatically deployed into production. A small GitHub Actions file:

# .github/workflows/test.yml
name: tests
on: [push, pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.12"
      - run: pip install -r requirements.txt
      - run: pytest

On every push GitHub starts a fresh machine, installs the requirements and runs your pytest tests from week 10; a red cross on the commit means a test failed.

Idea 5: Migrations, logging, backups

Database migrations. Earlier you used db.create_all(). It creates missing tables but never changes an existing one. If you add a column to a model, the old database file does not get it. Migrations are numbered scripts that evolve the schema step by step, keeping the data. The tool is Alembic; Flask-Migrate wraps it for Flask.

# app.py
from flask import Flask
from flask_sqlalchemy import SQLAlchemy
from flask_migrate import Migrate

app = Flask(__name__)
app.config["SQLALCHEMY_DATABASE_URI"] = "sqlite:///app.db"
db = SQLAlchemy(app)
migrate = Migrate(app, db)

class User(db.Model):
    id = db.Column(db.Integer, primary_key=True)
    name = db.Column(db.String(50), nullable=False)

flask db init                       # once: creates the migrations/ folder
flask db migrate -m "create user"   # compare models with the database, write a script
flask db upgrade                    # APPLY the script to the database
# later you add:   email = db.Column(db.String(120))   to User
flask db migrate -m "add email"     # new script: Detected added column 'user.email'
flask db upgrade                    # apply it
flask db downgrade                  # undo the latest one
flask db current                    # which revision is the database at

All of this was run for real. The second migration's script contains upgrade() with add_column('email', ...) and downgrade() with drop_column('email'). After the second upgrade flask db current printed 38103fadeb9c (head); after downgrade it showed the first revision again. Remember: migrate = generate script, upgrade = apply it (a very common confusion). Always read the generated script (autogenerate can miss renames, and SQLite cannot drop or alter columns directly, so Alembic uses its batch mode). Commit migrations/ to Git; on the server run flask db upgrade at each deployment.

Logging. In production nobody sits at the terminal, so write logs to a file or to the platform's log viewer. Use the logging module rather than print:

import logging
logging.basicConfig(level=logging.INFO, format="%(asctime)s %(levelname)s %(message)s")
log = logging.getLogger(__name__)

log.info("user %s logged in", "asha")
log.warning("disk almost full")
log.error("payment failed")

Levels in order: DEBUG, INFO, WARNING, ERROR, CRITICAL; setting INFO hides DEBUG. Never log passwords or tokens. Monitoring means watching health: is the site up (uptime check), how slow are the responses, how many errors; tools send an alert when something breaks (for example Sentry for errors, UptimeRobot for uptime). Gunicorn also writes an access log and an error log.

Backups. Servers die, disks fail, people run a wrong DELETE. Keep regular, automatic, off-site copies of the database and of uploaded files, and test a restore at least once, because a backup you cannot restore is not a backup. For SQLite you can copy the file when the app is idle, or use sqlite3 app.db ".backup backup.db".

Your turn

git checkout main
git merge feature1
git merge feature2

import os
print(os.environ.get("MODE", "dev"))

Exam radar

Quick quiz

Viva: say it out loud

Recap

Practise with real exam questions

These come straight from past papers (with the real figures and the official answer key). Open 33 real questions on this week   All End Term papers