# Rollback Playbook (Netlify)

When a deploy causes issues, use this playbook to roll back safely. It covers the two-site setup (frontend + backend on Netlify) and database considerations.

---

## When to roll back

- **Frontend:** Broken UI, auth errors, wrong API URL, or critical client-side bugs after a deploy.
- **Backend:** Health check failing, 5xx errors, or broken API endpoints after a deploy.
- **Database:** Only roll back migrations if you have a verified backup and a tested rollback migration. Prefer fixing forward when possible.

---

## 1. Roll back on Netlify (site-level)

Each Netlify site keeps deploy history. Rollback reverts **that site** to a previous deploy; it does not change the repo or the other site.

### Frontend site

1. In [Netlify](https://app.netlify.com): open the **frontend** site.
2. Go to **Deploys**.
3. Find the last known-good deploy (e.g. the one before the bad deploy).
4. Click the **⋯** menu on that deploy → **Publish deploy** (or **Restore**).
5. Confirm. The site will serve that deploy immediately.

### Backend site

1. Open the **backend** site in Netlify.
2. Go to **Deploys**.
3. Find the last known-good deploy.
4. **⋯** → **Publish deploy** (or **Restore**).
5. Confirm.

**Note:** Rollback only changes the deployed code. Environment variables (e.g. `DATABASE_URL`, `NEXT_PUBLIC_API_URL`) are unchanged. If the incident was caused by an env change, fix the env in Site settings → Environment variables and trigger a new deploy instead of (or after) rollback.

---

## 2. Database considerations

- **No migrations in this deploy:** Rolling back frontend/backend is enough; no DB action.
- **Migrations were run in the bad deploy:**  
  - If the new code is rolled back but the DB was already migrated, the **old** code may be incompatible with the **new** schema. Options:
    - **Preferred:** Deploy a fix forward (new code that works with current schema) rather than rolling back code.
    - **If you must roll back code:** Ensure you have a **rollback migration** that reverts the schema changes, and run it against the same DB (e.g. `npx prisma migrate deploy` after reverting the migration files in the repo). Test this in staging first.
  - **Backup:** For destructive or risky migrations, take a DB snapshot/backup before deploying.

---

## 3. After rollback

1. **Verify:**  
   - Frontend: open the app, sign in, hit the dashboard.  
   - Backend: `BACKEND_URL=https://your-backend.netlify.app npm run pre-deploy-check`
2. **Communicate:** If users were affected, notify them (status page, email, or in-app).
3. **Post-mortem:** Identify root cause, fix in a branch, and deploy again when ready. Avoid rolling back and forgetting.

---

## 4. Optional: block bad deploys with smoke check

To catch issues before or right after deploy:

- Add **BACKEND_URL** (and optionally **REQUIRE_DB**) to repo **Secrets** in GitHub.
- Run the **Smoke check (backend)** workflow from the Actions tab (manual **Run workflow**) after each deploy, or enable the `push`/`schedule` triggers in `.github/workflows/smoke-check.yml`.

If the smoke check fails, investigate before considering the deploy "done"; roll back if the deploy is already live and broken.

---

## Quick reference

| Step | Action |
|------|--------|
| 1 | Netlify → correct site (frontend or backend) → Deploys |
| 2 | Pick last known-good deploy → ⋯ → Publish deploy |
| 3 | Fix env vars if they caused the issue; avoid rolling back DB unless you have a tested rollback migration |
| 4 | Run `npm run pre-deploy-check` with `BACKEND_URL` set to confirm backend |
| 5 | Post-mortem and fix forward |