295 lines
7.8 KiB
Markdown
295 lines
7.8 KiB
Markdown
# HP CG Production Tracker — Development Setup
|
|
|
|
Cross-platform setup guide for macOS and Windows 11.
|
|
|
|
---
|
|
|
|
## Prerequisites
|
|
|
|
| Tool | Version | macOS | Windows |
|
|
|------|---------|-------|---------|
|
|
| Node.js | 22.x | `nvm install 22` | `nvm install 22` (nvm-windows) |
|
|
| npm | bundled with Node | Included | Included |
|
|
| PostgreSQL | 17.x | `brew install postgresql@17` | [Installer](https://www.postgresql.org/download/windows/) or `winget install PostgreSQL.PostgreSQL.17` |
|
|
| Git | any recent | Included with Xcode CLT | [git-scm.com](https://git-scm.com/download/win) |
|
|
|
|
### Node Version Manager
|
|
|
|
**macOS** — [nvm](https://github.com/nvm-sh/nvm):
|
|
```bash
|
|
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
|
|
```
|
|
|
|
**Windows** — [nvm-windows](https://github.com/coreybutler/nvm-windows):
|
|
Download the latest installer from the releases page and run it.
|
|
|
|
After installing nvm, the `.nvmrc` file in the project root specifies Node 22:
|
|
```bash
|
|
nvm install # reads .nvmrc automatically (macOS)
|
|
nvm use # switch to the project's Node version
|
|
```
|
|
|
|
On nvm-windows, specify the version explicitly:
|
|
```cmd
|
|
nvm install 22
|
|
nvm use 22
|
|
```
|
|
|
|
---
|
|
|
|
## 1. Clone the Repository
|
|
|
|
```bash
|
|
git clone <repo-url> hp_prod_tracker
|
|
cd hp_prod_tracker
|
|
```
|
|
|
|
---
|
|
|
|
## 2. Install Dependencies
|
|
|
|
```bash
|
|
npm install
|
|
```
|
|
|
|
This also runs `prisma generate` automatically via the postinstall hook, creating
|
|
the generated Prisma client at `src/generated/prisma/`.
|
|
|
|
If the generated client is missing for any reason:
|
|
```bash
|
|
npx prisma generate
|
|
```
|
|
|
|
---
|
|
|
|
## 3. Set Up PostgreSQL
|
|
|
|
### macOS (Homebrew)
|
|
|
|
```bash
|
|
brew install postgresql@17
|
|
brew services start postgresql@17
|
|
createdb hp_prod_tracker
|
|
```
|
|
|
|
The default Homebrew PostgreSQL setup uses your system username with no password.
|
|
|
|
### Windows
|
|
|
|
1. Install PostgreSQL 17 via the official installer or winget:
|
|
```cmd
|
|
winget install PostgreSQL.PostgreSQL.17
|
|
```
|
|
2. During installation, note the password you set for the `postgres` user.
|
|
3. Open **pgAdmin** or **psql** and create the database:
|
|
```sql
|
|
CREATE DATABASE hp_prod_tracker;
|
|
```
|
|
4. Optionally create a dedicated user:
|
|
```sql
|
|
CREATE USER leivur WITH PASSWORD 'your_password';
|
|
GRANT ALL PRIVILEGES ON DATABASE hp_prod_tracker TO leivur;
|
|
```
|
|
|
|
### Verify Connection
|
|
|
|
```bash
|
|
psql -h localhost -U leivur -d hp_prod_tracker
|
|
# or on Windows if using postgres user:
|
|
psql -h localhost -U postgres -d hp_prod_tracker
|
|
```
|
|
|
|
---
|
|
|
|
## 4. Configure Environment Variables
|
|
|
|
Create a `.env` file in the project root (this file is gitignored):
|
|
|
|
```env
|
|
# ─── Database ────────────────────────────────────────────
|
|
# macOS (Homebrew, no password):
|
|
DATABASE_URL="postgresql://leivur@localhost:5432/hp_prod_tracker?schema=public"
|
|
|
|
# Windows (with password):
|
|
# DATABASE_URL="postgresql://leivur:your_password@localhost:5432/hp_prod_tracker?schema=public"
|
|
|
|
# ─── Auth (Dev Bypass) ──────────────────────────────────
|
|
# Skips SSO and uses a seeded dev user. Set to "false" or remove for production SSO.
|
|
DEV_BYPASS_AUTH="true"
|
|
DEV_USER_ID="dev-user-001"
|
|
|
|
# ─── Auth (Production SSO — optional for local dev) ─────
|
|
# AUTH_GOOGLE_ID=""
|
|
# AUTH_GOOGLE_SECRET=""
|
|
# AUTH_MICROSOFT_ENTRA_ID_ID=""
|
|
# AUTH_MICROSOFT_ENTRA_ID_SECRET=""
|
|
# AUTH_MICROSOFT_ENTRA_ID_TENANT_ID=""
|
|
|
|
# ─── NextAuth ───────────────────────────────────────────
|
|
NEXTAUTH_SECRET="any-random-string-change-in-production"
|
|
NEXTAUTH_URL="http://localhost:3000"
|
|
```
|
|
|
|
---
|
|
|
|
## 5. Initialize the Database
|
|
|
|
Push the Prisma schema to the database and run the seed script:
|
|
|
|
```bash
|
|
npx prisma db push
|
|
npx prisma db seed
|
|
```
|
|
|
|
`db push` creates all tables from `prisma/schema.prisma`.
|
|
|
|
`db seed` populates:
|
|
- 10 pipeline stage templates with dependency rules
|
|
- Dev organization (id: `dev-org-001`)
|
|
- Dev admin user (id: `dev-user-001`, email: `dev@localhost`)
|
|
|
|
To inspect the database visually:
|
|
```bash
|
|
npx prisma studio
|
|
```
|
|
|
|
---
|
|
|
|
## 6. Start the Dev Server
|
|
|
|
```bash
|
|
npm run dev
|
|
```
|
|
|
|
Open [http://localhost:3000](http://localhost:3000). With `DEV_BYPASS_AUTH="true"`, you'll
|
|
be logged in automatically as the dev admin user.
|
|
|
|
---
|
|
|
|
## Available Scripts
|
|
|
|
| Script | Command | Description |
|
|
|--------|---------|-------------|
|
|
| Dev server | `npm run dev` | Start Next.js with Turbopack |
|
|
| Build | `npm run build` | Production build |
|
|
| Start | `npm start` | Run production build |
|
|
| Lint | `npm run lint` | ESLint check |
|
|
| Format | `npm run format` | Prettier format all files |
|
|
| Format check | `npm run format:check` | Prettier check (no write) |
|
|
| Generate client | `npm run db:generate` | Regenerate Prisma client |
|
|
| Push schema | `npm run db:push` | Sync schema to database (no migration files) |
|
|
| Seed | `npm run db:seed` | Run seed script |
|
|
| Studio | `npm run db:studio` | Open Prisma Studio GUI |
|
|
|
|
---
|
|
|
|
## Platform-Specific Notes
|
|
|
|
### macOS
|
|
|
|
- **nvm**: Must be sourced in each shell session. If `node` isn't found, run:
|
|
```bash
|
|
export NVM_DIR="$HOME/.nvm" && [ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
|
|
```
|
|
This is typically added to `~/.zshrc` automatically by the nvm installer.
|
|
|
|
- **PostgreSQL service**: Start/stop with Homebrew:
|
|
```bash
|
|
brew services start postgresql@17
|
|
brew services stop postgresql@17
|
|
```
|
|
|
|
### Windows
|
|
|
|
- **nvm-windows**: Requires an elevated (admin) terminal for `nvm install` and `nvm use`.
|
|
|
|
- **PostgreSQL service**: Runs as a Windows service by default. Manage via Services app
|
|
or:
|
|
```cmd
|
|
net start postgresql-x64-17
|
|
net stop postgresql-x64-17
|
|
```
|
|
|
|
- **Line endings**: Git should handle CRLF/LF conversion automatically. If you see
|
|
formatting issues, verify your Git config:
|
|
```cmd
|
|
git config --global core.autocrlf true
|
|
```
|
|
|
|
- **Terminal**: PowerShell, Windows Terminal, or Git Bash all work. The npm scripts are
|
|
cross-platform.
|
|
|
|
---
|
|
|
|
## Switching Between Machines
|
|
|
|
The workflow for moving between macOS and Windows:
|
|
|
|
1. **Commit and push** from the current machine:
|
|
```bash
|
|
git add -A && git commit -m "WIP" && git push
|
|
```
|
|
|
|
2. **Pull on the other machine**:
|
|
```bash
|
|
git pull
|
|
npm install # in case dependencies changed
|
|
npx prisma db push # in case schema changed
|
|
npm run dev
|
|
```
|
|
|
|
The `.env` file is gitignored, so each machine maintains its own database connection
|
|
string and auth settings. The database content is local to each machine — use
|
|
`npx prisma db seed` to reset to baseline data on a fresh setup.
|
|
|
|
---
|
|
|
|
## Troubleshooting
|
|
|
|
### `prisma generate` fails
|
|
Ensure Node 22 is active (`node -v`) and `npm install` completed successfully.
|
|
The generated client at `src/generated/prisma/` is gitignored and must be generated
|
|
locally.
|
|
|
|
### Database connection refused
|
|
- Verify PostgreSQL is running (`brew services list` on macOS, `services.msc` on Windows)
|
|
- Check `DATABASE_URL` in `.env` matches your local PostgreSQL user/password/port
|
|
|
|
### Port 3000 already in use
|
|
```bash
|
|
# macOS
|
|
lsof -ti:3000 | xargs kill
|
|
# Windows
|
|
netstat -ano | findstr :3000
|
|
taskkill /PID <pid> /F
|
|
```
|
|
|
|
### Schema out of sync after git pull
|
|
```bash
|
|
npx prisma db push # applies any schema changes
|
|
npx prisma generate # regenerates the client types
|
|
```
|
|
|
|
### nvm: command not found (macOS)
|
|
Add to `~/.zshrc`:
|
|
```bash
|
|
export NVM_DIR="$HOME/.nvm"
|
|
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
|
|
```
|
|
|
|
---
|
|
|
|
## Tech Stack Quick Reference
|
|
|
|
| Layer | Technology |
|
|
|-------|-----------|
|
|
| Framework | Next.js 16 (App Router, Turbopack) |
|
|
| Language | TypeScript 5.x |
|
|
| Styling | Tailwind CSS 4 |
|
|
| Components | shadcn/ui (Radix + Tailwind) |
|
|
| Database | PostgreSQL 17 + Prisma 7 |
|
|
| Auth | Auth.js v5 (Google + Microsoft SSO) |
|
|
| State | TanStack Query v5 + Zustand |
|
|
| Forms | React Hook Form + Zod v4 |
|
|
| Charts | Recharts |
|
|
| Icons | Lucide React |
|