ReviewOS

also looking at this

loghqorg/loghq

Deploy: uniform auth session model (main → production)

#7
Merged glennmichael123 wants to merge main into production
282 files +3028 -64856
docs/bootcamp/how-to/deploy.mddeleted+0-605
Changes to docs/bootcamp/how-to/deploy.md
@@ -1,605 +0,0 @@
1# Deployment How-To
2
3This guide covers deploying your Stacks application to production. Learn how to configure cloud settings, use the deployment command, manage environment variables, and set up custom domains.
4
5## Overview
6
7Stacks provides a streamlined deployment experience:
8
9- **Single Command** - Deploy with `buddy deploy`
10- **Multiple Providers** - AWS, Vercel, Netlify, and more
11- **Zero-Downtime** - Automatic rolling deployments
12- **CDN Integration** - Global edge distribution
13- **SSL Certificates** - Automatic HTTPS
14
15## Cloud Configuration
16
17Configure your deployment settings in `config/cloud.ts`:
18
19```typescript
20// config/cloud.ts
21import type { CloudConfig } from '@stacksjs/cloud'
22
23const config: CloudConfig = {
24 // Deployment driver
25 driver: 'aws', // 'aws' | 'vercel' | 'netlify'
26
27 // Application name (used for resource naming)
28 appName: 'my-stacks-app',
29
30 // Deployment environment
31 environment: 'production', // 'production' | 'staging' | 'development'
32
33 // AWS Configuration
34 aws: {
35 region: 'us-east-1',
36 accountId: process.env.AWS_ACCOUNT_ID,
37 credentials: {
38 accessKeyId: process.env.AWS_ACCESS_KEY_ID,
39 secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
40 },
41 },
42
43 // Domain configuration
44 domain: {
45 name: 'myapp.com',
46 subdomain: 'www',
47 certificate: {
48 provider: 'acm', // AWS Certificate Manager
49 autoRenew: true,
50 },
51 },
52
53 // CDN settings
54 cdn: {
55 enabled: true,
56 provider: 'cloudfront',
57 priceClass: 'PriceClass_100', // US, Canada, Europe
58 cachePolicy: {
59 defaultTTL: 86400, // 24 hours
60 maxTTL: 31536000, // 1 year
61 minTTL: 0,
62 },
63 },
64
65 // Compute settings
66 compute: {
67 memory: 1024, // MB
68 timeout: 30, // seconds
69 minInstances: 1,
70 maxInstances: 10,
71 autoScale: {
72 enabled: true,
73 targetCpuUtilization: 70,
74 },
75 },
76
77 // Database settings
78 database: {
79 provider: 'planetscale', // 'planetscale' | 'rds' | 'aurora'
80 region: 'us-east-1',
81 },
82
83 // Storage settings
84 storage: {
85 provider: 's3',
86 bucket: 'my-stacks-app-assets',
87 publicAccess: true,
88 },
89}
90
91export default config
92```
93
94## Using buddy deploy
95
96The `buddy deploy` command handles your entire deployment process.
97
98### Basic Deployment
99
100```bash
101# Deploy to production
102buddy deploy
103
104# Deploy to staging
105buddy deploy --env=staging
106
107# Deploy with verbose output
108buddy deploy --verbose
109```
110
111### Deployment Options
112
113```bash
114# Skip build step (deploy existing build)
115buddy deploy --skip-build
116
117# Deploy specific version/tag
118buddy deploy --tag=v1.2.3
119
120# Dry run (show what would be deployed)
121buddy deploy --dry-run
122
123# Force deployment (bypass checks)
124buddy deploy --force
125
126# Deploy with custom config
127buddy deploy --config=./custom-cloud.ts
128```
129
130### First-Time Setup
131
132For first-time deployments, run the setup command:
133
134```bash
135# Initialize cloud infrastructure
136buddy cloud:init
137
138# This will
139# - Create necessary cloud resources
140# - Set up IAM roles and permissions
141# - Configure DNS records
142# - Provision SSL certificates
143```
144
145## Environment Variables
146
147### Managing Environment Variables
148
149Environment variables keep sensitive data out of your codebase.
150
151#### Local Development
152
153Create a `.env` file in your project root:
154
155```bash
156# .env (local development)
157APP_NAME=MyStacksApp
158APP_ENV=local
159APP_DEBUG=true
160APP_URL=http://localhost:3000
161
162# Database
163DB_CONNECTION=sqlite
164DB_DATABASE=./storage/database.sqlite
165
166# Authentication
167AUTH_SECRET=your-local-secret-key
168
169# API Keys (local/test keys)
170STRIPE_KEY=sk_test_xxx
171STRIPE_SECRET=sk_test_xxx
172```
173
174#### Production Environment
175
176Set production variables using the CLI:
177
178```bash
179# Set individual variable
180buddy env:set API_KEY=your-production-api-key --env=production
181
182# Set multiple variables
183buddy env:set DB_HOST=prod-db.example.com DB_USER=admin --env=production
184
185# Import from file
186buddy env:import .env.production --env=production
187
188# List all variables
189buddy env:list --env=production
190
191# Remove a variable
192buddy env:remove API_KEY --env=production
193```
194
195#### Environment Files by Stage
196
197```bash
198.env # Local development (not committed)
199.env.example # Template (committed)
200.env.staging # Staging overrides
201.env.production # Production overrides
202```
203
204### Accessing Environment Variables
205
206```typescript
207// In your application
208import { env } from '@stacksjs/env'
209
210// Get value with default
211const apiKey = env('API_KEY', 'default-value')
212
213// Required value (throws if missing)
214const secretKey = env.required('SECRET_KEY')
215
216// Typed values
217const debugMode = env.boolean('APP_DEBUG', false)
218const port = env.number('PORT', 3000)
219const allowedHosts = env.array('ALLOWED_HOSTS', ['localhost'])
220```
221
222### Secrets Management
223
224For sensitive data, use the secrets manager:
225
226```bash
227# Store a secret
228buddy secret:set DATABASE_PASSWORD "super-secret" --env=production
229
230# Secrets are encrypted at rest and only decrypted at runtime
231buddy secret:list --env=production
232
233# Rotate a secret
234buddy secret:rotate DATABASE_PASSWORD --env=production
235```
236
237## Domain Setup
238
239### Configuring Custom Domains
240
241#### Step 1: Add Domain to Configuration
242
243```typescript
244// config/cloud.ts
245export default {
246 domain: {
247 name: 'myapp.com',
248 subdomain: 'www', // Results in www.myapp.com
249 aliases: [
250 'myapp.com', // Redirect root to www
251 'app.myapp.com',
252 ],
253 },
254}
255```
256
257#### Step 2: Configure DNS
258
259Add the following DNS records with your domain registrar:
260
261```bash
262# View required DNS records
263buddy domain:dns
264
265# Output
266# Type Name Value TTL
267# A @ 76.76.21.21 300
268# CNAME www cname.myapp.stacks.cloud 300
269```
270
271#### Step 3: Verify Domain
272
273```bash
274# Verify DNS propagation
275buddy domain:verify
276
277# Check domain status
278buddy domain:status
279```
280
281### SSL Certificates
282
283SSL certificates are automatically provisioned and renewed:
284
285```typescript
286// config/cloud.ts
287export default {
288 domain: {
289 name: 'myapp.com',
290 certificate: {
291 provider: 'acm', // AWS Certificate Manager
292 autoRenew: true,
293 // Or use custom certificate
294 // customCert: {
295 // cert: './certs/myapp.crt',
296 // key: './certs/myapp.key',
297 // },
298 },
299 },
300}
301```
302
303### Multiple Domains
304
305Support multiple domains for your application:
306
307```typescript
308// config/cloud.ts
309export default {
310 domains: [
311 {
312 name: 'myapp.com',
313 primary: true,
314 },
315 {
316 name: 'myapp.io',
317 redirect: 'myapp.com', // Redirect to primary
318 },
319 {
320 name: 'api.myapp.com',
321 type: 'api', // API-specific routing
322 },
323 ],
324}
325```
326
327## Deployment Strategies
328
329### Zero-Downtime Deployments
330
331Stacks uses rolling deployments by default:
332
333```typescript
334// config/cloud.ts
335export default {
336 deployment: {
337 strategy: 'rolling', // 'rolling' | 'blue-green' | 'canary'
338 healthCheck: {
339 path: '/health',
340 interval: 30,
341 timeout: 5,
342 healthyThreshold: 2,
343 unhealthyThreshold: 3,
344 },
345 },
346}
347```
348
349### Blue-Green Deployments
350
351For instant rollback capability:
352
353```typescript
354deployment: {
355 strategy: 'blue-green',
356 switchover: 'automatic', // or 'manual'
357 rollbackOnFailure: true,
358}
359```
360
361### Canary Deployments
362
363Gradually roll out to a percentage of users:
364
365```typescript
366deployment: {
367 strategy: 'canary',
368 stages: [
369 { percentage: 10, duration: '5m' },
370 { percentage: 50, duration: '10m' },
371 { percentage: 100 },
372 ],
373 rollbackOnError: true,
374}
375```
376
377## Monitoring Deployments
378
379### Deployment Status
380
381```bash
382# Check deployment status
383buddy deploy:status
384
385# View deployment logs
386buddy deploy:logs
387
388# View deployment history
389buddy deploy:history
390```
391
392### Rollback
393
394```bash
395# Rollback to previous version
396buddy deploy:rollback
397
398# Rollback to specific version
399buddy deploy:rollback --version=v1.2.2
400
401# View available rollback versions
402buddy deploy:versions
403```
404
405## CI/CD Integration
406
407### GitHub Actions
408
409```yaml
410# .github/workflows/deploy.yml
411name: Deploy
412
413on:
414 push:
415 branches: [main]
416
417jobs:
418 deploy:
419 runs-on: ubuntu-latest
420 steps:
421
422 - uses: actions/checkout@v4
423
424 - name: Setup Bun
425
426 uses: oven-sh/setup-bun@v1
427 with:
428 bun-version: latest
429
430 - name: Install dependencies
431
432 run: bun install
433
434 - name: Run tests
435
436 run: bun test
437
438 - name: Build
439
440 run: bun run build
441
442 - name: Deploy
443
444 run: bun run deploy
445 env:
446 AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
447 AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
448 AWS_ACCOUNT_ID: ${{ secrets.AWS_ACCOUNT_ID }}
449```
450
451### GitLab CI
452
453```yaml
454# .gitlab-ci.yml
455stages:
456
457 - test
458 - build
459 - deploy
460
461test:
462 stage: test
463 script:
464
465 - bun install
466 - bun test
467
468build:
469 stage: build
470 script:
471
472 - bun run build
473
474 artifacts:
475 paths:
476
477 - dist/
478
479deploy:
480 stage: deploy
481 script:
482
483 - bun run deploy
484
485 only:
486
487 - main
488
489 environment:
490 name: production
491 url: https://myapp.com
492```
493
494## Production Checklist
495
496Before deploying to production, ensure:
497
498### Security
499
500- [ ] Environment variables are set (not hardcoded)
501- [ ] Debug mode is disabled (`APP_DEBUG=false`)
502- [ ] HTTPS is enforced
503- [ ] CORS is properly configured
504- [ ] Rate limiting is enabled
505- [ ] Authentication secrets are rotated
506
507### Performance
508
509- [ ] Assets are minified and compressed
510- [ ] CDN is configured
511- [ ] Database indexes are optimized
512- [ ] Caching is enabled
513- [ ] Images are optimized
514
515### Reliability
516
517- [ ] Health check endpoint exists
518- [ ] Error monitoring is configured
519- [ ] Backup strategy is in place
520- [ ] Rollback procedure is tested
521
522### Configuration
523
524```typescript
525// config/app.ts (production settings)
526export default {
527 env: 'production',
528 debug: false,
529 url: 'https://myapp.com',
530
531 // Security headers
532 security: {
533 https: true,
534 hsts: {
535 enabled: true,
536 maxAge: 31536000,
537 includeSubdomains: true,
538 },
539 contentSecurityPolicy: true,
540 },
541
542 // Caching
543 cache: {
544 enabled: true,
545 driver: 'redis',
546 ttl: 3600,
547 },
548
549 // Logging
550 logging: {
551 level: 'error',
552 channel: 'cloudwatch',
553 },
554}
555```
556
557## Troubleshooting
558
559### Common Issues
560
561**Deployment fails with permission error:**
562
563```bash
564# Check AWS credentials
565buddy cloud:check-credentials
566
567# Verify IAM permissions
568buddy cloud:check-permissions
569```
570
571**Domain not resolving:**
572
573```bash
574# Check DNS propagation
575buddy domain:verify --verbose
576
577# Clear CDN cache
578buddy cdn:purge
579```
580
581**Application errors after deployment:**
582
583```bash
584# View application logs
585buddy logs --env=production
586
587# Check health status
588buddy health:check --env=production
589
590# Quick rollback
591buddy deploy:rollback
592```
593
594## Next Steps
595
596Now that you know how to deploy, continue to:
597
598- [Testing How-To](/bootcamp/how-to/testing) - Test before deploying
599- [Authentication How-To](/bootcamp/how-to/authentication) - Secure your deployed app
600
601## Related Documentation
602
603- [AWS Deployment Guide](https://docs.aws.amazon.com/)
604- [Cloudflare DNS Setup](https://developers.cloudflare.com/dns/)
605- [SSL/TLS Best Practices](https://ssl-config.mozilla.org/)