From e31014d45c6e555bcd16618043fc96a412b3c37f Mon Sep 17 00:00:00 2001 From: Hardik Date: Fri, 19 Jun 2026 12:07:55 +0530 Subject: [PATCH] docs: document the issue-to-deploy pipeline, staging, and test DB - App/README.md: add FORGEJO_*/NEXT_PUBLIC_ENV_LABEL env vars and an 'Operations & Automation' section pointing to automation/README.md. - App/CLAUDE.md: complete the env var list (AZURE_AD_*, FORGEJO_*, GST_SERVICE_URL, NEXT_PUBLIC_ENV_LABEL) and note the prod-mirror test DB used by autofix/staging. - .env.example: document NEXT_PUBLIC_ENV_LABEL. Co-Authored-By: Claude Opus 4.8 --- App/.env.example | 5 +++++ App/CLAUDE.md | 24 ++++++++++++++++++++++++ App/README.md | 30 ++++++++++++++++++++++++++++++ 3 files changed, 59 insertions(+) diff --git a/App/.env.example b/App/.env.example index 3001b4b..a22649f 100644 --- a/App/.env.example +++ b/App/.env.example @@ -54,3 +54,8 @@ GST_SERVICE_URL=http://localhost:3003 FORGEJO_URL=https://git.pelagiamarine.com FORGEJO_REPO=shad0w/pelagia-portal FORGEJO_TOKEN= + +# ── Non-production banner ───────────────────────────────────── +# When set, a fixed "internal dev / staging" banner is shown (EnvBanner). +# Leave UNSET in production. Staging sets this automatically. +# NEXT_PUBLIC_ENV_LABEL="INTERNAL DEV / STAGING - NOT PRODUCTION" diff --git a/App/CLAUDE.md b/App/CLAUDE.md index c9b64ad..af0739a 100644 --- a/App/CLAUDE.md +++ b/App/CLAUDE.md @@ -95,7 +95,31 @@ NEXTAUTH_SECRET # Required always NEXTAUTH_URL # Required always (e.g., http://localhost:3000) DATABASE_URL # PostgreSQL connection string +AZURE_AD_CLIENT_ID, AZURE_AD_CLIENT_SECRET, AZURE_AD_TENANT_ID + # Microsoft Entra SSO (prod). auth.ts reads them at module + # load — set placeholders in non-SSO/dev envs so it boots. + # Optional in dev (defaults to local storage + console email): R2_ACCOUNT_ID, R2_ACCESS_KEY_ID, R2_SECRET_ACCESS_KEY, R2_BUCKET_NAME, R2_PUBLIC_URL RESEND_API_KEY, EMAIL_FROM, EMAIL_FROM_NAME + +# Report Issue button (lib/forgejo.ts); token needs write:issue: +FORGEJO_URL, FORGEJO_REPO, FORGEJO_TOKEN + +GST_SERVICE_URL # GstService microservice (defaults to localhost:3003) +NEXT_PUBLIC_INVENTORY_ENABLED # Inventory feature flag +NEXT_PUBLIC_ENV_LABEL # When set, shows a non-prod banner (EnvBanner). Leave unset in prod. ``` + +### Operations & automation + +This repo runs a self-hosted issue-to-deploy pipeline on the `pms1` server (Forgejo + +headless Claude Code). See [`../automation/README.md`](../automation/README.md). Relevant +when working in this codebase: + +- The **Report Issue** button (portal header) files a Forgejo issue; a watcher triages it + and, for auto-fixable ones, implements a fix and opens a PR. Deploys are gated on a + human merging the PR and pushing a `vX.Y.Z` tag. +- Automated fixes and the **staging** instance run against `pelagia_test`, a **daily mirror + of the production database**, in dev mode (console email, local storage). Migrations are + applied to it, so its schema tracks `master`. Never assume an empty DB — it holds prod-like data. diff --git a/App/README.md b/App/README.md index 5bedfef..6baba01 100644 --- a/App/README.md +++ b/App/README.md @@ -116,6 +116,15 @@ R2_PUBLIC_URL=https://..r2.cloudflarestorage.com RESEND_API_KEY=re_ EMAIL_FROM=noreply@yourdomain.com EMAIL_FROM_NAME="Pelagia Portal" + +# Report Issue button -> files a Forgejo issue (optional; token needs write:issue) +FORGEJO_URL=https://git.example.com +FORGEJO_REPO=owner/repo +FORGEJO_TOKEN= + +# Non-prod banner (leave UNSET in production). When set, a fixed +# "INTERNAL DEV / STAGING - NOT PRODUCTION" banner is shown. +# NEXT_PUBLIC_ENV_LABEL="INTERNAL DEV / STAGING - NOT PRODUCTION" ``` ### 2. Run database migrations @@ -135,6 +144,27 @@ The app listens on port 3000 by default. Point your reverse proxy (nginx, Caddy, --- +## Operations & Automation + +This repo carries its own self-hosted **issue-to-deploy pipeline** (Forgejo + Claude Code +on the `pms1` server). The full design and runbook live in +**[`../automation/README.md`](../automation/README.md)**. In short: + +- **Report Issue button** (portal header) files a Forgejo issue tagged `portal`. +- A **watcher** triages each issue (Claude posts a requirements breakdown and routes it + to `claude-queue` or `interactive`), then for queued issues implements a fix and opens a PR. +- Merging a PR and pushing a **release tag (`vX.Y.Z`)** triggers a Forgejo Actions runner + that deploys to production. +- A **staging instance** (`automation/staging-up.sh`, pm2 `ppms-staging` on port 3200, + SSH-tunnel only) runs the latest `master` against a daily **prod-mirror test DB** + (`pelagia_test`) for smoke testing before tagging a release. + +Operational scripts live under [`../automation/`](../automation/): `claude-issue-watcher.sh` +(watcher), `refresh-test-db.sh` (nightly test-DB refresh), `staging-up.sh` (staging), +and `staging-tunnel.cmd` (Windows tunnel launcher). + +--- + ## Database Management | Command | Purpose |