Doctor plugin checks: implement health check classes and documentation

Implement remediation-aware health checks across all Doctor plugin modules (Agent, Attestor, Auth, BinaryAnalysis, Compliance, Crypto, Environment, EvidenceLocker, Notify, Observability, Operations, Policy, Postgres, Release, Scanner, Storage, Vex) and their backing library counterparts (AI, Attestation, Authority, Core, Cryptography, Database, Docker, Integration, Notify, Observability, Security, ServiceGraph, Sources, Verification). Each check now emits structured remediation metadata (severity, category, runbook links, and fix suggestions) consumed by the Doctor dashboard remediation panel. Also adds: - docs/doctor/articles/ knowledge base for check explanations - Advisory AI search seed and allowlist updates for doctor content - Sprint plan for doctor checks documentation Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-03-27 12:28:00 +02:00
parent fbd24e71de
commit c58a236d70
326 changed files with 18500 additions and 463 deletions
--- a/docs/doctor/articles/postgres/migrations.md
+++ b/docs/doctor/articles/postgres/migrations.md
@@ -0,0 +1,127 @@
+---
+checkId: check.postgres.migrations
+plugin: stellaops.doctor.postgres
+severity: warn
+tags: [database, postgres, migrations, schema]
+---
+# PostgreSQL Migration Status
+
+## What It Checks
+Connects to PostgreSQL and examines the EF Core migration history to identify pending migrations:
+
+1. **Migration table existence**: checks for the `__EFMigrationsHistory` table in the `public` schema. Warns if the table does not exist.
+2. **Applied migrations**: queries the migration history table (ordered by `MigrationId` descending) to determine which migrations have been applied.
+3. **Pending migrations**: compares applied migrations against the expected set to identify any unapplied migrations. Warns if pending migrations are found.
+
+Evidence collected: `TableExists`, `AppliedCount`, `PendingCount`, `LatestApplied`, `PendingMigrations`, `Status`.
+
+The check requires `ConnectionStrings:StellaOps` or `Database:ConnectionString` to be configured.
+
+## Why It Matters
+Pending database migrations mean the database schema does not match what the application code expects. This causes 500 errors when the application tries to access tables or columns that do not exist, or uses schema features that have not been applied. In Stella Ops, missing migrations are the number one cause of service failures after an upgrade. Services may start and appear healthy but fail on the first database operation that touches a missing table or column.
+
+## Common Causes
+- New deployment with schema changes but migration not executed
+- Migration was not run after a version update
+- Previous migration attempt failed partway through
+- Database initialized without EF Core (manual SQL scripts used instead)
+- Migration history table was accidentally dropped
+- First deployment to a fresh database with no migration history
+- Auto-migration disabled or not configured in service startup
+
+## How to Fix
+
+### Docker Compose
+```bash
+# Check migration status
+docker compose -f docker-compose.stella-ops.yml exec platform \
+  stella db migrations status
+
+# Apply pending migrations
+docker compose -f docker-compose.stella-ops.yml exec platform \
+  stella db migrate
+
+# If auto-migration is configured, restart the service (it migrates on startup)
+docker compose -f docker-compose.stella-ops.yml restart platform
+
+# Verify migration status after applying
+docker compose -f docker-compose.stella-ops.yml exec platform \
+  stella db migrations list
+```
+
+Ensure auto-migration is enabled:
+
+```yaml
+services:
+  platform:
+    environment:
+      Platform__AutoMigrate: "true"
+```
+
+### Bare Metal / systemd
+```bash
+# List pending migrations
+stella db migrations list --pending
+
+# Apply pending migrations
+stella db migrate
+
+# Verify all migrations are applied
+stella db migrations status
+
+# If auto-migration is configured, restart the service
+sudo systemctl restart stellaops-platform
+```
+
+Edit `/etc/stellaops/platform/appsettings.json` to enable auto-migration:
+
+```json
+{
+  "Platform": {
+    "AutoMigrate": true
+  }
+}
+```
+
+### Kubernetes / Helm
+```bash
+# Check migration status
+kubectl exec -it <platform-pod> -- stella db migrations status
+
+# Apply pending migrations
+kubectl exec -it <platform-pod> -- stella db migrate
+
+# Or use a migration Job
+kubectl apply -f - <<EOF
+apiVersion: batch/v1
+kind: Job
+metadata:
+  name: stellaops-migrate
+spec:
+  template:
+    spec:
+      containers:
+      - name: migrate
+        image: stellaops/platform:latest
+        command: ["stella", "db", "migrate"]
+      restartPolicy: Never
+EOF
+```
+
+Set in Helm `values.yaml`:
+
+```yaml
+platform:
+  autoMigrate: true
+  migrations:
+    runOnStartup: true
+```
+
+## Verification
+```
+stella doctor run --check check.postgres.migrations
+```
+
+## Related Checks
+- `check.postgres.connectivity` -- migrations require a working database connection
+- `check.postgres.pool` -- connection pool issues can cause migration failures