Module 7 · DevOps · Deep Dive

Deploy & CI

Turn your repo into a public URL you can paste into a job application — frontend on Vercel, backend in a container, Postgres managed in the cloud, all guarded by CI.

BasicIntermediateBuild

1 · The deployment shape

The goal is concrete: a URL like https://docchat.vercel.app that works for anyone, anywhere. To get there you deploy three separate pieces, each to the host that fits it best:

They find each other over HTTPS: the browser loads the frontend from Vercel, the frontend calls the backend's public URL, and the backend talks to Postgres over a connection string. Three URLs, wired by environment variables — never hardcoded.

2 · Managed Postgres & the connection string

Do not run your own database server. A managed Postgres provider hosts it, patches it, and backs it up. Two excellent free tiers in 2026:

• Neon — serverless Postgres, scales to zero, generous free tier. Great default for DocChat.
• Supabase — Postgres plus extras (auth, storage) if you want them.

You sign up, create a project, and copy a connection string. It looks like this:

# Neon connection string — keep it secret, it's a password
postgresql://user:pass@ep-cool-name.eu-central-1.aws.neon.tech/docchat?sslmode=require

That single string is the value of your DATABASE_URL environment variable — the same one SQLAlchemy reads in Module 3. You set it as a secret in each host's dashboard, not in your code:

# locally, in .env (which is gitignored — never committed)
DATABASE_URL="postgresql://user:pass@ep-cool-name.../docchat?sslmode=require"

3 · Deploy the frontend to Vercel

Vercel is the company that makes Next.js, so this is the smoothest path on the planet. The flow:

1. Push your repo to GitHub.
2. On vercel.com, Import Project and pick the repo. Vercel auto-detects Next.js — no config needed.
3. Set environment variables in the dashboard (Settings → Environment Variables). For DocChat the frontend needs the backend's URL:

# Vercel dashboard env var — public because the browser uses it
NEXT_PUBLIC_API_URL=https://docchat-api.onrender.com

After that first import, deployment is automatic: every git push to main auto-deploys to production, and every pull request gets its own preview URL. You never run a deploy command by hand.

4 · Deploy the backend container

FastAPI needs a running Python process, so it goes to a container host. You reuse the Dockerfile you wrote in Lesson 7.1 — that's the whole point of having containerised early. Good hosts:

• Render — connect the repo, it builds your Dockerfile, gives you an HTTPS URL. Easiest.
• Railway — similar, fast, nice dashboard.
• Fly.io — deploys containers close to UAE users (edge regions).

The flow mirrors Vercel: connect GitHub, the host detects the Dockerfile, builds it, and runs your start command. Set the backend's secrets in its dashboard:

# Backend host env vars (Render / Railway / Fly.io dashboard)
DATABASE_URL=postgresql://user:pass@ep-cool-name.../docchat?sslmode=require
OPENAI_API_KEY=sk-...                 # for the RAG embeddings/LLM
JWT_SECRET=a-long-random-string       # for auth tokens
FRONTEND_ORIGIN=https://docchat.vercel.app

The container's start command is the production server — not the dev reloader:

# in the Dockerfile (CMD) — bind to the port the host gives you
uvicorn app.main:app --host 0.0.0.0 --port $PORT

from fastapi.middleware.cors import CORSMiddleware

app.add_middleware(
    CORSMiddleware,
    allow_origins=["https://docchat.vercel.app"],  # the EXACT prod origin
    allow_credentials=True,
    allow_methods=["*"],
    allow_headers=["*"],
)

An alternative for small APIs is Vercel Python functions (serverless), which keeps everything on one platform — fine for light endpoints, but a container host is the better fit for DocChat's RAG workload.

5 · CI with GitHub Actions

CI (Continuous Integration) means: on every push, a robot installs your project, runs your tests, and lints/builds it — so a broken change is caught before it reaches users. On GitHub you do this with GitHub Actions: a YAML file at .github/workflows/ci.yml.

The structure is always the same: a trigger (on:), one or more jobs, each a list of steps. Here's a correct, minimal pipeline for the FastAPI backend:

.github/workflows/ci.yml

name: CI

on:
  push:
    branches: [main]
  pull_request:

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-python@v5
        with:
          python-version: "3.12"

      - name: Install dependencies
        run: pip install -r requirements.txt

      - name: Lint
        run: ruff check .

      - name: Run tests
        run: pytest -q

Push that file and GitHub runs it automatically. The result shows as a green check (or red X) on every commit and pull request. You can require the check to pass before merging — that's how teams keep main always-deployable.

6 · Production basics

You don't need heavy DevOps for a capstone, but know these four so you can talk about them:

• HTTPS — every host above gives you TLS automatically. Never serve a login form over plain HTTP.
• Logs & monitoring — each dashboard streams your app's logs. When something 500s in production, the log is your first stop. Render/Railway/Vercel keep recent logs for free.
• Custom domain — point docchat.com at Vercel by adding the domain in the dashboard and updating two DNS records. Optional, but a real domain reads as professional to a recruiter.
• Secrets in dashboards, not code — API keys and the DB password live in each host's environment-variable settings. If a secret ever lands in git, rotate it immediately.

7 · Migrations in the deploy pipeline

In Module 3 you ran alembic upgrade head by hand. In a real deploy that step must be automatic — otherwise someone forgets, and the new code hits a table that doesn't exist yet. Wire it into the deploy itself, either as a release / pre-deploy step the platform runs before swapping traffic, or as the first thing your container entrypoint does:

entrypoint.sh — runs on every container start, before the server

#!/bin/sh
  set -e
  # apply any pending migrations against the live DATABASE_URL
  alembic upgrade head
  # then start the production server
  exec uvicorn app.main:app --host 0.0.0.0 --port $PORT

On Render you'd set this as a Pre-Deploy Command; on Railway/Fly the entrypoint pattern above is common. Either way, schema and code ship together.

But automation is only safe if the migrations themselves are safe. During a rolling deploy, the platform keeps the old container serving traffic while the new one boots — so for a few seconds old code and new code run against the same database at once. A migration that the old code can't tolerate will throw 500s for every user still on the old version.

The golden rule is the expand → migrate → contract pattern — make every change backward-compatible:

• Expand — add the new thing (new nullable column, new table) in a release where nothing depends on it yet. Old code ignores it; new code can start using it.
• Migrate — backfill data and deploy the code that reads/writes the new shape.
• Contract — only once no running code touches the old column do you drop it, in a later release.

8 · Health checks & readiness

The platform needs a way to ask your app "are you alive?" and "are you ready for traffic?". You answer with two tiny endpoints — the distinction matters:

• Liveness (/health) — "is the process running?" If this fails, the platform restarts the container. It must not touch the DB — you don't want a brief DB blip to trigger a restart loop.
• Readiness (/ready) — "can I actually serve a request?" — i.e. can I reach Postgres? If this fails, the platform stops routing traffic to this instance but leaves it running, so it can recover.

from fastapi import FastAPI
  from sqlalchemy import text

app = FastAPI()

@app.get("/health")        # liveness — cheap, no I/O
def health():
    return {"status": "ok"}

@app.get("/ready")         # readiness — proves the DB is reachable
def ready(db = Depends(get_db)):
    db.execute(text("SELECT 1"))
    return {"status": "ready"}

This is the backbone of zero-downtime deploys: when a new container boots, the platform waits for /ready to go green before sending it any traffic and before retiring the old one. No request ever lands on a half-started instance.

9 · Rollback strategy

Things break in production. The grown-up answer isn't "hotfix in a panic" — it's roll back to the last good deploy in one click, then debug calmly. Every host gives you this:

• Vercel — open a previous deployment and "Promote to Production". Instant, because the old build still exists.
• Render — the Rollback button restores the previous deploy.
• Containers anywhere — re-deploy the previous image tag. This is why the tag matters.

Tag every image with the immutable git SHA, never :latest:

# build & push tagged with the commit SHA — every build is a distinct, recoverable artifact
docker build -t docchat-api:$GIT_SHA .
docker push registry.example.com/docchat-api:$GIT_SHA

# rollback = redeploy the previous known-good SHA
deploy docchat-api:a1b2c3d

:latest is a moving target — you can't tell which code it points at, and you can't reliably go back to "the one before". A git SHA is permanent and exact: a1b2c3d always means that build, forever.

10 · Observability

"It works on my machine" is meaningless once the code runs on a host you can't see. Observability is how you understand a system from the outside — three pillars:

• Logs — discrete events: "user 7 uploaded a doc", "DB query failed". What happened.
• Metrics — numbers over time: requests/sec, p95 latency, error rate. How much / how fast.
• Traces — one request's journey across services with timings. Where the time went.

The single highest-leverage upgrade for a capstone is structured JSON logging. A plain string log is hard to search; a JSON log is queryable — you can filter by user, status, or a correlation ID that ties every line from one request together:

# instead of: print("upload failed for user 7")
import logging, json

logger.info(json.dumps({
    "event": "upload_failed",
    "request_id": request_id,   # correlation ID — one value per request
    "user_id": 7,
    "status": 500,
}))

For exceptions, plug in Sentry — it captures every unhandled error with the full stack trace and context (which user, which request, which release), and groups duplicates so you fix the cause, not chase repeats:

import sentry_sdk

sentry_sdk.init(
    dsn=os.environ["SENTRY_DSN"],
    traces_sample_rate=0.1,        # sample 10% of traces for performance
)
# unhandled exceptions are now auto-captured with full context

Round it out with uptime monitoring — a service that pings /health every minute and alerts you (or just checks the page is up) the moment it goes down. Now production isn't a black box.

11 · A fuller GitHub Actions pipeline

The Section 5 pipeline lints and tests. A production-grade one does four stages in order — lint → test → build → deploy — and adds two real-world touches: dependency caching (so installs are fast) and a Postgres service container (so tests run against a real database, not a mock):

.github/workflows/ci.yml

name: CI

on:
  push:
    branches: [main]
  pull_request:

jobs:
  test:
    runs-on: ubuntu-latest
    services:
      postgres:                       # a throwaway Postgres just for this job
        image: postgres:16
        env:
          POSTGRES_PASSWORD: postgres
          POSTGRES_DB: docchat_test
        ports: ["5432:5432"]
        options: >-
          --health-cmd pg_isready
          --health-interval 10s
          --health-retries 5
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-python@v5
        with:
          python-version: "3.12"
          cache: pip                     # cache deps — skips re-download on repeat runs

      - name: Install dependencies
        run: pip install -r requirements.txt

      - name: Lint
        run: ruff check .

      - name: Run tests
        env:
          DATABASE_URL: postgresql://postgres:postgres@localhost:5432/docchat_test
        run: pytest -q

  deploy:
    needs: test                        # only runs if the test job passed
    if: github.ref == 'refs/heads/main'  # deploy only on merge to main, not PRs
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Build image
        run: docker build -t docchat-api:${{ github.sha }} .

      - name: Deploy
        run: curl -X POST "$RENDER_DEPLOY_HOOK"   # trigger the host to roll out
        env:
          RENDER_DEPLOY_HOOK: ${{ secrets.RENDER_DEPLOY_HOOK }}

Read the shape: the services: block boots a real postgres:16 alongside the job and waits for pg_isready before tests run; cache: pip reuses downloaded wheels across runs; the second job needs: test so a red test blocks deploy; and if: github.ref == 'refs/heads/main' means PRs get tested but only a merge to main ships. That's the full lint → test → build → deploy gate.

12 · Edge protection & secret rotation

Two quick hardening habits worth a sentence in an interview:

• Rate limiting / abuse protection at the edge — cap how many requests one IP can make so a bot can't hammer your login or run up your OpenAI bill. Do it as close to the user as possible: Vercel's firewall/WAF, Cloudflare in front, or a middleware like slowapi on FastAPI. A login endpoint capped at, say, 5 attempts/minute stops credential-stuffing cheaply.
• Secret rotation — secrets aren't set-and-forget. Rotate JWT_SECRET, API keys, and the DB password periodically, and immediately if one ever leaks. Because every secret lives in a dashboard env var (never in code), rotating is just: generate a new value, update it in the host, redeploy — no code change.

13 · Build it

Work the pieces in dependency order — database first, then backend, then frontend:

1. Neon: create a project, copy the DATABASE_URL, run alembic upgrade head against it.
2. Render: connect the repo, set DATABASE_URL, OPENAI_API_KEY, JWT_SECRET, FRONTEND_ORIGIN. Deploy. Note the API URL.
3. CORS: add your Vercel origin to allow_origins and push.
4. Vercel: import the repo, set NEXT_PUBLIC_API_URL to the Render URL. Deploy.
5. CI: commit .github/workflows/ci.yml and watch the green check appear.

When all three URLs talk to each other and the green check lands, DocChat is genuinely production-shaped — the exact thing an interviewer wants to click.

14 · Check yourself

Answer from memory — retrieval is what moves this from "I read it" to "I know it".