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

Story 3.1 Quick Start Guide

Implementation Complete!

All features for Story 3.1 have been implemented and tested. 44 tests passing.

What You Need to Do

1. Run Database Migration (Dev Environment)

-- Connect to your MySQL database and run:
ALTER TABLE site_deployments MODIFY COLUMN custom_hostname VARCHAR(255) NULL;
ALTER TABLE site_deployments ADD CONSTRAINT uq_pull_zone_bcdn_hostname UNIQUE (pull_zone_bcdn_hostname);

Or run: mysql -u your_user -p your_database < scripts/migrate_story_3.1.sql

2. Import Existing Bunny.net Sites

Now you can import your 400+ existing bunny.net buckets (with or without custom domains):

# Dry run first to see what will be imported
uv run python main.py sync-sites --admin-user your_admin --dry-run

# Actually import
uv run python main.py sync-sites --admin-user your_admin

This will now import ALL bunny.net sites, including those without custom domains.

3. Run Tests

# Run all Story 3.1 tests
uv run pytest tests/unit/test_url_generator.py \
               tests/unit/test_site_provisioning.py \
               tests/unit/test_site_assignment.py \
               tests/unit/test_job_config_extensions.py \
               tests/integration/test_story_3_1_integration.py \
               -v

Expected: 44 tests passing

4. Use New Features

Example Job Config

Create a job config file using the new features:

{
  "jobs": [{
    "project_id": 1,
    "tiers": {
      "tier1": {"count": 10},
      "tier2": {"count": 50}
    },
    "deployment_targets": ["www.primary.com"],
    "tier1_preferred_sites": [
      "www.premium-site.com",
      "site123.b-cdn.net"
    ],
    "auto_create_sites": true,
    "create_sites_for_keywords": [
      {"keyword": "engine repair", "count": 3}
    ]
  }]
}

In Your Code

from src.generation.site_assignment import assign_sites_to_batch
from src.generation.url_generator import generate_urls_for_batch

# After content generation
assign_sites_to_batch(
    content_records=batch_articles,
    job=job,
    site_repo=site_repo,
    bunny_client=bunny_client,
    project_keyword=project.main_keyword,
    region="DE"
)

# Generate URLs
url_mappings = generate_urls_for_batch(
    content_records=batch_articles,
    site_repo=site_repo
)

# Use the URLs
for url_info in url_mappings:
    print(f"{url_info['title']}: {url_info['url']}")

New Features Available

1. Sites Without Custom Domains

• Import and use bunny.net sites that only have .b-cdn.net hostnames
• No custom domain required
• Perfect for your 400+ existing buckets

2. Auto-Creation of Sites

• Set auto_create_sites: true in job config
• System creates sites automatically when pool is insufficient
• Uses project keyword in site names

3. Keyword-Based Site Creation

• Pre-create sites for specific keywords
• Example: {"keyword": "engine repair", "count": 3}
• Creates 3 sites with "engine-repair" in the name

4. Tier1 Preferred Sites

• Specify premium sites for tier1 articles
• Example: "tier1_preferred_sites": ["www.premium.com"]
• Tier1 articles assigned to these first

5. Smart Site Assignment

Tier1 Priority:

1. Preferred sites (if specified)
2. Keyword-matching sites
3. Random from pool

Tier2+ Priority:

1. Keyword-matching sites
2. Random from pool

6. URL Generation

• Automatic slug generation from titles
• Works with custom domains OR bcdn hostnames
• Format: https://domain.com/article-slug.html

File Changes Summary

Modified (6 core files):

• src/database/models.py - Nullable custom_hostname
• src/database/interfaces.py - Optional custom_hostname in interface
• src/database/repositories.py - New get_by_bcdn_hostname() method
• src/templating/service.py - Handles both hostname types
• src/cli/commands.py - sync-sites imports all sites
• src/generation/job_config.py - New config fields

Created (3 new modules):

• src/generation/site_provisioning.py - Creates bunny.net sites
• src/generation/url_generator.py - Generates URLs and slugs
• src/generation/site_assignment.py - Assigns sites to articles

Created (5 test files):

• tests/unit/test_url_generator.py (14 tests)
• tests/unit/test_site_provisioning.py (8 tests)
• tests/unit/test_site_assignment.py (9 tests)
• tests/unit/test_job_config_extensions.py (8 tests)
• tests/integration/test_story_3_1_integration.py (5 tests)

Production Deployment

When you deploy to production:

1. Model changes automatically apply (SQLAlchemy creates tables correctly)
2. No special migration needed - just deploy the code
3. Run sync-sites to import your bunny.net infrastructure
4. Start using the new features

Support

See STORY_3.1_IMPLEMENTATION_SUMMARY.md for detailed documentation.

Example job config: jobs/example_story_3.1_full_features.json