Skip to content

Latest commit

 

History

History
471 lines (365 loc) · 9.02 KB

DEPLOYMENT_GUIDE.md

File metadata and controls

471 lines (365 loc) · 9.02 KB

TrustVault PWA - Deployment Guide

Version: 1.0.0 Last Updated: November 24, 2025 Status: Production-Ready

Deployment Checklist

Pre-Deployment Verification

  • npm run type-check passes (TypeScript strict mode)
  • npm run build succeeds (4.3s, 625KB gzip)
  • npm run test passes (unit + integration + security)
  • npm audit shows 0 critical vulnerabilities
  • Security audit checklist completed
  • All features manually tested
  • Lighthouse scores >90 (pending: run after deploy)

Deployment Environment

# Node version
node >= 20.0.0

# NPM version
npm >= 10.0.0

# Dependencies resolved
✅ vitest@2.1.9
✅ @vitest/coverage-v8@2.1.9 (aligned)
✅ All other dependencies compatible

Deployment Options

Option 1: Vercel (Recommended)

Easiest deployment, zero configuration

# 1. Connect GitHub repo to Vercel
# 2. Vercel auto-detects Vite + React
# 3. Default build command: npm run build
# 4. Default output: dist/
# 5. Deploy (automatic or manual)

# Manual deployment
npm install -g vercel
vercel

Vercel Configuration:

  • Build Command: npm run build
  • Output Directory: dist
  • Environment: Node 20 (default)
  • Framework: Vite

Expected Result:

Option 2: GitHub Pages

Free hosting via GitHub Pages

# 1. Add to package.json:
# "homepage": "https://username.github.io/TrustVault-PWA"

# 2. Add deploy script:
# "deploy": "npm run build && gh-pages -d dist"

# 3. Deploy
npm run deploy

Option 3: Self-Hosted (AWS, GCP, Azure)

Maximum control, requires infrastructure

# Build locally
npm run build

# Upload dist/ folder to:
# - AWS S3 + CloudFront
# - Google Cloud Storage + CDN
# - Azure Static Web Apps
# - Digital Ocean App Platform

# Ensure:
# - HTTPS enabled
# - Gzip compression enabled
# - Security headers configured
# - Service worker caching

Post-Deployment Steps

1. Verify Deployment

# Check deployed site
https://trust-vault-pwa.vercel.app

# Verify in browser:
- [ ] Signup page loads
- [ ] Theme loads (no FOUC)
- [ ] Console clean (no errors)
- [ ] Service worker registers
- [ ] PWA installable (DevTools > Application)

2. Security Headers

Verify headers are present:

curl -i https://trust-vault-pwa.vercel.app | grep -E "^[A-Z]"

Expected headers:
- X-Content-Type-Options: nosniff
- X-Frame-Options: DENY
- X-XSS-Protection: 1; mode=block
- Referrer-Policy: strict-origin-when-cross-origin
- Content-Security-Policy: default-src 'self'...

3. PWA Validation

DevTools > Application > Manifest

{
  "name": "TrustVault",
  "short_name": "TrustVault",
  "start_url": "/",
  "display": "standalone",
  "background_color": "#121212",
  "theme_color": "#1976d2",
  "icons": [...],
  "screenshots": [...],
  "shortcuts": [...]
}

Service Worker:

  • Registered: ✅
  • Active & running: ✅
  • Precache: 52 assets
  • Update check: Auto-enabled

4. Performance Check

# Run Lighthouse
npm run lighthouse

# Minimum scores:
- Performance: >90
- Accessibility: >90
- Best Practices: >90
- SEO: >90
- PWA: 100

5. Functionality Test

Authentication:

  • Create account
  • Signin with email & password
  • Signout clears session
  • Refresh page → back to signin

Credentials:

  • Add credential
  • Search credentials
  • Edit credential
  • Delete credential
  • Verify encrypted in IndexedDB

Security:

  • Password generator works
  • TOTP codes display
  • Auto-lock triggers
  • Clipboard clears

Offline:

  • Go offline (DevTools > Network > Offline)
  • Can view credentials
  • Service worker serves cached assets
  • Go online → app works normally

Rollback Procedure

If Deployment Fails

Vercel:

# Automatic rollback to previous deployment
# Vercel Dashboard > Deployments > [Previous] > Rollback

# Or use CLI
vercel rollback

Manual Rollback:

# 1. Revert to previous commit
git revert <commit-hash>
git push origin main

# 2. Redeploy
# Vercel auto-deploys on push to main

Environment Variables

Required for production: None (PWA with local storage)

Optional for monitoring:

# Sentry error tracking (future)
VITE_SENTRY_DSN=https://...@sentry.io/...

# Analytics (future)
VITE_GA_ID=G-...

# Note: These should be set in deployment platform, not in code

DNS Configuration

For Custom Domain

Vercel + Custom Domain:

# 1. Vercel Dashboard > Settings > Domains
# 2. Add domain: trust-vault-pwa.com
# 3. Vercel provides DNS records
# 4. Update domain registrar DNS:

# Type: CNAME
# Name: www
# Value: cname.vercel-dns.com
# Or use ALIAS for apex domain

HTTPS / SSL

Automatic:

  • Vercel: Automatic with Let's Encrypt
  • GitHub Pages: Automatic
  • Custom domain: Vercel handles HSTS

Monitoring & Maintenance

Daily

  • Check error logs
  • Verify service worker updates
  • Monitor uptime

Weekly

  • Review performance metrics
  • Check dependency updates
  • Security alert scan

Monthly

  • Update dependencies (npm update)
  • Run security audit (npm audit)
  • Review user feedback

Quarterly

  • Penetration testing
  • Security review
  • Performance optimization

Troubleshooting

Issue: "npm install" fails on Vercel

Solution: Ensure @vitest/coverage-v8 matches vitest version

{
  "@vitest/coverage-v8": "^2.1.9",
  "vitest": "^2.1.9"
}

Commit fix and redeploy.

Issue: Service Worker not updating

Solution:

# Force update
Hard refresh: Cmd+Shift+R (Mac) / Ctrl+Shift+R (Windows)

# Or unregister old SW
DevTools > Application > Service Workers > Unregister > Reload

Issue: CORS errors in production

Solution: Verify headers configured in vite.config.ts

headers: {
  'Access-Control-Allow-Origin': 'self'
  // CSP already restricts resources
}

Issue: Large bundle size

Current: 625KB gzip (acceptable for feature-rich PWA) Optimization: Dynamic imports for heavy libraries

CI/CD Integration

GitHub Actions (Optional)

# .github/workflows/deploy.yml
name: Deploy

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Install dependencies
        run: npm install
      
      - name: Type check
        run: npm run type-check
      
      - name: Build
        run: npm run build
      
      - name: Test
        run: npm run test:run
      
      - name: Deploy to Vercel
        env:
          VERCEL_TOKEN: ${{ secrets.VERCEL_TOKEN }}
        run: |
          npm install -g vercel
          vercel --prod --token $VERCEL_TOKEN

Deployment Verification Checklist

After deployment to production, verify:

FUNCTIONALITY
- [ ] Signup page loads
- [ ] Signin works
- [ ] Add credential works
- [ ] Dashboard displays credentials
- [ ] Search/filter works
- [ ] Edit credential works
- [ ] Delete credential works
- [ ] Settings page accessible
- [ ] Export/import works
- [ ] Signout clears session

SECURITY
- [ ] No console errors
- [ ] No security warnings
- [ ] Security headers present
- [ ] HTTPS enforced
- [ ] CSP working (no inline scripts)
- [ ] XSS prevention active
- [ ] No plaintext passwords exposed

PERFORMANCE
- [ ] Page loads <2s
- [ ] Credentials decrypt <1s
- [ ] Search responsive (<100ms)
- [ ] No jank or stutter
- [ ] Lighthouse >90 all categories

PWA
- [ ] Service worker active
- [ ] Offline mode works
- [ ] Install prompt appears
- [ ] App installable
- [ ] Manifest valid
- [ ] Icons display correctly

BROWSER COMPATIBILITY
- [ ] Chrome (latest)
- [ ] Safari (latest)
- [ ] Firefox (latest)
- [ ] Edge (latest)
- [ ] Mobile (iOS/Android)

Version Control

Release Tags

# Tag release
git tag -a v1.0.0 -m "Initial production release"
git push origin v1.0.0

# Create release notes
# GitHub > Releases > Create from tag > Add notes

Commit Message Convention

Phase X: Feature name - Brief description

Detailed explanation
- Bullet point 1
- Bullet point 2

Fixes #123

Support & Communication

Documentation

  • README.md - User guide
  • SECURITY.md - Security details
  • ROADMAP.md - Future plans
  • CLAUDE.md - Development standards

Incident Response

  • Error: Check error logs (Sentry/similar)
  • Security: Follow SECURITY.md protocol
  • Availability: Check status page
  • Performance: Check Lighthouse scores

Success Criteria

✅ Deployment Successful When:

  1. Build completes in <10 seconds
  2. All tests pass (unit + integration + security)
  3. Lighthouse scores >90 all categories
  4. Zero security warnings
  5. Service worker active & caching
  6. All features functional
  7. Performance metrics green
  8. No console errors

Deployment Ready: ✅ APPROVED

TrustVault PWA is production-ready and can be deployed to any of the recommended platforms immediately.

Next: Monitor deployment and plan quarterly security audits.