Preview Environment Overview

Preview Environment Overview #

Preview Environments provide isolated, production-like environments for testing Pull Requests before they are merged into the main branch.

What is a Preview Environment? #

A Preview Environment is a fully functional instance of the BonsAI application that is automatically created from a GitHub Pull Request. It runs on Coder, our cloud development environment platform, and includes:

  • Complete Application Stack: All services (API, webapp, workers, etc.)
  • Database: PostgreSQL with migrations applied
  • Message Queue: RabbitMQ for async processing
  • Storage: LocalStack (S3 emulation)
  • Cache: Redis for session and data caching
  • External Access: Public URLs for testing

Why Use Preview Environments? #

Independent Testing #

Each Preview Environment is completely isolated from other environments. This means:

  • ✅ Test changes without affecting other developers
  • ✅ No conflicts with ongoing development
  • ✅ Safe experimentation with data and integrations
  • ✅ Multiple team members can test different features simultaneously

Easy Collaboration #

Preview Environments make it simple to share your work:

  • 🔗 Shareable URLs: Share preview links with stakeholders
  • 👥 Early Feedback: Get input from PMs and QA before merging
  • 🎯 Focused Testing: Test specific features in isolation
  • 📱 Demo Ready: Show new features to customers or stakeholders

Realistic Testing #

Preview Environments closely mirror production:

  • 🏗️ Same Architecture: Identical service configuration
  • 🔌 Real Integrations: Connect to actual Xero, QBO, SharePoint, etc.
  • 📊 Realistic Data: Use test data that mimics production
  • 🔒 Security: Same authentication and authorization mechanisms

Automatic Lifecycle #

Preview Environments are managed automatically:

  • 🚀 Auto-Create: Created when you add the preview label
  • 🔄 Auto-Update: Rebuilt when you push new commits
  • 🗑️ Auto-Delete: Removed when PR is closed or merged
  • ⏰ Auto-Stop: Automatically stops after 30 hours of inactivity

How It Works # 

┌─────────────────────────────────────────────────────────────┐
│  1. Developer creates Pull Request                          │
│     └── Add 'preview' label                                 │
└─────────────────────────────────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────────┐
│  2. GitHub Actions triggers Preview Environment creation    │
│     └── Calls Coder API                                     │
└─────────────────────────────────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────────┐
│  3. Coder provisions EC2 instance (t3.2xlarge)             │
│     ├── Installs Docker (rootless mode)                    │
│     ├── Clones PR branch                                   │
│     ├── Builds all services                                │
│     └── Starts application stack                           │
└─────────────────────────────────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────────┐
│  4. Environment becomes accessible (~40 minutes)            │
│     └── URL posted to PR comments                          │
└─────────────────────────────────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────────┐
│  5. Team tests the changes                                  │
│     ├── Developers verify functionality                    │
│     ├── QA performs testing                                │
│     └── PMs review features                                │
└─────────────────────────────────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────────┐
│  6. Developer pushes updates                                │
│     └── Environment automatically rebuilds (~10 minutes)   │
└─────────────────────────────────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────────┐
│  7. PR is closed/merged                                     │
│     └── Environment automatically deleted                   │
└─────────────────────────────────────────────────────────────┘

Architecture #

Each Preview Environment consists of:

Infrastructure Layer #

  • AWS EC2: t3.2xlarge instance (8 vCPU, 32 GB RAM)
  • Storage: 500 GB SSD (gp3)
  • Region: ap-northeast-1 (Tokyo)
  • Runtime: Docker in rootless mode for enhanced security

Application Services #

  • BonsAPI: Backend API server (Rust)
  • Webapp: Next.js frontend application
  • Workers: Background job processors
    • Accounting Sync
    • Document Conversion
    • Invoice Processing
    • Knowledge Management
    • Notification Service
    • SharePoint Delta Sync
    • Trigger Sync
    • Integration Heartbeat

Infrastructure Services #

  • PostgreSQL: Main database
  • RabbitMQ: Message queue
  • Redis: Cache and session storage
  • LocalStack: AWS S3 emulation
  • ClamAV: Virus scanning
  • Nginx: Reverse proxy

Developer Tools #

  • Swagger Editor: API specification editor
  • Swagger UI: API documentation viewer
  • CloudBeaver: Database management interface
  • Portainer: Docker container management

Resource Specifications #

Resource Specification
CPU 8 vCPUs
Memory 32 GB RAM
Storage 500 GB SSD
Network Enhanced networking enabled
Initial Setup Time ~40 minutes (first time)
Rebuild Time ~10 minutes (after updates)
Auto-stop After 30 hours of inactivity

Security Features #

Preview Environments are designed with security in mind:

  • 🔐 Rootless Docker: All containers run without root privileges
  • 🔒 Authentication: Clerk authentication required for access
  • 🛡️ Network Isolation: Each environment is network-isolated
  • 🔑 Secrets Management: Secrets provided via Doppler
  • 📝 Audit Logs: All access is logged in Coder

Limitations #

Be aware of these limitations:

  • ⏱️ Setup Time: Initial creation takes ~40 minutes
  • 🔄 Rebuild Time: Updates take ~10 minutes to deploy
  • 💰 Cost: Each environment costs ~$0.15/hour when running
  • 🌐 External Dependencies: Some integrations require manual OAuth setup
  • 📦 Data Persistence: Data is lost when environment is deleted

Next Steps #