Big-Link-Man/STORY_4.1_QUICKSTART.md

# Story 4.1: Deploy Content to Cloud - Quick Start Guide

## Prerequisites

1. Ensure `BUNNY_ACCOUNT_API_KEY` is in your `.env` file (for creating zones):
   ```bash
   BUNNY_ACCOUNT_API_KEY=your_account_api_key_here
   ```
   
   **Note**: File uploads use per-zone `storage_zone_password` from the database, NOT an API key from `.env`. These passwords are set automatically when sites are created via `provision-site` or `sync-sites` commands.

2. Run the database migration:
   ```bash
   uv run python scripts/migrate_add_deployment_fields.py
   ```

## Usage

### Automatic Deployment (Recommended)

Content deploys automatically after batch generation completes:

```bash
uv run python -m src.cli generate-batch \
  --job-file jobs/my_job.json \
  --username admin \
  --password mypass
```

Output will show deployment progress after all tiers complete:
```
  Deployment: Starting automatic deployment for project 123...
  Deployment: 48 articles, 6 pages deployed
  Deployment: Complete in 45.2s
```

### Manual Deployment

Deploy (or re-deploy) a batch manually:

```bash
uv run python -m src.cli deploy-batch \
  --batch-id 123 \
  --admin-user admin \
  --admin-password mypass
```

### Dry Run Mode

Preview what would be deployed without actually uploading:

```bash
uv run python -m src.cli deploy-batch \
  --batch-id 123 \
  --dry-run
```

## What Gets Deployed

1. **Articles**: All generated articles with `formatted_html`
   - Uploaded to: `{slug}.html` (e.g., `how-to-fix-engines.html`)
   - URL logged to: `deployment_logs/YYYY-MM-DD_tier1_urls.txt` (Tier 1)
   - URL logged to: `deployment_logs/YYYY-MM-DD_other_tiers_urls.txt` (Tier 2+)

2. **Boilerplate Pages**: About, contact, privacy (if they exist)
   - Uploaded to: `about.html`, `contact.html`, `privacy.html`
   - NOT logged to URL files

## URL Logging

Deployed article URLs are automatically logged to tier-segregated files:

```
deployment_logs/
  2025-10-22_tier1_urls.txt
  2025-10-22_other_tiers_urls.txt
```

Each file contains one URL per line:
```
https://example.com/article-1.html
https://example.com/article-2.html
https://example.com/article-3.html
```

Duplicate URLs are automatically prevented (safe to re-run deployments).

## Database Updates

After successful deployment, each article is updated with:
- `deployed_url`: Public URL where content is live
- `deployed_at`: Timestamp of deployment
- `status`: Changed to 'deployed'

Query deployed content:
```python
from src.database.session import db_manager
from src.database.repositories import GeneratedContentRepository

session = db_manager.get_session()
repo = GeneratedContentRepository(session)

deployed = repo.get_deployed_content(project_id=123)
for article in deployed:
    print(f"{article.title}: {article.deployed_url}")
```

## Deployment Summary

After deployment completes, you'll see a summary:

```
======================================================================
Deployment Summary
======================================================================
Articles deployed:  48
Articles failed:    2
Pages deployed:     6
Pages failed:       0
Total time:         45.2s

Errors:
  Article 15 (Engine Maintenance Tips): Connection timeout
  Article 32 (Common Problems): Invalid HTML content
======================================================================
```

## Error Handling

By default, deployment continues even if individual files fail. This ensures partial deployments complete successfully.

Failed files are:
- Logged to console with error details
- Listed in deployment summary
- NOT marked as deployed in database

To stop on first error:
```bash
uv run python -m src.cli deploy-batch \
  --batch-id 123 \
  --continue-on-error false
```

## Troubleshooting

### "Authentication failed for zone"
Check that the `storage_zone_password` in your database is correct. This is set when sites are created via `provision-site` or `sync-sites` commands.

### "Article has no formatted_html to deploy"
Ensure articles have templates applied. This happens automatically during batch processing in `_post_process_tier()`.

### "Site not found"
Ensure articles are assigned to sites. This happens automatically during batch processing via site assignment logic.

## Manual Re-deployment

To re-deploy content after fixes:

1. Fix the issue (update HTML, fix credentials, etc.)
2. Run manual deployment:
   ```bash
   uv run python -m src.cli deploy-batch --batch-id 123
   ```
3. Duplicate URLs are automatically prevented in log files

## Integration with Other Stories

- **Story 3.1**: Articles must be assigned to sites before deployment
- **Story 3.4**: Boilerplate pages are deployed if they exist in `site_pages` table
- **Story 4.2**: URL log files are consumed by post-deployment processes
- **Story 4.3**: Database status updates enable deployment tracking