Deployment

Deployment Scratchpad

Document deployment configurations, infrastructure discoveries, and operational insights.

Cloudflare Pages Configuration

Current Setup

Date: 2025-08-28

Production Configuration:

Site URL: https://bigissue.pages.dev
Build Command: npm run build
Output Directory: dist
Node Version: 18 (configured in GitHub Actions)

GitHub Secrets:

CLOUDFLARE_API_TOKEN: Custom token with Pages:Edit permissions
CLOUDFLARE_ACCOUNT_ID: f9c3aafb7c048170d5bdb5f0f6737e5b
CLOUDFLARE_PROJECT_NAME: bigissue

Deployment Triggers:

Production: Push to main branch
Preview: Pull request creation/updates
Manual: Via npx wrangler pages deploy ./dist

Successful Configuration Changes

Date: 2025-08-28

Asset Path Resolution:

// astro.config.mjs - Working configuration
export default defineConfig({
  site: 'https://bigissue.pages.dev', // No base path needed
  integrations: [starlight({ /* config */ })],
});

Previously Problematic:

// This caused CSS loading issues
export default defineConfig({
  site: 'https://poramateminsiri.github.io',
  base: '/bigissue', // Caused asset path problems
});

Learning: Cloudflare Pages works best with root-level paths, unlike GitHub Pages

GitHub Actions Integration

Workflow Configuration

Date: 2025-08-28

Deployment Workflow (.github/workflows/deploy-cloudflare.yml):

Trigger: Push to main, PR to main
Environment: ubuntu-latest, Node 18
Steps: Checkout → Setup Node → Install → Build → Deploy
Permissions: contents:read, deployments:write, pull-requests:write

Key Features:

- name: Deploy to Cloudflare Pages
  uses: cloudflare/pages-action@v1
  id: cloudflare-deploy
  with:
    apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
    accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
    projectName: ${{ secrets.CLOUDFLARE_PROJECT_NAME }}
    directory: dist
    gitHubToken: ${{ secrets.GITHUB_TOKEN }}

Automated PR Comments:

Preview URL automatically posted to PR
Deployment status updates
Easy access to test changes before merge

CI Pipeline Integration

Date: 2025-08-28

Build Validation (.github/workflows/ci.yml):

TypeScript checking with npx tsc --noEmit
Build validation and output verification
Preview server testing
Artifact upload on failure for debugging

Pipeline Flow:

Push → CI Build Check → Deployment → Preview Comment → Manual Review → Merge → Production

Failure Handling:

CI failures prevent deployment
Build artifacts uploaded for debugging
Clear error messages in GitHub interface

Deployment Performance

Speed Metrics

Date: 2025-08-28

Deployment Times:

Build phase: ~30-45 seconds (install + build + upload)
Propagation: Near-instant (edge cache distribution)
Total time: ~1-2 minutes from push to live URL

Preview Deployments:

Creation: ~30-45 seconds
Update: ~30-45 seconds for subsequent pushes
URL format: https://[commit-hash].bigissue.pages.dev

Performance Comparison:

Faster than GitHub Pages (no Jekyll processing)
Faster global distribution than traditional hosting
Built-in CDN and optimization

Reliability Observations

Date: 2025-08-28

Success Rate: 100% successful deployments in testing Error Recovery: Failed deployments don’t affect live site Rollback: Previous deployment remains active during build failures

Monitoring:

GitHub Actions provides detailed deployment logs
Cloudflare dashboard shows deployment history
Automatic health checks for deployment success

Infrastructure Insights

Cloudflare Pages Benefits

Date: 2025-08-28

Automatic Optimizations:

Asset compression (gzip/brotli)
Image optimization and format conversion
CSS/JS minification and bundling
HTTP/2 and HTTP/3 support

Global Distribution:

200+ edge locations worldwide
Automatic geographic routing
Built-in DDoS protection
SSL certificate management

Developer Experience:

Branch-based preview deployments
Integration with popular frameworks
Custom domain support
Analytics and performance monitoring

Wrangler CLI Alternative

Date: 2025-08-28

Direct Deployment Option:

npm install wrangler@latest --save-dev
npm run build
npx wrangler pages deploy ./dist --project-name bigissue

Use Cases:

Emergency deployments bypassing GitHub Actions
Local testing of deployment process
Deployment from different branches
Troubleshooting deployment issues

Configuration: Uses same Cloudflare credentials, simpler authentication

Operational Procedures

Deployment Troubleshooting

Date: 2025-08-28

Common Issues & Solutions:

Build Failures:

Check GitHub Actions logs for specific errors
Test build locally with npm run build
Verify all dependencies are in package.json
Check for environment-specific issues

CSS/Asset Loading Problems:

Verify site configuration in astro.config.mjs
Check asset paths in build output
Clear Cloudflare cache if needed
Test with preview deployment first

API Token Issues:

Regenerate token with correct permissions
Update GitHub secrets immediately
Verify account ID matches Cloudflare dashboard
Check token hasn’t expired

Emergency Procedures

Date: 2025-08-28

Broken Production Deployment:

Immediate: Previous deployment remains active
Investigation: Check GitHub Actions logs for failure details
Rollback: If needed, revert last commit and redeploy
Hotfix: Use Wrangler CLI for emergency fixes
Prevention: Always test with preview deployments

Service Outages:

Cloudflare Status: Check https://cloudflarestatus.com
GitHub Status: Check https://status.github.com
Alternative: Manual deployment via Cloudflare dashboard
Communication: Update team about service impacts

Security Considerations

Date: 2025-08-28

API Token Management:

Minimum required permissions (Cloudflare Pages:Edit)
Regular rotation schedule (quarterly)
Secure storage in GitHub secrets
No tokens in code or logs

Access Control:

Repository write access controls deployment
Branch protection prevents unauthorized changes
Required reviews for production changes
Audit logging via GitHub and Cloudflare

Deployment Best Practices

Pre-deployment Checklist

Local Testing: Build and preview work correctly
CI Validation: All automated checks pass
Preview Testing: Use PR preview deployment for validation
Performance Check: No significant performance regressions
Security Review: No sensitive information in deployment

Monitoring and Maintenance

Regular Health Checks: Monitor deployment success rates
Performance Tracking: Watch build times and site performance
Security Updates: Keep dependencies and tokens current
Documentation: Update deployment procedures as needed
Team Communication: Share operational knowledge and changes

Optimization Opportunities

Build Cache: Optimize CI cache strategy for faster builds
Parallel Processing: Explore build parallelization options
Asset Optimization: Fine-tune image and asset processing
CDN Configuration: Optimize cache headers and strategies
Monitoring: Implement advanced performance and error monitoring