IX Static Site CI/CD System

Deploy any static site with feature branch previews in minutes, not hours.

A comprehensive, production-ready CI/CD system for static sites that provides automated deployments, feature branch routing, SSL certificates, global CDN, and smart cleanup across AWS infrastructure.

🚀 Quick Start

Option 1: One-Command Setup (Fastest)

curl -fsSL https://raw.githubusercontent.com/IX-Erich/ix-cicd/main/cli/deploy-setup.sh | bash -s init \
  --project-name "my-awesome-app" \
  --domain-name "myapp.example.com"

Option 2: GitHub Actions (Team-Friendly)

- name: Deploy Static Site
  uses: IX-Erich/ix-cicd/reusable-actions/static-site-deploy@main
  with:
    aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
    aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
    s3-bucket: 'myproject.example.com'
    cloudfront-distribution-id: ${{ secrets.CLOUDFRONT_DISTRIBUTION_ID }}
    spa-mode: 'true'  # For React/Vue SPAs

Option 3: Terraform Module (Infrastructure-as-Code)

module "my_static_site" {
  source = "github.com/IX-Erich/ix-cicd//terraform/modules/static-site-hosting?ref=main"

  project_name = "my-awesome-app"
  domain_name  = "myapp.example.com"
  spa_mode     = true  # Enable for SPAs
}

✨ What You Get

• ✅ Feature Branch Deployments - Every branch gets its own URL (/feature-name/)
• ✅ Automated SSL/HTTPS - Free SSL certificates via AWS ACM
• ✅ Global CDN - Fast loading worldwide via CloudFront
• ✅ SEO Protection - Feature branches blocked from search engines
• ✅ Auto-cleanup - Deployments removed when branches are deleted
• ✅ Multi-framework Support - React, Vue, Jekyll, static HTML, Next.js
• ✅ Production Ready - Security headers, performance optimization, cost controls

🎯 Perfect For

Individual Developers

• Portfolio sites with live feature previews
• Side projects without server costs
• Client prototypes with shareable URLs

Teams

• Design reviews with live previews
• Stakeholder demos without technical setup
• QA testing in isolated environments

Companies

• Documentation sites with versioning
• Marketing pages with A/B testing
• Internal dashboards and tools

🏗️ System Architecture

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   GitHub Repo   │    │   GitHub Actions │    │   AWS Services  │
│                 │    │                  │    │                 │
│ Push to main ───┼───►│ Build & Deploy ──┼───►│ S3 Bucket       │
│                 │    │                  │    │ CloudFront CDN  │
│ Push to feature/│    │ Feature Branch ──┼───►│ ACM Certificate │
│ Push to hotfix/ │    │ Smart Router     │    │ Route53 DNS     │
└─────────────────┘    └──────────────────┘    └─────────────────┘

Results:

• main → https://yoursite.com/
• feature/new-ui → https://yoursite.com/feature-new-ui/
• hotfix/urgent → https://yoursite.com/hotfix-urgent/

🎨 Framework Support

Framework	Build Dir	SPA Mode	Example
React	build	✅ Yes	examples/react-app/
Vue.js	dist	✅ Yes	examples/vue-app/
Next.js	out	✅ Yes	examples/nextjs-export/
Jekyll	_site	❌ No	examples/jekyll-blog/
Static HTML	.	❌ No	examples/static-html/

📖 Documentation

📋 Complete System Documentation

The comprehensive guide covering all features, setup options, and advanced configurations.

🛠️ Framework Examples

Real-world examples with step-by-step setup instructions for popular frameworks.

🔧 Component Documentation

• CLI Tool - One-command project bootstrapping
• GitHub Actions - Reusable workflow components
• Terraform Module - Infrastructure as code

🚀 Features Deep Dive

Feature Branch Routing

Every pushed branch gets its own deployment URL:

• Smart CloudFront Function routing
• SEO protection with robots.txt on preview branches
• Automatic cleanup when branches are deleted
• Support for SPA routing on all deployments

SSL & Security

• Automated SSL certificates via AWS Certificate Manager
• Custom domains with DNS validation
• Security headers: HSTS, CSP, X-Frame-Options, etc.
• HTTPS redirects for all traffic

Performance Optimization

• Global CDN with edge locations worldwide
• Intelligent caching with framework-specific rules
• Compression for all text-based assets
• HTTP/2 and modern protocol support

Cost Management

• Optimized cache policies to minimize origin requests
• Regional pricing tiers to control CloudFront costs
• Lifecycle policies for S3 storage optimization
• Resource tagging for cost allocation

📊 System Comparison

Approach	Setup Time	Flexibility	Maintenance	Best For
CLI Tool	1 minute	Medium	Low	Quick starts
GitHub Actions	5 minutes	High	Medium	Team consistency
Terraform	15 minutes	Very High	High	Infrastructure control
Manual Setup	30+ minutes	Maximum	High	Custom requirements

🔧 Advanced Usage

Multi-Environment Deployments

jobs:
  deploy-staging:
    if: github.ref == 'refs/heads/develop'
    # Deploy to staging.myapp.com
    
  deploy-production:
    if: github.ref == 'refs/heads/main'  
    # Deploy to myapp.com

Custom Cache Behaviors

module "my_static_site" {
  # Basic config...
  
  custom_cache_behaviors = [
    {
      path_pattern = "/api/*"
      ttl_settings = { default_ttl = 0 }  # Don't cache APIs
    },
    {
      path_pattern = "*.js"
      ttl_settings = { default_ttl = 31536000 }  # Cache JS for 1 year
    }
  ]
}

Security Headers

security_headers = {
  "Strict-Transport-Security" = "max-age=63072000"
  "Content-Security-Policy"   = "default-src 'self'"
  "X-Frame-Options"           = "DENY"
}

🎯 Migration from Other Systems

From Netlify

1. Copy your build settings to GitHub Actions workflow
2. Update domain DNS to point to CloudFront
3. Migrate environment variables to GitHub Secrets

From Vercel

1. Export static build using next export or similar
2. Configure build directory in deployment action
3. Update DNS records

From AWS Amplify

1. Keep existing S3 bucket or create new one
2. Add CloudFront distribution for better caching
3. Migrate build settings to GitHub Actions

🤝 Contributing

We welcome contributions! Please see our Contributing Guidelines for details.

Development Setup

1. Fork this repository
2. Create a feature branch: git checkout -b feature/my-improvement
3. Test your changes on a real project
4. Submit a pull request with clear description

Reporting Issues

• Bug reports: Include steps to reproduce, expected vs actual behavior
• Feature requests: Describe the use case and proposed solution
• Questions: Check existing documentation and examples first

📈 Roadmap

Immediate (Next Release)

• Vue.js complete example
• Jekyll complete example
• GitHub CLI integration
• Cost estimation calculator

Future Features

• Multi-region deployments
• Blue/green deployment support
• Integration with monitoring tools
• Custom domain automation
• Backup and disaster recovery

🔒 Security

Reporting Security Issues

Please report security vulnerabilities to security@imaginariax.com. Do not use public issue trackers for security reports.

Security Features

• IAM least privilege - Minimal AWS permissions
• Encrypted in transit - HTTPS everywhere
• Security headers - Protection against common attacks
• Secret management - Secure handling of credentials

📄 License

MIT License - see LICENSE file for details.

🆘 Support

Getting Help

1. 📖 Read the documentation - Comprehensive guides
2. 📋 Check examples - Framework-specific implementations
3. 🔍 Search issues - Known problems and solutions
4. ➕ Create an issue - For bugs or feature requests

Community

• Discord: Join our community for real-time help
• Twitter: @ix_cicd for updates and tips
• Blog: Technical deep-dives and tutorials

---

🎉 Ready to Deploy?

Choose your preferred approach and get started in minutes!

• 🚀 One-Command CLI Setup - Fastest way to get started
• 🔧 GitHub Actions Integration - Team-friendly workflows
• 🏗️ Terraform Infrastructure - Full control
• 📚 Complete Documentation - Everything you need to know

Deploy with confidence. Deploy with IX CI/CD. ⚡