# OSHUN Web — Deployment & Rollback Procedures

## Environments

| Environment | URL                        | Branch | Deploy Trigger           |
| ----------- | -------------------------- | ------ | ------------------------ |
| Staging     | staging.oshun.app          | main   | Automatic on push        |
| Production  | oshun.app                  | main   | Manual workflow dispatch |
| Canary      | canary.oshun.app           | main   | Manual (canary strategy) |
| PR Preview  | oshun-web-pr-\*.vercel.app | PR     | Automatic on PR open     |

## Deployment Strategies

### Standard Deployment

Full-traffic deployment. The new build replaces the current production/staging
deployment entirely.

**Trigger:**

```
GitHub → Actions → OSHUN Web Deploy → Run workflow
  → Environment: production
  → Strategy: standard
```

**Flow:**

1. Quality gate (lint, typecheck, test)
2. Build with Vercel CLI
3. Deploy with `--prod` flag
4. Health check (5 retries, 10s intervals)
5. Lighthouse budget check (production only)
6. Source map upload (automatic via workflow_run trigger)

### Canary Deployment

Deploy to a separate URL without affecting production traffic. Use this to
validate changes before promoting to full production.

**Trigger:**

```
GitHub → Actions → OSHUN Web Deploy → Run workflow
  → Environment: production
  → Strategy: canary
```

**Flow:**

1. Quality gate
2. Build
3. Deploy **without** `--prod` (gets unique Vercel URL)
4. Alias to `canary.oshun.app`
5. Health check on canary URL
6. Manual validation before promoting

**Promoting canary to production:**

After validating the canary, trigger a standard deployment or use the Vercel
CLI:

```bash
vercel alias set <canary-deployment-url> oshun.app \
  --token=$VERCEL_TOKEN \
  --scope=$VERCEL_ORG_ID
```

## Rollback Procedure

### Option 1: GitHub Actions Rollback (Recommended)

Use the deploy workflow with the rollback URL from a previous deployment.

**Steps:**

1. Find the previous deployment URL:
   - Go to [Vercel Dashboard](https://vercel.com) → OSHUN Web project
   - Or check the GitHub Actions run for the last successful deployment
   - Copy the deployment URL (e.g., `https://oshun-web-abc123.vercel.app`)

2. Trigger rollback:

   ```
   GitHub → Actions → OSHUN Web Deploy → Run workflow
     → Environment: production (or staging)
     → Strategy: standard
     → Rollback URL: https://oshun-web-abc123.vercel.app
   ```

3. The workflow will alias the previous deployment to the production domain

### Option 2: Vercel CLI Rollback

```bash
# List recent deployments
vercel ls oshun-web --token=$VERCEL_TOKEN

# Promote a specific deployment to production
vercel alias set <deployment-url> oshun.app \
  --token=$VERCEL_TOKEN \
  --scope=$VERCEL_ORG_ID

# For staging
vercel alias set <deployment-url> staging.oshun.app \
  --token=$VERCEL_TOKEN \
  --scope=$VERCEL_ORG_ID
```

### Option 3: Git Revert

If the issue is in the code and not the deployment infrastructure:

```bash
# Revert the problematic commit
git revert <commit-sha>
git push origin main

# This triggers an automatic staging deployment
# Then manually promote to production via the workflow
```

## Post-Rollback Checklist

After any rollback:

- [ ] Verify the rollback URL is serving correctly
- [ ] Check health endpoint returns 200
- [ ] Verify error monitoring is not showing new errors
- [ ] Notify the team in the appropriate channel
- [ ] Create a post-mortem issue if the deployment caused user-facing issues
- [ ] Investigate root cause before re-deploying

## Health Checks

The deployment workflow runs health checks automatically:

- **Endpoint:** Root URL (`/`)
- **Expected:** HTTP 200
- **Retries:** 5 attempts with 10-second intervals
- **Stabilization:** 15-second wait after deployment before first check

To manually check:

```bash
curl -s -o /dev/null -w "%{http_code}" https://oshun.app
curl -s -o /dev/null -w "%{http_code}" https://staging.oshun.app
```

## Monitoring After Deployment

1. **Error monitoring:** Check the BFF error reporting dashboard for spikes
2. **Lighthouse:** Review the automated Lighthouse CI results (production only)
3. **Bundle size:** Check the bundle monitor PR comment for regressions
4. **Core Web Vitals:** Monitor via the Web Vitals reporting endpoint

## CI/CD Workflow Summary

| Workflow                          | Trigger              | Purpose                        |
| --------------------------------- | -------------------- | ------------------------------ |
| `oshun-web-deploy.yml`            | Push main / manual   | Build and deploy               |
| `oshun-web-preview.yml`           | PR open/update       | PR preview deployment          |
| `oshun-web-e2e.yml`               | PR / push / daily    | Playwright E2E tests           |
| `oshun-web-lighthouse.yml`        | PR                   | Lighthouse performance budgets |
| `oshun-web-bundle-monitor.yml`    | PR / push            | Bundle size tracking           |
| `oshun-web-visual-regression.yml` | PR                   | Visual snapshot comparison     |
| `oshun-web-sourcemaps.yml`        | After deploy success | Source map upload for errors   |

## Required Secrets

| Secret                          | Purpose                          |
| ------------------------------- | -------------------------------- |
| `VERCEL_TOKEN`                  | Vercel CLI authentication        |
| `VERCEL_ORG_ID`                 | Vercel organization scope        |
| `OSHUN_WEB_VERCEL_PROJECT_ID`   | Vercel project identifier        |
| `OSHUN_PRODUCTION_BFF_URL`      | Production BFF base URL          |
| `OSHUN_STAGING_BFF_URL`         | Staging BFF base URL             |
| `OSHUN_WEB_SENTRY_DSN`          | Error monitoring DSN             |
| `OSHUN_WEB_ANALYTICS_WRITE_KEY` | Analytics write key              |
| `OSHUN_WEB_FEATURE_FLAGS`       | Feature flag JSON                |
| `OSHUN_SOURCEMAP_TOKEN`         | Auth token for source map upload |
