spaps-server-quickstart 0.2.0__tar.gz → 0.2.2__tar.gz

{spaps_server_quickstart-0.2.0 → spaps_server_quickstart-0.2.2}/.gitignore

@@ -37,6 +37,10 @@ build/
 out/
 *.tsbuildinfo
 
+# Storybook
+storybook-static/
+*.storybook
+
 # Environment files
 .env
 .env.*

{spaps_server_quickstart-0.2.0 → spaps_server_quickstart-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: spaps-server-quickstart
-Version: 0.2.0
+Version: 0.2.2
 Summary: Shared FastAPI/Celery scaffolding for Sweet Potato service backends.
 Project-URL: Repository, https://github.com/sweet-potato/spaps
 Author-email: buildooor <buildooor@gmail.com>
@@ -32,6 +32,7 @@ Requires-Dist: pytest-asyncio<0.24,>=0.23.0; extra == 'dev'
 Requires-Dist: pytest-cov<6.0,>=5.0.0; extra == 'dev'
 Requires-Dist: pytest<9.0,>=8.2.0; extra == 'dev'
 Requires-Dist: ruff<0.5,>=0.4.1; extra == 'dev'
+Requires-Dist: types-pyyaml<7.0,>=6.0.0; extra == 'dev'
 Provides-Extra: release
 Requires-Dist: build<2.0,>=1.2.1; extra == 'release'
 Requires-Dist: twine<6.0,>=5.0.0; extra == 'release'
@@ -67,6 +68,48 @@ poetry run -C packages/python-server-quickstart pytest
 The shared modules are designed to be imported by individual service packages. Tests live
 alongside the shared code to guard the common behaviour.
 
+### Local Auth Bypass Mode
+
+For local development without external auth services, enable local mode by setting
+`DEVELOPMENT_ENVIRONMENT=local`. This provides pre-configured personas (admin/user)
+that bypass SPAPS authentication.
+
+```python
+from spaps_server_quickstart.settings import BaseServiceSettings
+from spaps_server_quickstart.local_mode import (
+    LocalAuthMiddleware,
+    get_default_registry,
+)
+
+settings = BaseServiceSettings(development_environment="local")
+
+if settings.is_local_development:
+    app.add_middleware(LocalAuthMiddleware, registry=get_default_registry())
+```
+
+**Available personas:**
+
+| Persona | Token | Roles |
+| --- | --- | --- |
+| Admin | `local-admin` | `admin`, `user` |
+| User | `local-user` | `user` |
+
+Use the token in your Authorization header: `Authorization: Bearer local-admin`
+
+Optional local auth routes are available under `spaps_server_quickstart.templates.domains.auth.local_routes`:
+
+```python
+from spaps_server_quickstart.templates.domains.auth.local_routes import router as local_auth_router
+
+if settings.is_local_development:
+    app.include_router(local_auth_router, prefix="/v1/auth", tags=["local-auth"])
+```
+
+This adds:
+- `GET /v1/auth/local-personas` - List available personas
+- `POST /v1/auth/local-login` - Login with persona code or token
+- `GET /v1/auth/local-me` - Get current persona from Authorization header
+
 ## Operational Templates
 
 For infrastructure parity with live SPAPS services, the directory
@@ -74,15 +117,94 @@ For infrastructure parity with live SPAPS services, the directory
 
 - Makefile with lint/test/deploy shortcuts
 - Production `.env.production.example`
-- Docker Compose + reverse-proxy stubs
-- Deploy script that refreshes the shared proxy
+- Docker Compose + reverse-proxy stubs (pre-configured with Docker DNS resolver support)
+- Deploy script that reloads the shared proxy in-place after each rollout
+- **Pre/post deployment checks** (`pre-deploy-checks.sh`, `post-deploy-verify.sh`)
 - Database maintenance scripts (`backup-db.sh`, `restore-db.sh`, `new-migration.sh`)
 - Pre-push hook + `scripts/prepush.sh` matching live automation
+- Local Postgres helpers under `scripts/dev/` (`start-db.sh`, `stop-db.sh`, `await_db.py`) for pgvector-backed test runs
+
+### Deployment Checks
+
+The deployment scripts include automated validation:
+
+**Pre-deployment (`pre-deploy-checks.sh`):**
+- Docker availability and daemon status
+- Port availability for required services
+- Disk space validation (configurable minimum)
+- Required environment variable validation
+- Dev container conflict detection
+- Docker network verification
+
+**Post-deployment (`post-deploy-verify.sh`):**
+- Container running status
+- Health endpoint validation with exponential backoff
+- Image version verification
+- Migration status check (optional)
+- Docker healthcheck status
+- Service connectivity (Redis, database)
+
+Configuration via environment variables:
+
+| Variable | Description | Default |
+| --- | --- | --- |
+| `SERVICE_NAME` | Service identifier for checks | `quickstart` |
+| `REQUIRED_PORTS` | Comma-separated ports to check | `8000` |
+| `MIN_DISK_SPACE_GB` | Minimum disk space required | `5` |
+| `REQUIRED_ENV_VARS` | Required environment variables | `` |
+| `HEALTH_ENDPOINT` | URL for health check | `http://localhost:8000/health` |
+| `MAX_HEALTH_WAIT` | Max seconds to wait for health | `60` |
+| `SKIP_PRE_CHECKS` | Skip pre-deployment checks | `0` |
+| `SKIP_POST_CHECKS` | Skip post-deployment checks | `0` |
+
+### Database Caching for Local Development
+
+The `local-debug-loop.sh` script caches seeded database state to speed up `make local-up`:
+
+```bash
+# First run: seeds database and creates cache
+make local-up
+
+# Subsequent runs: restores from cache if seeds/migrations unchanged
+make local-up
+
+# Force full reseed (ignores cache)
+make local-up-seed
+
+# Watch mode: auto-reseeds when files change
+make local-up-watch
+```
+
+**How it works:**
+1. Computes SHA256 hash of `alembic/`, `scripts/seeds/`, `fixtures/` directories
+2. If hash matches cached version, restores database from `pg_dump` cache
+3. If hash differs, runs full migrations + seeds, then saves new cache
+4. Cache stored at `~/.cache/${SERVICE_NAME}/db/seeded.sql.gz`
+
+**Configuration:**
+
+| Variable | Description | Default |
+| --- | --- | --- |
+| `SERVICE_NAME` | Service name for cache paths | `quickstart` |
+| `CACHE_ROOT` | Base cache directory | `~/.cache/${SERVICE_NAME}` |
+| `FORCE_RESEED` | Force full reseed ignoring cache | `0` |
+| `SKIP_DB_CACHE` | Disable caching entirely | `0` |
+| `CACHE_TARGETS` | Directories to include in hash | `alembic scripts/seeds fixtures` |
+| `LOCAL_WATCH` | Enable watch mode for auto-reseed | `0` |
 
 Copy the folder into a service repository when adopting the quickstart so CI/CD, GHCR pulls, backup automation,
 and the shared reverse proxy follow the same playbook used by Ingredient, HTMA, and Sweet Potato. Update the provided
 environment variables (`PROJECT_SLUG`, `DB_SERVICE`, etc.) after copying to match the new service naming.
 
+The reverse proxy template adds `resolver 127.0.0.11 ipv6=off valid=30s;` and marks upstream servers with `resolve`
+so nginx re-resolves Docker service names whenever containers cycle. During deployment the helper issues
+`docker exec shared-reverse-proxy nginx -s reload` (falling back to the legacy `./up.sh` script) so configuration
+changes take effect without bouncing the proxy container.
+
+When developing locally, start the database with `scripts/dev/start-db.sh` before running `scripts/prepush.sh` or
+pytest. The helper waits for a pgvector-enabled Postgres on port 5433 and seeds `PYTEST_DATABASE_URL`,
+`DATABASE_URL`, and `SYNC_DATABASE_URL` with sensible defaults. Shut it down with `scripts/dev/stop-db.sh`.
+
 ## RBAC Helpers & Sample Routers
 
 - Use `spaps_server_quickstart.rbac.require_roles` as a FastAPI dependency to guard admin/staff-only
@@ -130,6 +252,7 @@ plumbing. All list-like settings accept comma-separated environment variables fo
 
 | Variable | Description | Notes |
 | --- | --- | --- |
+| `DEVELOPMENT_ENVIRONMENT` | Set to `local` to enable local auth bypass | Defaults to `None` |
 | `SPAPS_API_URL` | Base URL for SPAPS API requests | Defaults to `https://api.sweetpotato.dev` |
 | `SPAPS_API_KEY` | Service API key used for auth + channel helpers | Required when `spaps_auth_enabled` is true |
 | `SPAPS_APPLICATION_ID` | Application identifier enforced during session validation | Required when `spaps_auth_enabled` is true |

{spaps_server_quickstart-0.2.0 → spaps_server_quickstart-0.2.2}/README.md

@@ -28,6 +28,48 @@ poetry run -C packages/python-server-quickstart pytest
 The shared modules are designed to be imported by individual service packages. Tests live
 alongside the shared code to guard the common behaviour.
 
+### Local Auth Bypass Mode
+
+For local development without external auth services, enable local mode by setting
+`DEVELOPMENT_ENVIRONMENT=local`. This provides pre-configured personas (admin/user)
+that bypass SPAPS authentication.
+
+```python
+from spaps_server_quickstart.settings import BaseServiceSettings
+from spaps_server_quickstart.local_mode import (
+    LocalAuthMiddleware,
+    get_default_registry,
+)
+
+settings = BaseServiceSettings(development_environment="local")
+
+if settings.is_local_development:
+    app.add_middleware(LocalAuthMiddleware, registry=get_default_registry())
+```
+
+**Available personas:**
+
+| Persona | Token | Roles |
+| --- | --- | --- |
+| Admin | `local-admin` | `admin`, `user` |
+| User | `local-user` | `user` |
+
+Use the token in your Authorization header: `Authorization: Bearer local-admin`
+
+Optional local auth routes are available under `spaps_server_quickstart.templates.domains.auth.local_routes`:
+
+```python
+from spaps_server_quickstart.templates.domains.auth.local_routes import router as local_auth_router
+
+if settings.is_local_development:
+    app.include_router(local_auth_router, prefix="/v1/auth", tags=["local-auth"])
+```
+
+This adds:
+- `GET /v1/auth/local-personas` - List available personas
+- `POST /v1/auth/local-login` - Login with persona code or token
+- `GET /v1/auth/local-me` - Get current persona from Authorization header
+
 ## Operational Templates
 
 For infrastructure parity with live SPAPS services, the directory
@@ -35,15 +77,94 @@ For infrastructure parity with live SPAPS services, the directory
 
 - Makefile with lint/test/deploy shortcuts
 - Production `.env.production.example`
-- Docker Compose + reverse-proxy stubs
-- Deploy script that refreshes the shared proxy
+- Docker Compose + reverse-proxy stubs (pre-configured with Docker DNS resolver support)
+- Deploy script that reloads the shared proxy in-place after each rollout
+- **Pre/post deployment checks** (`pre-deploy-checks.sh`, `post-deploy-verify.sh`)
 - Database maintenance scripts (`backup-db.sh`, `restore-db.sh`, `new-migration.sh`)
 - Pre-push hook + `scripts/prepush.sh` matching live automation
+- Local Postgres helpers under `scripts/dev/` (`start-db.sh`, `stop-db.sh`, `await_db.py`) for pgvector-backed test runs
+
+### Deployment Checks
+
+The deployment scripts include automated validation:
+
+**Pre-deployment (`pre-deploy-checks.sh`):**
+- Docker availability and daemon status
+- Port availability for required services
+- Disk space validation (configurable minimum)
+- Required environment variable validation
+- Dev container conflict detection
+- Docker network verification
+
+**Post-deployment (`post-deploy-verify.sh`):**
+- Container running status
+- Health endpoint validation with exponential backoff
+- Image version verification
+- Migration status check (optional)
+- Docker healthcheck status
+- Service connectivity (Redis, database)
+
+Configuration via environment variables:
+
+| Variable | Description | Default |
+| --- | --- | --- |
+| `SERVICE_NAME` | Service identifier for checks | `quickstart` |
+| `REQUIRED_PORTS` | Comma-separated ports to check | `8000` |
+| `MIN_DISK_SPACE_GB` | Minimum disk space required | `5` |
+| `REQUIRED_ENV_VARS` | Required environment variables | `` |
+| `HEALTH_ENDPOINT` | URL for health check | `http://localhost:8000/health` |
+| `MAX_HEALTH_WAIT` | Max seconds to wait for health | `60` |
+| `SKIP_PRE_CHECKS` | Skip pre-deployment checks | `0` |
+| `SKIP_POST_CHECKS` | Skip post-deployment checks | `0` |
+
+### Database Caching for Local Development
+
+The `local-debug-loop.sh` script caches seeded database state to speed up `make local-up`:
+
+```bash
+# First run: seeds database and creates cache
+make local-up
+
+# Subsequent runs: restores from cache if seeds/migrations unchanged
+make local-up
+
+# Force full reseed (ignores cache)
+make local-up-seed
+
+# Watch mode: auto-reseeds when files change
+make local-up-watch
+```
+
+**How it works:**
+1. Computes SHA256 hash of `alembic/`, `scripts/seeds/`, `fixtures/` directories
+2. If hash matches cached version, restores database from `pg_dump` cache
+3. If hash differs, runs full migrations + seeds, then saves new cache
+4. Cache stored at `~/.cache/${SERVICE_NAME}/db/seeded.sql.gz`
+
+**Configuration:**
+
+| Variable | Description | Default |
+| --- | --- | --- |
+| `SERVICE_NAME` | Service name for cache paths | `quickstart` |
+| `CACHE_ROOT` | Base cache directory | `~/.cache/${SERVICE_NAME}` |
+| `FORCE_RESEED` | Force full reseed ignoring cache | `0` |
+| `SKIP_DB_CACHE` | Disable caching entirely | `0` |
+| `CACHE_TARGETS` | Directories to include in hash | `alembic scripts/seeds fixtures` |
+| `LOCAL_WATCH` | Enable watch mode for auto-reseed | `0` |
 
 Copy the folder into a service repository when adopting the quickstart so CI/CD, GHCR pulls, backup automation,
 and the shared reverse proxy follow the same playbook used by Ingredient, HTMA, and Sweet Potato. Update the provided
 environment variables (`PROJECT_SLUG`, `DB_SERVICE`, etc.) after copying to match the new service naming.
 
+The reverse proxy template adds `resolver 127.0.0.11 ipv6=off valid=30s;` and marks upstream servers with `resolve`
+so nginx re-resolves Docker service names whenever containers cycle. During deployment the helper issues
+`docker exec shared-reverse-proxy nginx -s reload` (falling back to the legacy `./up.sh` script) so configuration
+changes take effect without bouncing the proxy container.
+
+When developing locally, start the database with `scripts/dev/start-db.sh` before running `scripts/prepush.sh` or
+pytest. The helper waits for a pgvector-enabled Postgres on port 5433 and seeds `PYTEST_DATABASE_URL`,
+`DATABASE_URL`, and `SYNC_DATABASE_URL` with sensible defaults. Shut it down with `scripts/dev/stop-db.sh`.
+
 ## RBAC Helpers & Sample Routers
 
 - Use `spaps_server_quickstart.rbac.require_roles` as a FastAPI dependency to guard admin/staff-only
@@ -91,6 +212,7 @@ plumbing. All list-like settings accept comma-separated environment variables fo
 
 | Variable | Description | Notes |
 | --- | --- | --- |
+| `DEVELOPMENT_ENVIRONMENT` | Set to `local` to enable local auth bypass | Defaults to `None` |
 | `SPAPS_API_URL` | Base URL for SPAPS API requests | Defaults to `https://api.sweetpotato.dev` |
 | `SPAPS_API_KEY` | Service API key used for auth + channel helpers | Required when `spaps_auth_enabled` is true |
 | `SPAPS_APPLICATION_ID` | Application identifier enforced during session validation | Required when `spaps_auth_enabled` is true |