Big-Link-Man/docs/stories/story-1.6-deployment-infrastructure.md

Story 1.6: Deployment Infrastructure Management

Story

As an Admin, I want a database model and CLI commands to manage bunny.net deployment infrastructure for static sites, so that the system can provision new sites, attach domains to existing storage, and track all necessary credentials and IDs for future operations.

Context

bunny.net requires a sequential provisioning workflow using two separate APIs (Account API for infrastructure, Storage API for files). Each site deployment requires tracking multiple related resources (Storage Zones and Pull Zones) with their corresponding IDs, credentials, and hostnames for future management operations like file uploads, cache purges, and deletion.

Acceptance Criteria

Database Model

• A SiteDeployment table exists with the following fields:
  • id (integer, primary key)
  • site_name (string, required) - User-friendly name for the site
  • custom_hostname (string, required, unique) - The FQDN (e.g., www.yourdomain.com)
  • storage_zone_id (integer, required) - bunny.net Storage Zone ID
  • storage_zone_name (string, required) - Storage Zone name
  • storage_zone_password (string, required) - Storage Zone API password
  • storage_zone_region (string, required) - Storage region code (e.g., "DE", "NY", "LA")
  • pull_zone_id (integer, required) - bunny.net Pull Zone ID
  • pull_zone_bcdn_hostname (string, required) - Default b-cdn.net hostname
  • created_at (timestamp)
  • updated_at (timestamp)

CLI Commands

Provision New Site

• Command: provision-site --name <site_name> --domain <custom_hostname> --storage-name <storage_zone_name> --region <region>
• Creates a new Storage Zone on bunny.net
• Creates a new Pull Zone linked to the Storage Zone
• Adds the custom hostname to the Pull Zone
• Stores all response data in the database
• Displays DNS configuration instructions for manual setup by the user
• Admin-only access

Attach Domain to Existing Storage

• Command: attach-domain --name <site_name> --domain <custom_hostname> --storage-name <existing_storage_zone_name>
• Retrieves existing Storage Zone ID by name
• Creates a new Pull Zone linked to the existing Storage Zone
• Adds the custom hostname to the Pull Zone
• Stores all response data in the database
• Displays DNS configuration instructions for manual setup by the user
• Admin-only access

List Sites

• Command: list-sites
• Displays all site deployments with key details (site name, custom hostname, storage zone name, pull zone b-cdn hostname)
• Admin-only access

Get Site Details

• Command: get-site --domain <custom_hostname>
• Displays complete deployment details for a specific site
• Admin-only access

Remove Site

• Command: remove-site --domain <custom_hostname>
• Removes the site deployment record from the database
• Does NOT delete resources from bunny.net (manual cleanup required)
• Requires confirmation prompt
• Admin-only access

API Integration Requirements

Configuration

• BUNNY_ACCOUNT_API_KEY must be present in environment variables
• Base URL: https://api.bunny.net
• All requests require headers:
  • AccessKey: Account API Key
  • Content-Type: application/json

Workflow A: New Site Provisioning

1. Create Storage Zone

   • Endpoint: POST /storagezone
   • Request: {"Name": "<storage_zone_name>", "Region": "<region>"}
   • Capture: Id, Password

2. Create Pull Zone

   • Endpoint: POST /pullzone
   • Request: {"Name": "<pull_zone_name>", "OriginType": 2, "StorageZoneId": <storage_zone_id>}
   • Capture: Id, Hostname

3. Add Custom Hostname

   • Endpoint: POST /pullzone/{pull_zone_id}/addHostname
   • Request: {"Hostname": "<custom_hostname>"}
   • Verify: 200 OK response

Workflow B: Attach to Existing Storage

1. Find Existing Storage Zone

   • Endpoint: GET /storagezone
   • Parse response to find zone by name
   • Capture: Id, Password, Region

2. Create Pull Zone (same as Workflow A, step 2)

3. Add Custom Hostname (same as Workflow A, step 3)

Error Handling

• Handle API authentication failures (invalid API key)
• Handle resource name conflicts (Storage/Pull Zone names must be unique)
• Handle missing Storage Zones (Workflow B)
• Handle network errors with appropriate retry logic
• Validate region codes before API calls
• Validate FQDN format before provisioning

Output Requirements

• After successful provisioning, display DNS configuration instructions for the user to manually configure with their domain registrar:

  Site provisioned successfully!
  
  MANUAL DNS CONFIGURATION REQUIRED:
  You must create the following CNAME record with your domain registrar:
  
  Type: CNAME
  Host: <subdomain>
  Value: <pull_zone_bcdn_hostname>
  
  Example:
  Type: CNAME
  Host: www
  Value: my-site-cdn.b-cdn.net
  
  Note: DNS propagation may take up to 48 hours.
  

Technical Notes

• Storage Zone names and Pull Zone names must be globally unique across bunny.net
• The Storage Zone password is only returned during creation; it cannot be retrieved later
• OriginType must always be 2 for Storage Zone-backed Pull Zones
• DNS Configuration: This system does NOT automate DNS record creation. The user must manually create CNAME records with their domain registrar. The CLI only provides instructions.
• DNS propagation may take up to 48 hours after the user creates the CNAME record

Dependencies

• Story 1.5 (CLI infrastructure and admin authentication)
• Story 1.2 (Database setup and ORM)
• bunny.net Account API Key in environment configuration

Future Considerations

• Story 4.x will use these stored credentials for file upload operations
• Story 4.x will use these IDs for cache purge operations
• Deletion of bunny.net resources (Storage/Pull Zones) will require separate implementation
• Multi-region replication configuration may be added later