IFDM-153: Set up a staging site

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
 <iframe src="https://ifdm-learning.stanford.edu/interactives/investment-calculator/"></iframe>
 ```
+
 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

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'],

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"
   },

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) {