Deployment Flow

This guide describes how projects in the practicum should be deployed, even though we do not currently deploy automatically via CD pipelines. The goal is to prepare student teams to deploy safely, consistently, and with clear documentation for future cohorts.

Deployment is about more than pushing code live — it requires infrastructure, secrets, permissions, and reproducibility.

---

When Students Should Deploy

Deployments should only be performed by:

Role	Deployment Permission
Professor / TPM	Full admin access
Lead Engineers	Temporary deploy access
PMs (when approved)	May assist with secrets & environment setup
Students / Contributors	No deployment permission

Deployment decisions must be approved by:

• The TPM, and
• The instructor

Deployment is never automatic and must be intentional. (for now)

---

Supported Deployment Approaches

The practicum projects may be deployed using manual cloud hosting and/or managed static hosting.

Tech	Deployment Style	Common Hosts
Next.js / React	Static or Node-hosted	Vercel, Netlify, Railway
NestJS / Node APIs	Persistent backend service	Render, Railway, AWS
Databases	Managed cloud DB	Supabase, Railway, Neon, ElephantSQL
Small apps / utilities	Lightweight deploy	GitHub Pages, Cloudflare Pages

Each project must document:

• which host is chosen
• how to deploy
• who has access

No deployment without documentation.

---

Required Preparations Before Deployment

Before deploying, teams must complete:

✔ 1) Create a Production Build

npm run build

✔ 2) Create an .env.example File

This shows required environment variables without exposing credentials.

✔ 3) Document the Deployment in the Repo

In README.md, include:

• Hosting service used
• Deployment steps
• Required environment variables
• Rollback steps

✔ 4) TPM/Instructor Approves Deployment

Deployment must be requested, not assumed.

---

Standard Deployment Checklist (For Students)

Before deployment can occur, students must provide:

Requirement	Description
Production Build Verified	npm run build must succeed
Required Env Vars Listed	In .env.example
Secrets Documented	In a secure channel, not in repo
No Local-Only Data	Test accounts, no personal data
README Deployment Section	Instructions clear and reproducible
Rollback Plan	How to revert to previous version

If any part is missing, deployment is postponed.

---

High-Level Manual Deployment Flow

Click to Expand Deployment Steps

1) TPM/Instructor Selects Hosting Provider

Choice depends on cost, traffic, longevity, and DB needs.

2) Lead Engineers Receive Temporary Access

Access is never permanent and expires after project completion.

3) Environment Variables Added Securely

Secrets are entered into:

• Cloud host environment variable panel
• Never committed to the repo
• Shared only by secure message, not Slack channels

4) Deploy and Validate Build

Deploy manually through the hosting interface, then:

• Visit public URL
• Test authentication (if applicable)
• Test critical routes/services/API endpoints

5) Document the Deployment in README & Wiki

Must include:

• Hosting service
• Secrets required
• Deployment steps
• How to rollback

6) Remove Access from Students After Semester

Only TPM and Instructor maintain ongoing control.

---

Rollback Expectations

Deployments must be reversible. A rollback plan must include:

Requirement	Example
Previous stable build	Store build artifact or previous commit
DB backup before deploy	Export/backup with timestamp
Steps to redeploy old version	Document re-deploy instructions
Access to logs	From hosting provider
Responsible roles	Who performs rollback?

Rollback documentation is part of a professional deployment, not optional.

---

Deployment Must Be Documented Per Repo

Each deployed project must contain:

📌 Deployment Section in README.md
📌 .env.example file
📌 Hosting provider chosen + account owner
📌 Rollback instructions
📌 Access list (who has deploy rights and expiration date)

The goal is reproducible deployments, not one-time student experiments.

---