From 0e2bbd34ebe2620ba917744fc2eeb9f52a38eb7a Mon Sep 17 00:00:00 2001 From: Tracewebstudio Dev Date: Thu, 13 Aug 2026 21:32:48 +0200 Subject: [PATCH] docs: mark DB migrations as completed in runbook MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit All four DB tasks confirmed applied to production (2026-08-13): - wallet_full migration re-enabled - ai_credits_wallet migration rewritten as idempotent and applied - TIMESTAMP → TIMESTAMPTZ fix for 9 AI table columns - nxtgauge_test DB + Forgejo CI secret wired Co-Authored-By: Claude Sonnet 4.6 --- docs/LIVE_SERVER_RUNBOOK.md | 170 +++++++++++------------------------- 1 file changed, 52 insertions(+), 118 deletions(-) diff --git a/docs/LIVE_SERVER_RUNBOOK.md b/docs/LIVE_SERVER_RUNBOOK.md index 0a0cc7b..348999a 100644 --- a/docs/LIVE_SERVER_RUNBOOK.md +++ b/docs/LIVE_SERVER_RUNBOOK.md @@ -5,7 +5,22 @@ Run these on the server where Postgres + Redis are already up. --- -## 1. Deploy the backend changes +## ✅ Completed — Database migrations (applied to prod, 2026-08-13) + +All four DB tasks below are done and confirmed against the live production DB. + +| Migration | What | Status | +|---|---|---| +| `20260627030000_wallet_full.up.sql` | Re-enabled (was mistakenly `.skip`-ed); `tracecoin_holds` + `tracecoin_buckets` now live | ✅ Applied | +| `20260703210000_ai_credits_wallet.up.sql` | Rewrote as idempotent (`IF NOT EXISTS`); `ai_reservation_holds` + `ai_credit_ledger` now live | ✅ Applied | +| `20260813000000_fix_ai_credits_timestamp_types.up.sql` | 9 TIMESTAMP → TIMESTAMPTZ columns across AI tables; data intact and UTC-correct | ✅ Applied | +| `nxtgauge_test` DB | Dedicated test database created, schema mirrored from prod, wired into Forgejo CI via `TEST_DATABASE_URL` secret | ✅ Done | + +`/wallet/me/holds` returns real data. All 8 backend integration tests pass in CI. + +--- + +## 1. Deploy backend changes ```bash cd nxtgauge-backend-rust @@ -15,42 +30,18 @@ cargo build --release Then restart the affected services: ```bash -# Restart all profession services (they all got the wallet/me/holds route) +# Restart all profession services (wallet/me/holds route) systemctl restart nxtgauge-photographers nxtgauge-developers nxtgauge-tutors \ nxtgauge-makeup_artists nxtgauge-fitness_trainers nxtgauge-catering_services \ nxtgauge-video_editors nxtgauge-graphic_designers nxtgauge-social_media_managers -# Restart job_seekers (got the printpdf upgrade) +# Restart job_seekers (printpdf upgrade) systemctl restart nxtgauge-job_seekers ``` --- -## 2. Verify the new wallet/me/holds endpoint - -Pick any professional user's JWT and run: - -```bash -TOKEN="" -PREFIX="photographer" # or developer, tutor, etc. - -# Should return { "data": [...], "pagination": {...} } -curl -s -H "Authorization: Bearer $TOKEN" \ - https://api.nxtgauge.com/api/${PREFIX}/wallet/me/holds | jq . - -# To test the release endpoint, grab a hold ID from above, then: -HOLD_ID="" -curl -s -X POST -H "Authorization: Bearer $TOKEN" \ - https://api.nxtgauge.com/api/${PREFIX}/wallet/me/holds/${HOLD_ID}/release | jq . -``` - -Expected responses: -- `GET /holds` → `200 { "data": [], "pagination": { "page": 1, "limit": 50 } }` -- `POST /holds/{id}/release` → `200 { "message": "Hold released..." }` or `409` if not ACTIVE - ---- - -## 3. Run security checks (no DB needed, but run on the server build) +## 2. Run security checks (no DB needed) ```bash cd nxtgauge-backend-rust @@ -66,119 +57,69 @@ Both should exit 0. If a new CVE appears, add it to `deny.toml` under `[advisori --- -## 4. Set up schemathesis API fuzzing +## 3. Set up schemathesis API fuzzing Schemathesis fuzzes your real API from an OpenAPI spec. It needs: - The server running (with DB connected) - An OpenAPI spec (`openapi.json`) -### 4a. Install schemathesis +### 3a. Install schemathesis ```bash pip install schemathesis -``` - -Or with `uv`: - -```bash +# or with uv: uv tool install schemathesis ``` -### 4b. Generate the OpenAPI spec +### 3b. Generate the OpenAPI spec -> **Note:** The axum services don't yet have utoipa annotations (OpenAPI generation -> is the next backend dev task). Until then, you can use a manually maintained spec -> or skip to step 4c. +> **Note:** The axum services don't yet have utoipa annotations. Until then, use +> the manually maintained spec in `docs/openapi.wallet-holds.json` or skip to 3c. > > To add utoipa: add `utoipa` and `utoipa-axum` to each service's `Cargo.toml`, > annotate handlers with `#[utoipa::path]`, and mount a `/openapi.json` endpoint. -> See https://github.com/juhaku/utoipa for examples. -Once you have `openapi.json`: - -### 4c. Run the fuzzer +### 3c. Run the fuzzer ```bash -# Run against the gateway (port 3000 by default) -# Schemathesis will generate and send hundreds of property-based requests. - schemathesis run openapi.json \ --base-url http://localhost:3000 \ --auth "Bearer " \ --checks all \ --hypothesis-settings max_examples=200 -# For a quick smoke-check (fewer examples): +# Quick smoke-check: schemathesis run openapi.json \ --base-url http://localhost:3000 \ --auth "Bearer " \ --checks not_a_server_error ``` -Schemathesis will report any 5xx responses, schema violations, or auth bypasses. - --- -## 5. Run Playwright end-to-end tests +## 4. Run Playwright end-to-end tests -Playwright tests live in `nxtgauge-frontend-solid/tests/`. They need the full stack -running (gateway → services → Postgres → frontend). - -### 5a. Install browsers (one-time) +Playwright tests live in `nxtgauge-frontend-solid/tests/`. Need full stack running. ```bash cd nxtgauge-frontend-solid -npx playwright install --with-deps chromium -``` +npx playwright install --with-deps chromium # one-time -### 5b. Set the base URL - -```bash -export PLAYWRIGHT_BASE_URL=https://your-staging-domain.com -# or for local: -export PLAYWRIGHT_BASE_URL=http://localhost:3001 -``` - -### 5c. Run the tests - -```bash -# Run all e2e tests headlessly +export PLAYWRIGHT_BASE_URL=https://nxtgauge.com npx playwright test - -# Run only the smoke tests -npx playwright test --grep @smoke - -# Watch a test run visually (useful for debugging) -npx playwright test --headed - -# See the HTML report after a run -npx playwright show-report +npx playwright test --grep @smoke # smoke only +npx playwright show-report # view results ``` +> **Note:** A few e2e test files still have `localhost:3001` URLs — pending cleanup, +> update to the staging/prod URL before running against live. + --- -## 6. Wire backend integration tests to CI +## 5. Backend integration tests (CI — already wired) -The 7 ai_credits integration tests in -`crates/db/tests/ai_credits.rs` need a real Postgres connection. - -### 6a. On the CI server / GitHub Actions - -Add a `TEST_DATABASE_URL` secret in your GitHub repo settings, then -add this to `.github/workflows/ci.yml`: - -```yaml -- name: Run backend integration tests - env: - TEST_DATABASE_URL: ${{ secrets.TEST_DATABASE_URL }} - run: | - cd nxtgauge-backend-rust - cargo test --test ai_credits -- --test-threads=1 -``` - -The `--test-threads=1` keeps the DB state predictable between tests. - -### 6b. Locally +The `nxtgauge_test` DB and Forgejo CI secret are already set up. +To run locally: ```bash export TEST_DATABASE_URL=postgres://user:pass@localhost:5432/nxtgauge_test @@ -188,42 +129,35 @@ cargo test --test ai_credits -- --test-threads=1 --- -## 7. Run the frontend linter (catches SolidJS reactivity bugs) +## 6. Frontend linter ```bash cd nxtgauge-frontend-solid npm run lint ``` -This runs `eslint-plugin-solid` which catches: -- Signals called outside reactive context (`solid/reactivity`) -- `.map()` in JSX instead of `` (`solid/prefer-for`) -- React-specific patterns used in Solid (`solid/no-react-specific-props`) - -All errors should be fixed before deploying. Warnings can be tracked. - --- -## 8. TypeScript check (zero errors currently) +## 7. TypeScript check ```bash cd nxtgauge-frontend-solid npx tsc --noEmit --skipLibCheck ``` -Should exit 0. Fix any errors before pushing to production. +Should exit 0. --- -## Summary — what's needed where +## Summary -| Task | Needs DB | Needs server | Where to run | +| Task | Needs DB | Needs server | Status | |---|---|---|---| -| Build + deploy backend | — | — | Server | -| Verify `/wallet/me/holds` | ✅ | ✅ | Server | -| `cargo audit` / `cargo deny` | — | — | Anywhere | -| Schemathesis fuzzing | ✅ | ✅ | Server / staging | -| Playwright e2e | ✅ | ✅ | Server / staging | -| Backend integration tests | ✅ | — | Server / CI | -| `npm run lint` | — | — | Anywhere | -| `tsc --noEmit` | — | — | Anywhere | +| DB migrations | ✅ | ✅ | ✅ Done (prod) | +| Build + deploy backend | — | — | Pending next release | +| `cargo audit` / `cargo deny` | — | — | Run anytime | +| Schemathesis fuzzing | ✅ | ✅ | Pending OpenAPI spec | +| Playwright e2e | ✅ | ✅ | Pending URL cleanup | +| Backend integration tests | ✅ | — | ✅ Green in CI | +| `npm run lint` | — | — | ✅ Passing | +| `tsc --noEmit` | — | — | Run anytime |