From caf6222d1d6de9ff59dae22e26ea348af82f9cdf Mon Sep 17 00:00:00 2001 From: Ian Monroe Date: Tue, 26 May 2026 14:51:28 +0000 Subject: [PATCH] IFDM-153: Set up a staging site --- docs/deployment.md | 107 ++++++++++++++++++++++++++++++++-------- next.config.ts | 2 +- package.json | 4 +- scripts/check-branch.js | 7 +-- 4 files changed, 95 insertions(+), 25 deletions(-) diff --git a/docs/deployment.md b/docs/deployment.md index caa38ff..a130a2f 100644 --- a/docs/deployment.md +++ b/docs/deployment.md @@ -1,43 +1,110 @@ -# Instructions for deployment and embedding +# Instructions for deployment and embedding -## Deployment +## Environments -The app deploys to https://ifdm-learning.stanford.edu/ via GitHub Pages and the `gh-pages` branch. The deploy script will automatically run the build step and generate the static files based on your local `1.x` branch code. Make sure you are on the latest `1.x` branch before deploying. +| Environment | Branch | URL | Command | +|---|---|---|---| +| Production | `1.x` | https://ifdm-learning.stanford.edu/ | `yarn deploy` | +| Staging | `dev` | https://su-sws.github.io/ifdm_learning_apps_staging/ | `yarn deploy:staging` | -### Deployment Steps +--- + +## Development workflow -1. Ensure you are on the latest `1.x` branch code: - - `git checkout 1.x && git fetch && git pull` -2. Make sure you are using the correct Node version: - - If you use nvm and are not already on the correct version, run: `nvm use` -3. (Optional) Test the build locally before deploying: - - `yarn build` -4. Deploy to GitHub Pages: - - `yarn deploy` -5. After deploying, verify the deployment: - - Visit https://github.com/SU-SWS/ifdm_learning_apps/deployments to confirm the deployment ran successfully. +Feature branches are developed and reviewed via pull request, then merged in two stages: + +``` +feature/my-branch → PR → dev → yarn deploy:staging → QA on staging + ↓ approved + PR to 1.x → yarn deploy → production +``` + +1. Open a PR from your feature branch targeting `dev` +2. After merge, deploy to staging and verify: `yarn deploy:staging` +3. Once staging is confirmed, open a PR from `dev` into `1.x` +4. After merge, deploy to production: `yarn deploy` --- -### Embedding a Calculator +## Deploying to production + +The deploy script enforces that you are on the `1.x` branch before building. + +1. Switch to the latest `1.x`: + ``` + git checkout 1.x && git fetch && git pull + ``` +2. Confirm the correct Node version is active: + ``` + nvm use + ``` +3. Deploy: + ``` + yarn deploy + ``` +4. Verify at https://github.com/SU-SWS/ifdm_learning_apps/deployments + +--- + +## Deploying to staging + +The staging deploy script enforces that you are on the `dev` branch before building. + +1. Switch to the latest `dev`: + ``` + git checkout dev && git fetch && git pull + ``` +2. Confirm the correct Node version is active: + ``` + nvm use + ``` +3. Deploy: + ``` + yarn deploy:staging + ``` +4. Verify at https://github.com/SU-SWS/ifdm_learning_apps_staging/deployments and preview at https://su-sws.github.io/ifdm_learning_apps_staging/ + +--- + +## One-time staging setup (already done — for reference) + +If the staging environment ever needs to be rebuilt from scratch: + +1. Create a new GitHub repo: `SU-SWS/ifdm_learning_apps_staging` +2. In that repo's Settings → Pages, set the source to the `gh-pages` branch +3. Add the staging remote to your local clone: + ``` + git remote add staging git@github.com:SU-SWS/ifdm_learning_apps_staging.git + ``` + Note: `yarn deploy:staging` targets this remote directly via `gh-pages -r`; the local remote entry is for reference and manual pushes only. + +--- + +## Embedding a calculator Example iFrame: -```angular2html +```html ``` + See below screencast as an example of embedding the iframe: ![Embedding Example](images/embedding-in-mighty.gif) +--- + ## Troubleshooting -### Changes Not Appearing +### Changes not appearing 1. Clear browser cache -2. Check GitHub Pages deployment status -3. Verify the gh-pages branch updated +2. Check GitHub Pages deployment status in the repo's Deployments tab +3. Verify the `gh-pages` branch updated with a recent commit + +### Staging assets not loading (404 on `/_next/` paths) +The staging build sets `basePath=/ifdm_learning_apps_staging` so all asset paths are prefixed correctly for the project URL. If you see 404s on static assets, confirm `build:staging` was used (not the plain `build` command). -### iframe Issues +### iframe issues - Ensure the source URL is correct - Check for CORS restrictions - Test the iframe URL directly in browser diff --git a/next.config.ts b/next.config.ts index 36a15be..520da8c 100644 --- a/next.config.ts +++ b/next.config.ts @@ -3,7 +3,7 @@ import type { NextConfig } from "next"; const nextConfig: NextConfig = { output: 'export', trailingSlash: true, - basePath: '', + basePath: process.env.NEXT_BASE_PATH || '', eslint: { // Directories to run ESLint on during builds dirs: ['app'], diff --git a/package.json b/package.json index aabc014..f4417f4 100644 --- a/package.json +++ b/package.json @@ -6,8 +6,10 @@ "dev": "next dev --turbopack", "build:local": "next build", "build": "echo \" \" > public/.nojekyll && next build && cp CNAME out/CNAME", - "predeploy": "node scripts/check-branch.js && yarn build", + "build:staging": "echo \" \" > public/.nojekyll && NEXT_BASE_PATH=/ifdm_learning_apps_staging next build", + "predeploy": "node scripts/check-branch.js 1.x && yarn build", "deploy": "gh-pages -d out", + "deploy:staging": "node scripts/check-branch.js dev && yarn build:staging && gh-pages -d out -r git@github.com:SU-SWS/ifdm_learning_apps_staging.git", "start": "next start", "lint": "next lint" }, diff --git a/scripts/check-branch.js b/scripts/check-branch.js index 9e40988..7f87ec1 100644 --- a/scripts/check-branch.js +++ b/scripts/check-branch.js @@ -1,11 +1,12 @@ const { execSync } = require('child_process'); +const allowedBranch = process.argv[2] || '1.x'; + try { const branch = execSync('git rev-parse --abbrev-ref HEAD', { encoding: 'utf8' }).trim(); - if (branch !== '1.x') { - console.error(`Build blocked on all branches but 1.x`); - console.error('Builds are not allowed on this branch.'); + if (branch !== allowedBranch) { + console.error(`Deploy blocked: must be on branch '${allowedBranch}' (currently on '${branch}').`); process.exit(1); } } catch (error) {