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