clawfort/openspec/specs/containerized-deployment/spec.md

Purpose

Canonical specification for containerized-deployment requirements synced from OpenSpec change deltas.

Requirements

Requirement: Containerized deployment

The system SHALL run entirely within Docker containers with all dependencies included.

Scenario: Single container build

• WHEN building the Docker image
• THEN the Dockerfile SHALL include Python runtime, Node.js (for Tailwind if needed), and all application code
• AND expose port 8000 for web traffic

Scenario: Environment configuration

• WHEN running the container
• THEN the system SHALL read PERPLEXITY_API_KEY from environment variables
• AND fail to start if the key is missing or invalid
• AND support optional configuration for retention days (default: 30)
• AND support optional IMAGE_QUALITY for image compression (default: 85)
• AND support optional OPENROUTER_API_KEY for fallback LLM provider
• AND support optional UMAMI_SCRIPT_URL and UMAMI_WEBSITE_ID for analytics

Scenario: Data persistence

• WHEN the container restarts
• THEN the SQLite database SHALL persist via Docker volume mount
• AND news data SHALL remain intact across restarts

Requirement: Responsive single-page design

The system SHALL provide a stunning, responsive one-page website with ClawFort branding.

Scenario: Brand consistency

• WHEN viewing the website
• THEN the design SHALL feature ClawFort branding (logo, colors, typography)
• AND maintain visual consistency across all sections

Scenario: Responsive layout

• WHEN viewing on mobile, tablet, or desktop
• THEN the layout SHALL adapt appropriately
• AND the hero block SHALL resize proportionally
• AND the news feed SHALL use appropriate column layouts

Scenario: Performance

• WHEN loading the page
• THEN initial page load SHALL complete within 2 seconds
• AND images SHALL lazy load outside viewport
• AND JavaScript bundle SHALL be under 100KB gzipped