sum-cli 3.0.0__py3-none-any.whl

sum/docs/USER_GUIDE.md

@@ -0,0 +1,663 @@
+# SUM CLI User Guide (v3)
+
+This guide covers the SUM Platform CLI tool v3, which provides commands for deploying and managing production SUM client sites.
+
+## Overview
+
+The SUM CLI v3 (`sum-platform`) is the single control plane for the SUM site lifecycle:
+
+- **`sum-platform init`** - Create new production sites at `/srv/sum/<name>/`
+- **`sum-platform update`** - Update deployed sites (pull, migrate, restart)
+- **`sum-platform backup`** - Backup database and media
+- **`sum-platform promote`** - Deploy staging sites to production servers
+- **`sum-platform check`** - Validate project setup
+- **`sum-platform themes`** - List available themes
+- **`sum-platform run`** - Start development server
+
+## Installation
+
+### Install from PyPI
+
+```bash
+pip install sum-cli
+sum-platform --version
+```
+
+### With Gitea Support
+
+```bash
+pip install sum-cli[gitea]
+```
+
+### Monorepo Development Mode
+
+From the repository root:
+
+```bash
+source .venv/bin/activate
+pip install -e ./cli
+sum-platform --version
+```
+
+---
+
+## Commands
+
+### `sum-platform init` - Create a New Site
+
+Create a new production-ready site with full infrastructure provisioning.
+
+**Requires sudo.** The init command provisions PostgreSQL databases, installs systemd services, and configures Caddy reverse proxy.
+
+#### Basic Usage
+
+```bash
+sudo sum-platform init <site-name> [options]
+```
+
+#### What Init Does
+
+1. Validates prerequisites (sudo, postgres, git, systemctl)
+2. Creates site directories at `/srv/sum/<name>/`
+3. Provisions PostgreSQL database and user
+4. Scaffolds Django/Wagtail project from boilerplate
+5. Creates virtualenv and installs dependencies
+6. Runs database migrations
+7. Seeds initial homepage content
+8. Creates Django superuser
+9. Collects static files
+10. Installs systemd service
+11. Configures Caddy reverse proxy
+12. Starts the site service
+13. Optionally creates Git repository (GitHub or Gitea)
+
+#### Options
+
+| Flag | Description |
+|------|-------------|
+| `--theme <slug>` | Theme to use (default: theme_a) |
+| `--profile <name>` | Content profile to seed (default: starter) |
+| `--content-path <path>` | Path to custom content directory for seeding |
+| `--no-git` | Skip git initialization and repository creation |
+| `--skip-systemd` | Skip systemd service installation |
+| `--skip-caddy` | Skip Caddy reverse proxy configuration |
+| `--superuser <username>` | Custom superuser username (default: admin) |
+
+#### Examples
+
+**Create site with default theme:**
+```bash
+sudo sum-platform init acme
+```
+
+**Create site with specific theme:**
+```bash
+sudo sum-platform init acme --theme theme_b
+```
+
+**Create site with custom content profile:**
+```bash
+sudo sum-platform init acme --profile sage-stone
+```
+
+**Create site with external content directory:**
+```bash
+sudo sum-platform init acme --content-path /path/to/profiles/acme
+```
+
+**Create site without git/GitHub:**
+```bash
+sudo sum-platform init acme --no-git
+```
+
+**Create site with custom superuser:**
+```bash
+sudo sum-platform init acme --superuser markadmin
+```
+
+#### Output
+
+On success:
+```
+Checking infrastructure prerequisites...
+  ✓ Running as root
+  ✓ PostgreSQL available
+  ✓ Git available
+  ✓ systemctl available
+  ⚠ GitHub CLI not available (git operations will be skipped)
+
+Creating site 'acme'...
+  [1/17] Checking prerequisites
+  [2/17] Generating credentials
+  [3/17] Creating directories
+  ...
+  [17/17] Writing credentials file
+
+✅ Site 'acme' created successfully!
+
+Site Information:
+  Domain: acme.lintel.site
+  Admin URL: https://acme.lintel.site/admin/
+  Credentials: /srv/sum/acme/.credentials
+
+Superuser Credentials:
+  Username: admin
+  Password: <generated>
+```
+
+#### Directory Structure
+
+After init, the site directory contains:
+
+```
+/srv/sum/acme/
+├── app/                  # Django project
+│   ├── manage.py
+│   ├── acme/            # Python package
+│   ├── theme/           # Active theme
+│   └── ...
+├── venv/                 # Python virtualenv
+├── static/               # Collected static files
+├── media/                # User uploads
+├── backups/              # Database backups
+├── .env                  # Environment variables
+└── .credentials          # Superuser credentials
+```
+
+---
+
+### `sum-platform update` - Update a Deployed Site
+
+Pull latest code, run migrations, and restart services.
+
+#### Basic Usage
+
+```bash
+sum-platform update <site-name> [options]
+```
+
+#### What Update Does
+
+1. Pulls latest code from git repository
+2. Updates pip dependencies
+3. Runs database migrations (unless skipped)
+4. Collects static files
+5. Restarts systemd service
+
+#### Options
+
+| Flag | Description |
+|------|-------------|
+| `--target <env>` | Target environment: staging (default) or prod |
+| `--skip-migrations` | Skip database migrations |
+
+#### Examples
+
+**Update staging site:**
+```bash
+sum-platform update acme
+```
+
+**Update production site (via SSH):**
+```bash
+sum-platform update acme --target prod
+```
+
+**Update without migrations:**
+```bash
+sum-platform update acme --skip-migrations
+```
+
+#### Output
+
+```
+Updating site 'acme' on staging...
+  [1/5] Pulling latest code
+  [2/5] Installing dependencies
+  [3/5] Running migrations
+  [4/5] Collecting static files
+  [5/5] Restarting service
+
+✅ Site 'acme' updated successfully!
+```
+
+---
+
+### `sum-platform backup` - Backup a Site
+
+Create database and optional media backups.
+
+#### Basic Usage
+
+```bash
+sum-platform backup <site-name> [options]
+```
+
+#### What Backup Does
+
+1. Creates timestamped database dump (pg_dump | gzip)
+2. Optionally archives media directory (tar)
+3. Stores backups in `/srv/sum/<name>/backups/`
+
+#### Options
+
+| Flag | Description |
+|------|-------------|
+| `--target <env>` | Target environment: staging (default) or prod |
+| `--include-media` | Include media directory in backup |
+
+#### Examples
+
+**Backup database only:**
+```bash
+sum-platform backup acme
+```
+
+**Backup database and media:**
+```bash
+sum-platform backup acme --include-media
+```
+
+**Backup production site:**
+```bash
+sum-platform backup acme --target prod
+```
+
+#### Output
+
+```
+Creating backup for site 'acme'...
+  [1/2] Backing up database
+  [2/2] Backing up media
+
+✅ Backup completed!
+
+Backup files:
+  Database: /srv/sum/acme/backups/acme_db_20260201_143022.sql.gz
+  Media: /srv/sum/acme/backups/acme_media_20260201_143022.tar.gz
+```
+
+---
+
+### `sum-platform promote` - Promote to Production
+
+Deploy a staging site to a production server.
+
+#### Basic Usage
+
+```bash
+sum-platform promote <site-name> --domain <domain>
+```
+
+#### What Promote Does
+
+1. Validates staging site exists
+2. Creates backup of staging database
+3. Copies backup to production server via SCP
+4. Provisions production infrastructure via SSH:
+   - Creates directories
+   - Provisions PostgreSQL database
+   - Clones git repository
+   - Creates virtualenv and installs dependencies
+   - Restores database from backup
+   - Syncs media files via rsync
+   - Installs systemd service
+   - Configures Caddy
+   - Starts service
+5. Verifies site health
+
+#### Options
+
+| Flag | Description |
+|------|-------------|
+| `--domain <domain>` | **Required.** Production domain name |
+
+#### Examples
+
+**Promote to production:**
+```bash
+sum-platform promote acme --domain acme.example.com
+```
+
+#### Output
+
+```
+Promoting site 'acme' to production...
+  [1/11] Validating staging site
+  [2/11] Creating staging backup
+  [3/11] Copying backup to production
+  [4/11] Provisioning production directories
+  [5/11] Creating production database
+  [6/11] Cloning repository
+  [7/11] Setting up virtualenv
+  [8/11] Restoring database
+  [9/11] Syncing media
+  [10/11] Installing services
+  [11/11] Verifying health
+
+✅ Site promoted to production!
+
+Production URL: https://acme.example.com
+Admin URL: https://acme.example.com/admin/
+```
+
+---
+
+### `sum-platform check` - Validate Project Setup
+
+Validate that a project is properly configured.
+
+#### Basic Usage
+
+```bash
+sum-platform check [project-name]
+```
+
+#### What Check Validates
+
+| Check | Description |
+|-------|-------------|
+| Virtualenv | `.venv` or `venv/` directory exists with required packages |
+| Credentials | `.env.local` or `.credentials` file exists |
+| Database | Migrations are up to date |
+| Homepage | Default site root page configured |
+| Theme CSS | Compiled CSS exists and is valid |
+| Theme Slug | Theme slug matches configuration |
+| Env Vars | Required environment variables present |
+| sum_core | Core module can be imported |
+
+#### Output
+
+```
+[OK] Virtualenv: venv exists with required packages
+[OK] Credentials: .credentials found
+[OK] Database: Migrations up to date
+[OK] Homepage: Homepage set as site root
+[OK] Theme compiled CSS: /srv/sum/acme/app/theme/active/static/theme_a/css/main.css
+[OK] Theme slug match: theme_a
+[OK] Required env vars: Required env vars present
+[OK] sum_core import: sum_core importable
+
+✅ All checks passed
+```
+
+---
+
+### `sum-platform themes` - List Available Themes
+
+List all themes available in the registry.
+
+#### Usage
+
+```bash
+sum-platform themes
+```
+
+#### Output
+
+```
+Available themes:
+
+  theme_a
+    Name: Theme A
+    Description: Default starter theme
+    Version: 1.0.0
+
+  theme_b
+    Name: Theme B
+    Description: Alternate theme
+    Version: 1.2.0
+```
+
+---
+
+### `sum-platform run` - Start Development Server
+
+Start a local development server for testing.
+
+#### Usage
+
+```bash
+sum-platform run [project-name] [options]
+```
+
+#### Options
+
+| Flag | Description |
+|------|-------------|
+| `--port <port>` | Port to run on (default: 8000) |
+
+#### Examples
+
+**Run with default port:**
+```bash
+sum-platform run acme
+```
+
+**Run on specific port:**
+```bash
+sum-platform run acme --port 8080
+```
+
+---
+
+## Configuration
+
+### System Configuration
+
+The CLI reads configuration from `/etc/sum/config.yml`. All fields are required.
+
+```yaml
+agency:
+  # Your agency/organization name
+  name: "Lintel Digital"
+  # Git provider: "github" (default) or "gitea"
+  git_provider: "github"
+  # GitHub organization (required when git_provider: github)
+  github_org: "lintel-digital"
+  # Gitea settings (required when git_provider: gitea)
+  # gitea_url: "https://gitea.example.com"
+  # gitea_org: "lintel"
+  # gitea_token_env: "GITEA_TOKEN"  # env var name containing API token
+
+staging:
+  # Staging server hostname (for reference)
+  server: "staging.lintel.site"
+  # Domain pattern for staging sites ({slug} will be replaced)
+  domain_pattern: "{slug}.lintel.site"
+  # Base directory for site deployments
+  base_dir: "/srv/sum"
+
+production:
+  # Production server hostname
+  server: "prod.lintel.site"
+  # SSH host for production deployments
+  ssh_host: "10.0.0.1"
+  # Base directory on production server
+  base_dir: "/srv/sum"
+
+templates:
+  # Directory containing infrastructure templates
+  dir: "/opt/lintel-ops/infra"
+  # Relative path to systemd service template
+  systemd: "systemd/sum-site-gunicorn.service.template"
+  # Relative path to Caddy config template
+  caddy: "caddy/Caddyfile.template"
+
+defaults:
+  # Default theme for new sites
+  theme: "theme_a"
+  # User to run site services as
+  deploy_user: "deploy"
+  # Default content seeding profile
+  seed_profile: "starter"
+```
+
+### Gitea Configuration
+
+To use Gitea instead of GitHub:
+
+1. Set `git_provider: "gitea"` in the config
+2. Provide `gitea_url` and `gitea_org`
+3. Set the `GITEA_TOKEN` environment variable (or custom env var name via `gitea_token_env`)
+4. Install with Gitea support: `pip install sum-cli[gitea]`
+
+Example Gitea configuration:
+
+```yaml
+agency:
+  name: "Acme Agency"
+  git_provider: "gitea"
+  gitea_url: "https://git.acme.internal"
+  gitea_org: "acme-sites"
+  gitea_token_env: "GITEA_TOKEN"
+```
+
+### Environment Variables
+
+Sites use `.env` files for configuration:
+
+```bash
+# Database
+DJANGO_DB_NAME=acme_db
+DJANGO_DB_USER=acme_user
+DJANGO_DB_PASSWORD=<generated>
+DJANGO_DB_HOST=localhost
+DJANGO_DB_PORT=5432
+
+# Django
+DJANGO_SECRET_KEY=<generated>
+DJANGO_SETTINGS_MODULE=acme.settings.production
+
+# Site
+ALLOWED_HOSTS=acme.lintel.site
+```
+
+---
+
+## Prerequisites
+
+### For `init` command
+
+- **Root access** (sudo)
+- **PostgreSQL** server running
+- **Git** installed
+- **systemctl** available (systemd)
+- **Caddy** installed (for reverse proxy)
+- **GitHub CLI** (optional, for GitHub repository creation)
+- **GITEA_TOKEN** env var (optional, for Gitea repository creation)
+
+### For `promote` command
+
+- **SSH access** to production server
+- **rsync** installed on both servers
+- Production server with same prerequisites as staging
+
+---
+
+## Troubleshooting
+
+### "This command requires root privileges"
+
+Run the command with sudo:
+```bash
+sudo sum-platform init acme
+```
+
+### "PostgreSQL not available"
+
+Ensure PostgreSQL is running:
+```bash
+sudo systemctl start postgresql
+sudo systemctl status postgresql
+```
+
+### "Site already exists"
+
+The site directory already exists at `/srv/sum/<name>/`. Either:
+- Choose a different name
+- Remove the existing site directory (carefully!)
+
+### "GitHub CLI not available"
+
+Install the GitHub CLI:
+```bash
+# Ubuntu/Debian
+sudo apt install gh
+
+# Then authenticate
+gh auth login
+```
+
+Or use `--no-git` to skip GitHub operations.
+
+### "Gitea API token not found"
+
+Set the token environment variable:
+```bash
+export GITEA_TOKEN="your-gitea-api-token"
+```
+
+Or use `--no-git` to skip Gitea operations.
+
+### Database connection errors
+
+Check PostgreSQL configuration:
+```bash
+sudo -u postgres psql -c "SELECT 1"
+```
+
+Verify the database was created:
+```bash
+sudo -u postgres psql -c "\\l" | grep acme
+```
+
+---
+
+## Migration from CLI v2
+
+### Key Changes
+
+- **No more `clients/` scaffolding** - Sites are created at `/srv/sum/<name>/`
+- **No more `--full` or `--quick`** - Init always does full provisioning
+- **Requires sudo** - Init provisions infrastructure that requires root
+- **New commands** - `update`, `backup`, `promote` for site lifecycle
+- **System config** - Configuration read from `/etc/sum/config.yml`
+- **Git provider choice** - Support for both GitHub and Gitea
+
+### Deprecated Flags
+
+These flags from v2 are no longer supported:
+
+- `--full`, `--quick` - Replaced by always-full provisioning
+- `--no-prompt`, `--ci` - Init is now non-interactive by default
+- `--skip-venv`, `--skip-migrations` - These steps are mandatory
+- `--run`, `--port` - Server is started via systemd, not manually
+
+### Project Structure Changes
+
+**v2 (clients/ scaffolding):**
+```
+clients/acme/
+├── .venv/
+├── manage.py
+└── acme/
+```
+
+**v3 (production sites):**
+```
+/srv/sum/acme/
+├── app/
+│   ├── manage.py
+│   └── acme/
+├── venv/
+├── static/
+├── media/
+└── backups/
+```
+
+---
+
+## Support
+
+- **Issues:** [GitHub Issues](https://github.com/markashton480/sum-platform/issues)

sum/exceptions.py

@@ -0,0 +1,45 @@
+"""CLI-specific exception hierarchy.
+
+All CLI exceptions inherit from SumCliError for consistent catching.
+ThemeValidationError also inherits ValueError for compatibility with
+validation patterns that expect ValueError subclasses.
+"""
+
+
+class SumCliError(Exception):
+    """Base exception for SUM CLI failures."""
+
+
+class SetupError(SumCliError):
+    """Raised when initial setup steps fail."""
+
+
+class ThemeNotFoundError(SumCliError):
+    """Raised when a requested theme slug cannot be found."""
+
+
+class ThemeValidationError(SumCliError, ValueError):
+    """Raised when theme exists but is invalid (bad manifest or missing files).
+
+    Inherits ValueError for compatibility with validation error handling patterns.
+    """
+
+
+class VenvError(SumCliError):
+    """Raised when virtual environment operations fail."""
+
+
+class DependencyError(SumCliError):
+    """Raised when dependency installation or resolution fails."""
+
+
+class MigrationError(SumCliError):
+    """Raised when database migrations fail."""
+
+
+class SeedError(SumCliError):
+    """Raised when seed data operations fail."""
+
+
+class SuperuserError(SumCliError):
+    """Raised when superuser creation fails."""

sum/setup/__init__.py

@@ -0,0 +1,17 @@
+from __future__ import annotations
+
+from sum.setup.auth import SuperuserManager
+from sum.setup.database import DatabaseManager
+from sum.setup.deps import DependencyManager
+from sum.setup.orchestrator import SetupOrchestrator
+from sum.setup.seed import ContentSeeder
+from sum.setup.venv import VenvManager
+
+__all__ = [
+    "ContentSeeder",
+    "DatabaseManager",
+    "DependencyManager",
+    "SetupOrchestrator",
+    "SuperuserManager",
+    "VenvManager",
+]