@amirulabu/create-recurring-rabbit-app 0.0.0-alpha

package/templates/default/docs/deployment.md

@@ -0,0 +1,435 @@
+# Deployment Guide
+
+## Platform Options
+
+### Vercel (Recommended)
+
+**Zero-config deployment from GitHub**
+
+```bash
+vercel deploy
+```
+
+**Features:**
+
+- Automatic HTTPS and CDN
+- Environment variable management
+- PostgreSQL add-on available
+- Automatic builds on git push
+- Preview deployments for pull requests
+
+**Steps:**
+
+1. Push code to GitHub
+2. Import project in Vercel
+3. Configure environment variables (see below)
+4. Add Vercel Postgres or Railway database
+5. Deploy
+
+**Vercel Postgres Setup:**
+
+- Go to project settings → Storage → Postgres
+- Create database
+- Copy connection string to `DATABASE_URL`
+
+### Railway
+
+**Simple git-based deployment**
+
+```bash
+railway up
+```
+
+**Features:**
+
+- Built-in PostgreSQL hosting
+- Automatic domain assignment
+- Environment variable management
+- Auto-scaling
+
+**Steps:**
+
+1. Push code to GitHub
+2. New Project in Railway
+3. Connect GitHub repository
+4. Configure environment variables
+5. Railway Postgres is auto-created
+6. Deploy
+
+### Self-Hosted Docker
+
+**Full control over infrastructure**
+
+```dockerfile
+FROM node:18-alpine
+WORKDIR /app
+COPY package*.json ./
+RUN npm ci --only=production
+COPY . .
+RUN npm run build
+EXPOSE 3000
+CMD ["npm", "start"]
+```
+
+```bash
+docker build -t my-app .
+docker run -p 3000:3000 -e DATABASE_URL="postgres://..." my-app
+```
+
+**Features:**
+
+- Complete infrastructure control
+- Cost-effective for higher traffic
+- Custom domain and SSL
+
+## Production Checklist
+
+### Database Setup
+
+- [ ] PostgreSQL instance created (Vercel Postgres, Railway, Supabase, etc.)
+- [ ] Database URL added to environment variables
+- [ ] Migrations run against production database
+- [ ] Connection pooling configured (automatic in app)
+
+### Environment Variables
+
+#### Required Variables
+
+| Variable             | Description                  | How to Generate                                   |
+| -------------------- | ---------------------------- | ------------------------------------------------- |
+| `BETTER_AUTH_SECRET` | Secret for session signing   | Generate 32+ random chars: `openssl rand -hex 32` |
+| `DATABASE_URL`       | PostgreSQL connection string | Get from database provider                        |
+| `RESEND_API_KEY`     | Email service API key        | Get from [Resend](https://resend.com)             |
+
+#### Optional Variables
+
+| Variable          | Description            | Default                 |
+| ----------------- | ---------------------- | ----------------------- |
+| `BETTER_AUTH_URL` | Your production domain | `PUBLIC_APP_URL`        |
+| `PUBLIC_APP_URL`  | Your production domain | `http://localhost:3000` |
+| `NODE_ENV`        | Environment            | `production`            |
+
+**Vercel Environment Variables:**
+
+- Go to project settings → Environment Variables
+- Add all required variables
+- Select appropriate scope (production, preview, development)
+
+**Railway Environment Variables:**
+
+- Go to project → Variables
+- Add all required variables
+- Railway provides DATABASE_URL automatically
+
+### Domain & SSL
+
+- [ ] Custom domain configured
+- [ ] SSL certificate active (automatic on Vercel/Railway)
+- [ ] Redirects from www/non-www setup
+
+**Vercel Domain Setup:**
+
+- Go to project settings → Domains
+- Add custom domain
+- Update DNS records as instructed
+
+### Email Configuration
+
+- [ ] Resend account verified with production domain
+- [ ] Email templates customized with your branding
+- [ ] SPF/DKIM records configured for deliverability
+
+**SPF Record:**
+
+```
+@  IN  TXT  "v=spf1 include:resend.com ~all"
+```
+
+**DKIM Record:**
+Get from Resend → Domains → Your domain → DKIM
+Add as TXT record in your DNS provider.
+
+### Performance & Monitoring
+
+- [ ] Error tracking configured (Sentry, Vercel Analytics)
+- [ ] Performance monitoring enabled
+- [ ] Database connection limits appropriate for plan
+- [ ] CDN configured (automatic on Vercel)
+
+## Scaling Considerations
+
+### Database Optimization
+
+#### Monitor Slow Queries
+
+Check database provider's dashboard for slow query logs.
+Add indexes for frequently queried columns:
+
+```typescript
+export const users = sqliteTable(
+  'users',
+  {
+    id: text('id').primaryKey(),
+    email: text('email').notNull(),
+    // Add index
+  },
+  (table) => ({
+    emailIdx: index('email_idx').on(table.email),
+  })
+)
+```
+
+#### Connection Pooling
+
+Production app uses connection pooling:
+
+- Development: 5 connections
+- Production: 20 connections
+
+Adjust in `src/server/db/index.ts` if needed:
+
+```typescript
+const pool = new Pool({
+  connectionString: env.DATABASE_URL,
+  max: 20, // Adjust based on plan
+})
+```
+
+### CDN & Caching
+
+#### Static Assets
+
+Automatic on Vercel/Railway:
+
+- CSS/JS files cached
+- Images optimized
+- Gzip compression enabled
+
+#### API Response Caching
+
+Cache tRPC queries with TanStack Query:
+
+```typescript
+const { data } = api.myQuery.useQuery({
+  staleTime: 1000 * 60 * 5, // 5 minutes
+})
+```
+
+### Security Hardening
+
+- [ ] Rate limiting on authentication endpoints (already configured)
+- [ ] Regular dependency updates
+- [ ] Security headers configured
+
+**Content Security Policy** (Vercel):
+
+```javascript
+// vercel.json
+{
+  "headers": [
+    {
+      "source": "/(.*)",
+      "headers": [
+        {
+          "key": "X-Content-Type-Options",
+          "value": "nosniff"
+        },
+        {
+          "key": "X-Frame-Options",
+          "value": "DENY"
+        }
+      ]
+    }
+  ]
+}
+```
+
+## Migration to Production
+
+### Step-by-Step Process
+
+1. **Prepare Production Database**
+   - Create PostgreSQL instance
+   - Copy connection string
+   - Test connection locally if possible
+
+2. **Configure Environment Variables**
+   - Set `BETTER_AUTH_SECRET` (new random string)
+   - Set `DATABASE_URL` (PostgreSQL connection)
+   - Set `RESEND_API_KEY` (production key)
+   - Set `PUBLIC_APP_URL` (your domain)
+
+3. **Run Migrations**
+
+   ```bash
+   DATABASE_URL="postgres://..." npm run db:migrate
+   ```
+
+4. **Build Production Bundle**
+
+   ```bash
+   npm run build
+   ```
+
+5. **Deploy**
+   - Vercel: `vercel deploy --prod`
+   - Railway: `git push railway master`
+
+6. **Verify Deployment**
+   - Check build logs
+   - Test authentication flow
+   - Verify database connectivity
+   - Test email delivery
+
+### Common Deployment Issues
+
+#### Database Connection Failed
+
+**Issue:** `Error: connect ENOENT /data/app.db`
+
+**Cause:** Production trying to use SQLite instead of PostgreSQL
+
+**Solution:** Ensure `DATABASE_URL` environment variable is set in production
+
+#### Environment Variables Not Found
+
+**Issue:** `BETTER_AUTH_SECRET is required`
+
+**Cause:** Missing environment variable in deployment platform
+
+**Solution:**
+
+- Vercel: Check Environment Variables section
+- Railway: Check Variables section
+- Docker: Use `-e DATABASE_URL="..."` flag
+
+#### Build Fails
+
+**Issue:** Build fails during deployment
+
+**Common Causes:**
+
+- Missing dependency in package.json
+- TypeScript errors not caught locally
+- Environment validation errors
+
+**Solution:**
+
+1. Run `npm run typecheck` locally
+2. Run `npm run build` locally
+3. Check build logs in platform dashboard
+
+#### Email Not Sending in Production
+
+**Issue:** Emails work in dev but not in production
+
+**Cause:** RESEND_API_KEY not set or wrong
+
+**Solution:**
+
+1. Verify API key is set in production environment variables
+2. Check API key is not from test environment
+3. Verify domain is verified in Resend dashboard
+
+## Monitoring & Observability
+
+### Vercel Analytics
+
+Automatically enabled on Vercel deployments:
+
+- Page views
+- Web Vitals (LCP, FID, CLS)
+- Geolocation data
+
+### Database Monitoring
+
+Check provider dashboard for:
+
+- Connection counts
+- Query performance
+- Storage usage
+- CPU usage
+
+### Application Monitoring
+
+Consider adding:
+
+- **Sentry** for error tracking
+- **LogRocket** for session replay
+- **Datadog** for infrastructure monitoring
+
+## Continuous Deployment
+
+### GitHub Integration
+
+**Vercel:**
+
+1. Go to project settings → Git
+2. Connect GitHub repository
+3. Configure branch (master → production)
+4. Every push triggers deployment
+
+**Railway:**
+
+1. Go to project → GitHub
+2. Connect repository
+3. Configure branch
+4. Every push triggers deployment
+
+### Preview Deployments
+
+Test changes before production:
+
+```bash
+# Create pull request
+# Vercel creates preview deployment
+# Test on preview URL
+# Merge when ready
+```
+
+## Backup & Recovery
+
+### Database Backups
+
+**Vercel Postgres:**
+
+- Automatic backups included
+- Restorable from dashboard
+
+**Railway:**
+
+- Automatic snapshots included
+- Point-in-time recovery
+
+**Supabase:**
+
+- Daily backups included
+- 30-day retention
+
+### Rollback Procedure
+
+If deployment breaks production:
+
+```bash
+# Vercel
+vercel rollback --scope=your-project
+
+# Railway
+# Revert git commit and push
+git revert HEAD
+git push
+```
+
+## Post-Launch Checklist
+
+- [ ] All environment variables set
+- [ ] Database migrations applied
+- [ ] Email sending verified
+- [ ] Domain SSL active
+- [ ] Analytics working
+- [ ] Error tracking enabled
+- [ ] Performance budgets met
+- [ ] Backup plan configured
+- [ ] Monitoring set up
+- [ ] Team has access to deployment platform
+- [ ] On-call rotation established (if team)