Deployment & Ephemeral Preview Environments

Aruuri leverages a sophisticated deployment strategy centered around fully ephemeral preview environments. This system is designed to provide complete isolation for each development branch, ensuring high-fidelity testing while maintaining operational efficiency and cost control.

Core Principles of Ephemeral Previews

The ephemeral preview system is built on four key principles:

1. Full-Stack Isolation: Every pull request (PR) receives its own dedicated, isolated environment. This includes a separate database branch, distinct AWS infrastructure (Lambda functions, S3 buckets, CloudFront distributions), and a custom domain. This prevents conflicts and ensures that changes are tested against a clean slate.
2. Zero Ongoing Costs: Resources deployed for preview environments are automatically scaled to zero or removed when they are no longer needed. This applies to both database branches and AWS infrastructure, eliminating dormant costs associated with unused environments.
3. Automatic Cleanup: When a pull request is closed or merged, its associated preview environment and all its resources are automatically destroyed. This ensures a clean AWS account and prevents resource sprawl.
4. Custom Domains: Each preview environment is assigned a unique, readable URL, following a consistent format. For example, a PR with number 42 would be accessible at https://preview-pr-42.aruuri.so.

Technical Foundation: SST v3, AWS, & Cloudflare

The ephemeral preview architecture is orchestrated using SST v3 (Serverless Stack Toolkit), which simplifies the deployment and management of serverless applications on AWS. Cloudflare is used for DNS management to handle custom domains for each stage.

Here's how these technologies work together:

• SST v3: Acts as the infrastructure-as-code layer, defining all AWS resources needed for an Aruuri deployment. Its removal: 'remove' configuration for non-production stages is critical for automatic cleanup.
• AWS: Provides the underlying cloud resources, including:
  • Next.js App (Lambda/S3): The Next.js application (see apps/web) is deployed as a serverless application using AWS Lambda and S3 for static assets, managed by SST's sst.aws.Nextjs construct.
  • S3 Buckets: Isolated S3 buckets are created for each stage (aruuri-{stage}-mediabucket-*) to store media uploads and static content, configured for CloudFront access.
  • CloudFront: Content Delivery Networks (CDNs) are provisioned to serve media files globally with low latency and optimal caching.
  • Neon PostgreSQL: Provides serverless PostgreSQL databases. While SST manages the application infrastructure, Neon handles database branching, allowing each preview environment to have its own isolated database.
• Cloudflare: Manages DNS records (aruuri.so) to route traffic to the correct CloudFront distributions and Next.js applications, enabling custom preview-pr-*.aruuri.so domains.

Architecture Deep Dive: Configuration Files

The following configuration files illustrate how the ephemeral preview system is set up:

• sst.config.ts: This is the central SST configuration file.

  • It defines the application name (aruuri) and the AWS region (eu-west-2).
  • Crucially, protect: isProtectedStage and removal: isProtectedStage ? 'retain' : 'remove' are used to ensure that only production and dev stages retain resources, while all other stages (including previews) have their resources automatically removed on deletion.
  • It dynamically imports and calls functions from packages/infrastructure/ to create the Next.js app, media CDN, storage, and domain configuration based on the deployment stage.
  • It explicitly returns the created resources (mediaDistribution, mediaOAC, uploadBucket) to SST, allowing the toolkit to track and manage their lifecycle for proper cleanup ordering.

• packages/infrastructure/domains.ts: The getDomainConfig function dynamically determines the domain for each stage:

  • production uses aruuri.so with www.aruuri.so redirect.
  • dev uses dev.aruuri.so.
  • Preview environments use the format preview-{stage}.aruuri.so, ensuring a unique and predictable URL for each pull request. This configuration uses sst.cloudflare.dns to manage the DNS records within Cloudflare.

• packages/infrastructure/storage.ts: The createMediaStorage function creates an S3 bucket for media files:

  • new sst.aws.Bucket(${RESOURCE_IDS.MEDIA_BUCKET}-${stage}, { access: 'cloudfront' }) ensures that each stage (production, dev, pr-123) receives its own isolated S3 bucket.
  • The access: 'cloudfront' property automatically configures the necessary bucket policy, granting CloudFront the s3:GetObject permission via an Origin Access Control (OAC).

• packages/infrastructure/cdn.ts: The createMediaCDN function sets up the CloudFront Content Delivery Network:

  • It provisions an aws.cloudfront.OriginAccessControl (OAC) and links it to the S3 bucket created in storage.ts. This secure setup prevents direct public access to the S3 bucket.
  • An aws.cloudfront.Distribution is created with comment: Media CDN for ${stage} stage for easy identification.
  • The defaultCacheBehavior uses CACHE_POLICY.CACHING_OPTIMIZED for efficient static media delivery and viewerProtocolPolicy: 'redirect-to-https' for security.
  • It's crucial that both the mediaDistribution and mediaOAC are explicitly returned by sst.config.ts to SST. This ensures that SST correctly tracks their dependencies and deletes the CloudFront distribution before the OAC during cleanup, preventing OriginAccessControlInUse errors.

• packages/infrastructure/app.ts: The createNextjsApp function deploys the main Next.js web application (apps/web):

  • It creates an sst.aws.Nextjs resource, passing the dynamically generated domain configuration.
  • Environment variables, including database URLs (ARUURI_*_DATABASE_URL*), CLOUDFRONT_MEDIA_URL, PAYLOAD_SECRET, and S3 configuration, are injected, ensuring that each instance runs with the correct stage-specific settings.
  • The uploadBucket is linked to the Next.js application, allowing it to interact with the stage-specific S3 storage.

Preview URL Format

All preview environments follow a consistent URL pattern:

https://preview-pr-{number}.aruuri.so

Where {number} corresponds to the GitHub Pull Request number.

Deployment & Cleanup Scripts

Aruuri provides a suite of pnpm scripts to manage deployments and ephemeral environments:

Deployment

• pnpm run deploy: Deploys the application to the production stage.
• pnpm run deploy:dev: Deploys to the dev stage.
• pnpm run deploy:preview <stage-name>: Deploys to a specific preview stage. This is typically run in CI/CD pipelines when a PR is opened, using sst deploy --stage pr-{number}.

Cleanup

• pnpm run remove:dev: Removes the dev stage deployment.
• pnpm run remove:previews [stage1] [stage2] ... or pnpm run remove:previews --all-previews: This powerful script (scripts/remove-previews.ts) is designed to remove specific preview environments or all active pr-* stages.
  • It intelligently discovers active preview stages by querying AWS Lambda functions.
  • It first attempts to sst unlock and then sst remove the stage.
  • Crucially, it includes logic to detect and handle CloudFront OAC blocking removal errors. If such an error occurs, it executes the scripts/cleanup-cloudfront-distributions.ts script to disable and delete the stubborn CloudFront distributions before retrying the sst remove command.
• pnpm run cleanup:cloudfront <stage>: A dedicated utility script (scripts/cleanup-cloudfront-distributions.ts) to manually force the removal of CloudFront distributions for a given stage, especially useful in cases where SST's automatic cleanup might get stuck due to CloudFront's slow propagation times.

Temporary Site Protection

During early development, all Aruuri environments (local, preview, production) are protected with a password-based login form. This is a temporary measure for security and will be removed before public launch.

• The password is set via the SITE_PASSWORD environment variable.
• For local development, this can be set in a .env.local file or managed with Doppler.
• For deployments, SITE_PASSWORD must be configured in GitHub Secrets for CI/CD.
• The apps/web/src/middleware.ts file intercepts requests to enforce this password protection, redirecting unauthenticated users to a /login page. It also supports Basic Auth headers for automated testing (e.g., Playwright).

This comprehensive ephemeral preview system allows Aruuri to maintain a rapid development pace, ensure high code quality through isolated testing, and manage cloud infrastructure costs effectively.